NAME

Module::Case - Case sensitive module loading.

SYNOPSIS

# Specify which modules you wish to force the case
# to match exactly if ever loaded in the future
use Module::Case qw(Config config);

# Load only Config.pm starting with CAPITAL C
# even on case-insensitive file systems and
# even if lowercase config.pm is earlier in the @INC.
use Config;

# Now load only the lowercase file
use config;

DESCRIPTION

This module was created to alleviate the problems caused by case-ignorant or case-insensitive file systems or operating systems such as Windows or OSX when attempting to load a module that doesn't exactly match the case.

This is especially troublesome when there are two different modules within the @INC that are case-insensitively similar. It becomes very difficult to load the one that comes later in the @INC because it will always get snagged on the first one.

Using this module can force a module to load ONLY if the case matches exactly, just as if the file system containing the module were case-sensitive.

Module::Case is efficient enough to run in production.

IMPLEMENTATION

This modules injects a special CODEREF at the beginning of @INC that performs a pre-check on each matching file within @INC to ensure the case is exactly correct instead of allowing Perl to blindly compile any file that smells like the module wishing to load.

If the specified module doesn't exactly match the case of how it was requested, then the "require" or "use" will die with an error instead of gleefully loading any case-insensitively matching module.

CAVEATS

The module being loaded must contain the exact string of the package matching what has been flagged for sensitively. For example:

use Module::Case qw(Exact::Module::Name);
use Exact::Module::Name;
# -or-
require Exact::Module::Name;

Then the contents of "Exact/Module/Name.pm" must contain "package Exact::Module::Name" somewhere in the pm file or else it should fail to load.

If there are multiple different modules that match case-insensitvely and you wish to load more than one of these, then it would be safer to specify ALL of these variations in the import line, such as:

use Module::Case qw(cwd Cwd);
use cwd;
use Cwd;

This is because once a case-sensitive module is loaded successfully, then it is immediately removed from the import whitelist. Technically, you only need to specify the module that isn't matched first in the @INC, but if this order ever changes in the future, then it will still incorrectly load the FIRST case-insensitive match in @INC.

AUTHOR

Rob Brown <bbb@cpan.org>

SEE ALSO

Similar behavior to Acme::require::case but using an alternate implementation which makes Module::Case quite fast and Module::Case doesn't require any dependencies.