NAME

Detect::Module - allows to autodetect Perl modules

SYNOPSIS

    use Detect::Module qw(:standard);

    my $which = Use 'DB_File', 'SDBM_File';
    # $which now contains the name of the loaded module
    # This is specially useful because the modules have
    # a compatible tie() syntax

    my $constructor = NewRef 'IO::Socket::COOL', 'IO::Socket::INET';
    my $o = $constructor->(PeerAddr => 'localhost:25');
    # $o now contains an object of one of the both modules

    my $esc = Load 'URI::Escape';
    $esc->uri_escape (' ') eq '%20';
    ${$esc->('SCALAR', 'x')} = 3;

DESCRIPTION

This module is used for autodetection of Perl modules. The functions in this module accept a list of module names, from which the first one that can be loaded using require() is used.

USAGE

You may include most functions using the export tag ':standard' like shown in the synopsis. Otherwise you call them like Detect::Module::Use(). Only Debug() and Reset() cannot be exported.

Use @ModuleList, Require @ModuleList

These work like require() except they are executed at run time and all modules in @ModuleList are tried until an existing module is found. If no such module exists, these subs die(). The modules in the list are tried from left to right. Module names have to contain :: as path separator. Of course the @INC path is used to find the modules (the built-in require() is used to load the modules).

There is no difference between Use() and Require(). To achieve compile-time execution, enclose the Use() call in a BEGIN block.

The return value is the name of the module that has been loaded.

Once loading a module has failed, it is never tried again. So using these subs multiple times does not result in performance impacts (Perl checks if a module is already loaded). But you should use this to access multiple functions of this package:

    # Load the module
    my $mod = Use (...);
    # I need the object:
    my $obj = Load $mod;
    # This does not have performance impacts because $mod is already
    # loaded and Perl checks %INC!

You can circumvent this behaviour by calling Detect::Module::Reset which clears the %FAIL-Cache.

There is a trick to catch cases where a module is _not_ found:

    # Try loading
    unless (my $mod = Use (..., 0))
    {
     print "Module not found\n";
     print "Using workaround instead...\n";
    }

This relies upon the fact that a require 0 always succeeds. But this works only with Use(), Require() and Load()!

NewRef @ModuleList

This one works exactly like Use() except that a reference to the constructor (or better: to a sub that calls the module's constructor) is returned. The returned sub reference calls new Module::Name @_, where Module::Name is the name of the module loaded.

Load @ModuleList

This one returns a blessed object with the following capabilities:

$o->(SCALAR => 'x') returns a reference to $x of the module.
$o->(ARRAY => 'x') returns a reference to @x of the module.
$o->(HASH => 'x') returns a reference to %x of the module.
$o->(CODE => 'x') returns a reference to &x of the module.
$o->(CODECHECK => 'x') returns a reference to &x of the module, or undef if &x does not exist.
$o->(GLOB => 'x') returns a reference to *x of the module. HANDLE is a synonym to GLOB.
$o->m(@args) calls the function m() of the module with @args.

CHANGED since Detect::Module version 1.2: Load() now returns undef if no module was found and '0' was a possible name.

Debug $Flag

Debugging output is switched on when $Flag is true. Debugging output is printed on STDERR and consists of lines like:

'Trying Module::Name'
'x; `rm -rf /` rejected - invalid characters'
the $@ contents after a failed require()

Reset

Clears the hash %FAIL which contained all failed require() attempts. This may be useful when using mod_perl in Apache.

AUTHOR

Written by Rudolf Polzer, Germany (rpolzer@durchnull.de)

KNOWN BUGS

Load() uses symbolic references (therefore I use no strict 'subs'). Doing the same with eval() leads to more obfuscated code.
The sub returned by Load() return references instead of tied variables. This makes accessing package variables harder, but not impossible.
You cannot directly call AUTOLOAD() using the object returned by Load(). Use $o->(CODE => 'AUTOLOAD')->(@args) instead.
When calling an undefined sub using the object returned by Load(), you can get error messages without line numbers and package names (so you do not know where the error occured). This only happens when you call the undefined sub from the main program, not from a sub.

REPORTING BUGS or FIXING THE ONES ABOVE

Report bugs to me (rpolzer@durchnull.de)

COPYRIGHT

(c) 2001 Rudolf Polzer. This is free software, copying and modifications are allowed as long as this copyright notice remains. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.