NAME

Exporter::Easy - Takes the drudgery out of Exporting symbols

SYNOPSIS

In module YourModule.pm:

  package YourModule;
  use Exporter::Easy (
    OK => [ 'munge', 'frobnicate' ] # symbols to export on request
  );

In other files which wish to use YourModule:

  use ModuleName qw(frobnicate);      # import listed symbols
  frobnicate ($left, $right)          # calls YourModule::frobnicate

DESCRIPTION

The Exporter::Easy module is a wrapper around Exporter. In it's simplest case it allows you to drop the boilerplate code that comes with using Exporter, so

  require Exporter;
  use base qw( Exporter );
  use vars qw( @EXPORT );
  @EXPORT = ( 'init' );

becomes

  use Exporter::Easy ( EXPORT => [ 'init' ] );

and more complicated situations where you use tags to build lists and more tags become easy, like this

  use Exporter (
        EXPORT => [qw( init :base )],
        TAGS => [
                base => [qw( open close )],
                read => [qw( read sysread readline )],
                write => [qw( print write writeline )],
                misc => [qw( select flush )],
                all => [qw( :base :read :write :misc)],
                no_misc => [qw( :all !:misc )],
        ],
        OK => [qw( some other stuff )],
  );

All it does is set up @EXPORT, @EXPORT_OK, @EXPORT_FAIL and %EXPORT_TAGS in the current package and add Exporter to that packages @ISA. The rest is handled as normal by Exporter.

HOW TO USE IT

Put

        use Exporter::Easy ( KEY => value, ...);

In your package. Arguments are passes as key-value pairs, the following keys are available

EXPORT

The value should be a reference to a list of symbol names and tags. Any tags will be expanded and the resulting list of symbol names will be placed in the @EXPORT array in your package.

FAIL

The value should be a reference to a list of symbol names and tags. The tags will be expanded and the resulting list of symbol names will be placed in the @EXPORT_FAIL array in your package. They will also be removed from the @EXPORT_OK list.

TAGS

The value should be a reference to a list that goes like (TAG_NAME, TAG_VALUE, TAG_NAME, TAG_VALUE, ...), where TAG_NAME is a string and TAG_VALUE is a reference to an array of symbols and tags. For example

  TAGS => [
    file => [ 'open', 'close', 'read', 'write'],
    string => [ 'length', 'substr', 'chomp' ],
    hash => [ 'keys', 'values', 'each' ],
    all => [ ':file', ':string', ':hash' ],
    some => [':all', '!open', ':hash'],
  ]

This is used to fill the %EXPORT_TAGS in your package. You can build tags from other tags - in the example above the tag all will contain all the symbols from file, string and hash. You can also subtract symbols and tags - in the example above, some contains the symbols from all but with open removed and all the symbols from hash removed.

The rule is that any symbol starting with a ':' is taken to be a tag which has been defined previously (if it's not defined you'll get an error). If a symbol is preceded by a '!' it will be subtracted from the list, otherwise it is added.

If you try to redefine a tag you will also get an error.

All the symbols which occur while building the tags are automatically added your package's @EXPORT_OK array.

OK

The value should be a reference to a list of symbols names. These symbols will be added to the @EXPORT_OK array in your package.

ALL

The value should be the name of tag that doesn't yet exist. This tag will contain a list of all symbols which can be exported.

SEE ALSO

For details on what all these arrays and hashes actually do, see the Exporter documentation.

AUTHOR

Written by Fergal Daly <fergal@esatclear.ie>.

LICENSE

Under the same license as Perl itself