NAME

Module::Stubber - Import possibly unavailable modules and their exported symbols as stub functions, objects, and methods

SYNOPSIS

    use Module::Stubber 'Possibly::Unavailable::Module' => [qw(some symbols)];
    
    some();
    symbols();
    
    my $maybe_dummy = Possibly::Unavailable::Module->new();
    $maybe_dummy->anything();
    

DESCRIPTION

Module::Stubber lets you create dummy stubs for modules which may not be importable, either because they are not a hard dependency for your code, or they do not function correctly on the target platform.

The proper usage for Module::Stubber is

    use Module::Stubber $module_name => $import_spec, other => options;
    

Thus, assuming the module My::Foo is installed, calling

    use Module::Stubber 'My::Foo' => [(foo_frob foo_bork)];
    

is equivalent to

    use My::Foo qw(foo_frob foo_bork);
    

OPTIONS

The following options are currently supported, and may be passed as hash keys after the import spec

will_use

will_use allows for extended symbol specifications if the module is not available.

It can take one of two value types:

Array Reference

This is a simple list of symbol names to append to the stub's functions.

Hash Reference

This is a more detailed specification of symbols, and will let you specify a default value or replacement subroutine for each symbol listed.

    use Module::Stubber
        'My::Foo' => [qw(foo_frob foo_bork)],
        will_use => {
            foo_frob => 42,
            foo_bork => sub {
                warn("We're already borked!")
            }
        };
    
    my $answer_to_everything = foo_frob(); # 42
    foo_bork(); # prints a warning
    

silent

Set this to true to disable printing initial warning messages when stubs are used in code. See "Warning Messages" for more information.

MISCELLANY

Warning Messages

The stub methods and functions created will print a warning message that looks something like

    *** '%s' requested at %s:%d
    *** This symbol does not really exist, and has been
    *** implemented as a stub by Module::Stubber.
    *** Depending on how important
    *** this function is, this program may not function
    *** correctly. This message will only display once.

only once.

The message is a package variable found at $Module::Stubber::Stub::MSG_FMT. It is a format string; the first parameter is the function name, the second is the filename of the caller of this function, and the third is the line number.

The printing of this message is dependent on another package-level hash, %Module::Stubber::Sub::Warncache.

Often it is desirable to have these messages print, but this may sometimes be impractical, especially for many methods. To silence the initial printing, simply place a hash entry under those method names - which must be fully qualified.

Module Load Status

You can check to see if a real module loaded successfully by inspecting the %Module::Stubber::Status hash. Keys are module names, and values are true or false, depending on whether the module was loaded or not.

RATIONALE

There are quite a few 'see if this module exists' handlers on CPAN. None of them (to my knowledge) allow you to actually do the hard part and specify stub replacements.

I wrote this module because I needed a way to include debugging/development modules on a project of mine, while being able to test core functionality on other systems which did not/could not have those development modules installed.

This module can become quite handy when the core purpose of the modules being used are mainly informative and with a simple API. For more complicated scenarios when the functionality of the desired module is actually needed, you might want to consider maybe, if, and first, and others.

SEE ALSO

maybe

if

Module::Load::Conditional

Package::Butcher - Provides a different and more comprehensive API

AUTHOR AND COPYRIGHT

Copyright (C) 2011 M. Nunberg

You may use and distribute this module under the same terms as Perl itself.