NAME

optional - Pragma to optionally load a module (or pick from a list of modules) and provide a constant and some tools for taking action depending on if it loaded or not.

DESCRIPTION

Helps write code that has optional dependencies. Will load (or not load) the module, then provide you with some tools that help you write logic that depends on the result.

If a module fails to load for any reason other than its absence then the exception will be rethrown to show the error.

SYNOPSIS

    # Will try to load Optional::Module::Foo, naming tools with the 'opt_foo' name
    use optional opt_foo => qw/Optional::Module::Foo/;

    # Will try to load Optional::Module::Bar first, but will fallback to
    # Optional::Module::Foo if the first is not installed.
    use optional opt_any => qw/Optional::Module::Bar Optional::Module::Foo/;

    # You get a constant (capitlized version of name) that you can use in conditionals
    if (OPT_FOO) { ... }

    # The constant will return the module name that was loaded, if any, undef
    # if it was not loaded.
    if (my $mod = OPT_FOO) { ... }

    # Quickly write code that will only execute if the module was loaded
    # If the module was not loaded this always returns undef, so it is safe to
    # use in a hash building list.
    my $result = if_opt_foo { ... };

    # Quickly write code that will only execute if the module was NOT loaded If
    # the module was loaded this always returns undef, so it is safe to use in
    # a hash building list.
    my $result = unless_opt_foo { ... };

    sub feature_that_requires_foo {
        need_opt_foo();                                       # Throws an error telling the user they need to install Optional::Module::Foo to use this feature
        need_opt_foo(feature => 'widget');                    # Same, but names the feature
        need_opt_foo(trace   => 1);                           # Add a stack trace
        need_opt_foo(message => ...);                         # Write a custom message
        need_opt_foo(message => ..., append_modules => 1);    # Write a custom message, and add the module/s that need to be installed
    }

EXPORTS

For each use of this module you will get 4 subs exported into your namespace, all contain the NAME intially provided.

$module_or_undef = NAME()

All caps version of the name. It is a constant, it always returns either the used modules name, or undef if the optional module is not installed.

$res = if_NAME { ... }

Run a block if the module was installed and loaded. Returns undef if the module was not loaded, otherwise it returns what your sub returns.

$res = unless_NAME { ... }

Run a block if the module was NOT installed and loaded. Returns undef if the module was loaded, otherwise it returns what your sub returns.

need_NAME()

need_NAME(message => $MSG, trace => $BOOL, append_modules => $BOOL, feature => $FEATURE_NAME)

No-op if the module was loaded.

If the module was not loaded it will throw an exception like this:

    "You must install one of the following modules to use this feature [Module::A]\n"
    "You must install one of the following modules to use this feature [Preferred::Module, Backup::Module]\n"

You can also specify a feature name for a message like:

    "You must install one of the following modules to use the 'My Feature' feature [Module::A]\n"

You can also add a custom message, and optionally append the module names by setting append_modules to true.

In all forms you can set trace to true to use confess for a stack trace.

SOURCE

The source code repository for 'optional' can be found at https://github.com/exodist/optional/.

MAINTAINERS

Chad Granum <exodist@cpan.org>

AUTHORS

Chad Granum <exodist@cpan.org>

COPYRIGHT

Copyright Chad Granum <exodist7@gmail.com>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://dev.perl.org/licenses/