-
-
19 May 2008 21:47:27 UTC
- Distribution: Module-Optional
- Module version: 0.03
- Source (raw)
- Browse (raw)
- Changes
- How to Contribute
- Issues (0)
- Testers (3100 / 0 / 0)
- Kwalitee
Bus factor: 0- 88.14% Coverage
- License: perl_5
- Activity
24 month- Tools
- Download (14.01KB)
- MetaCPAN Explorer
- Permissions
- Subscribe to distribution
- Permalinks
- This version
- Latest version
and 1 contributors- Ivor Williams ()
- Dependencies
- Test::Simple
- and possibly others
- Reverse dependencies
- CPAN Testers List
- Dependency graph
NAME
Module::Optional - Breaking module dependency chains
SYNOPSIS
use Bar::Dummy qw(); use Module::Optional Bar;
ABSTRACT
This module provides a way of using a module which may or may not be installed on the target machine. If the module is available it behaves as a straight use. If the module is not available, subs are repointed to their equivalents in a dummy namespace.
DESCRIPTION
Suppose you are the developer of module
Foo
, which uses functionality from the highly controversial moduleBar
. You actually quite likeBar
, and want to reuse its functionality in yourFoo
module. But, many people will refuse to installFoo
as it needsBar
. MaybeBar
is failing tests or is misbehaving on some platforms.Making
Bar
an optional module will allow users to runFoo
that don't haveBar
installed. For Module::Build users, this involves changing the status of theBar
dependency fromrequires
torecommends
.To use this module, you need to set up a namespace
Bar::Dummy
. The recommended way of doing this is to ship lib/Bar/Dummy.pm with your module. This could be shipped as a standalone module. A dummy module forParams::Validate
is shipped with Module::Optional, as this was the original motivation for the module. If there are other common candidates for dummying, petition me, and I'll include them in the Module::Optional distribution.Using an optional module
Place the lines of code in the following order:
use Bar::Dummy qw(); use Module::Optional qw(Bar quux wibble wobble);
Always set up the dummy module first, but don't import anything - this is to avoid warnings about redefined subroutines if the real Bar is installed on the target machine. Module::Optional will do the importing: quux wibble and wobble from the real Bar if it exists, or from Bar::Dummy if it doesn't.
Asking for a module version
If you need a version of the module or later, this can be done thus:
use Bar::Dummy qw(); use Module::Optional qw(Bar 0.07 quux wibble wobble);
If version 0.07 or later of Bar is not available, the dummy is used.
Suppressing the module
You will probably be developing your module on a platform that does have Bar installed (I hope). However, you need to be able to tell what happens on systems without Bar. To do this, run the following (example is Unix):
MODULE_OPTIONAL_SKIP=1 make test
You also want to do this in tests for the dummy module that you are providing. (You are providing tests for this module?) This can easily be done with a begin block at the top of the test:
BEGIN { local $ENV{MODULE_OPTIONAL_SKIP} = 1; use Module::Optional qw(Params::Validate); }
Writing a ::Dummy Module
You provide a namespace suffixed with ::Dummy containing subs corresponding to all the subs and method calls for the optional module. You should also provide the same exports as the module itself performs.
Adhere strictly to any prototypes in the optional module.
An example of a dummy module is Params::Validate::Dummy, provided in this distribution.
INTERNALS
Module::Optional performs two types of redirection for the missing module. Firstly via @ISA inheritance - Foo::Bar inherits from Foo::Bar::Dummy.
Secondly, an AUTOLOAD method is added to Foo::Bar, which will catch calls to subs in this namespace.
BUGS
Please report bugs to rt.cpan.org by posting to bugs-module-optional@rt.cpan.org or visiting https://rt.cpan.org/Public/Dist/Display.html?Name=Module-Optional.
AUTHOR
Ivor Williams ivorw-mod-opt at xemaps.com
COPYRIGHT
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included with this module.
SEE ALSO
Module Install Instructions
To install Module::Optional, copy and paste the appropriate command in to your terminal.
cpanm Module::Optional
perl -MCPAN -e shell install Module::Optional
For more information on module installation, please visit the detailed CPAN module installation guide.