view release on metacpan or  search on metacpan

README.mkdn  view on Meta::CPAN

# NAME

Extorter - Import Routines By Any Means Necessary

# VERSION

version 0.10

# SYNOPSIS

    use Extorter qw(

        *utf8
        *strict
        *warnings

        feature^say
        feature^state

        Carp::croak
        Carp::confess

        Data::Dump::dump

        Digest::SHA1::sha1_hex
        Digest::SHA1::sha1_base64

        Encode::encode_utf8
        Encode::decode_utf8

        IO::All::io

        List::AllUtils::distinct
        List::AllUtils::firstval
        List::AllUtils::lastval
        List::AllUtils::pairs
        List::AllUtils::part
        List::AllUtils::uniq

        Memoize::memoize

        Scalar::Util::blessed
        Scalar::Util::refaddr
        Scalar::Util::reftype
        Scalar::Util::weaken

    );

# DESCRIPTION

The Extorter module allows you to create import lists which extract routines
from the package(s) specified. It will import routines found in the package
variables `@EXPORT`, `@EXPORT_OK` and `%EXPORT_TAGS`, or, extract routines
defined in the package which are not explicitly exported. Otherwise, as a last
resort, Extorter will try to load the package, using a parameterized `use`
statement, in the event that the package has a custom or magical importer that
does not conform to the [Exporter](https://metacpan.org/pod/Exporter) interface.

Extorter accepts a list of fully-qualified declarations. The verbosity of the
declarations are meant to promote explicit, clean, and reasonable import lists.
Extorter has the added bonus of extracting functionality from packages which may
not have originally been designed to be imported. Declarations are handled in
the order in which they're declared, which means, as far as the import and/or
extraction order goes, the last routine declared will be the one available to
your program and any `redefine` warnings will be suppressed. This is a feature
not a bug. **NOTE: Any declaration prefixed with an asterisk is assumed to be a
fully-qualified namespace of a package and is imported directly.**

# FEATURES AND VERSIONS

Declaring version requirements and version-specific features is handled a bit
differently. As mentioned in the description, any declaration prefixed with an
asterisk is assumed to be a fully-qualified namespace of a package and is
imported directly. This works for modules as well as pragmas like `strict`,
`warnings`, `utf8`, and others. However, this does not work for declaring a
Perl version or version-specific features. Currently, there is no single
declaration which will allow you to configure Extorter to implement them but
the following approach is equivalent:

    use 5.18.0;

The Perl version requirement will be enforced whenever a scope issuing the
**use VERSION** declaration is found, i.e. as long as you ensure that declaration
is seen, the version requirement will be enforced for your program. So now we
just need to figure out how to import features into the calling namespace using
Extorter. The following approach works towards that end:

    use 5.18.0;
    use Extorter 'feature^:5.18';

# EXTORTER AND EXPORTER

You can use Extorter with the [Exporter](https://metacpan.org/pod/Exporter) module, to create a sophisticated
exporter which implements the Exporter interface. The following is an example:

    package MyApp::Imports;

    use Extorter;
    use base 'Exporter';

    our @EXPORT_OK = qw(
        optional_thing1
        optional_thing2
    );