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 module "Bar". You actually quite like
    "Bar", and want to reuse its functionality in your "Foo" module. But,
    many people will refuse to install "Foo" as it needs "Bar". Maybe "Bar"
    is failing tests or is misbehaving on some platforms.

    Making "Bar" an optional module will allow users to run "Foo" that don't
    have "Bar" installed. For Module::Build users, this involves changing
    the status of the "Bar" dependency from "requires" to "recommends".

    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 for
    "Params::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.

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
    Test::MockModule, Module::Pluggable, Module::Build.