NAME

   Exporter::Declare - Exporting done right

DESCRIPTION

   Exporter::Declare is a meta-driven exporting tool. Exporter::Declare
   tries to adopt all the good features of other exporting tools, while
   throwing away horrible interfaces. Exporter::Declare also provides
   hooks that allow you to add options and arguments for import. Finally,
   Exporter::Declare's meta-driven system allows for top-notch
   introspection.

FEATURES

   Declarative exporting (like Moose for exporting)

   Meta-driven for introspection

   Customizable import() method

   Export groups (tags)

   Export generators for subs and variables

   Clear and concise OO API

   Exports are blessed, allowing for more introspection

   Import syntax based off of Sub::Exporter

   Packages export aliases

SYNOPSIS

EXPORTER

       package Some::Exporter;
       use Exporter::Declare;

       default_exports qw/ do_the_thing /;
       exports qw/ subA subB $SCALAR @ARRAY %HASH /;

       # Create a couple tags (import lists)
       export_tag subs => qw/ subA subB do_the_thing /;
       export_tag vars => qw/ $SCALAR @ARRAY %HASH /;

       # These are simple boolean options, pass '-optionA' to enable it.
       import_options   qw/ optionA optionB /;

       # These are options which slurp in the next argument as their value, pass
       # '-optionC' => 'foo' to give it a value.
       import_arguments qw/ optionC optionD /;

       export anon_export => sub { ... };
       export '@anon_var' => [...];

       default_export a_default => sub { 'default!' }

       our $X = "x";
       default_export '$X';

       my $iterator = 'a';
       gen_export unique_class_id => sub {
           my $current = $iterator++;
           return sub { $current };
       };

       gen_default_export '$my_letter' => sub {
           my $letter = $iterator++;
           return \$letter;
       };

       # You can create a function to mangle the arguments before they are
       # parsed into a Exporter::Declare::Spec object.
       sub alter_import_args {
          my ($class, $importer, $args) = @_;

          # fiddle with args before importing routines are called
          @$args = grep { !/^skip_/ } @$args
       }

       # There is no need to fiddle with import() or do any wrapping.
       # the $specs data structure means you generally do not need to parse
       # arguments yourself (but you can if you want using alter_import_args())

       # Change the spec object before export occurs
       sub before_import {
           my $class = shift;
           my ( $importer, $specs ) = @_;

           if ($specs->config->{optionA}) {
               # Modify $spec attributes accordingly
           }
       }

       # Use spec object after export occurs
       sub after_import {
           my $class = shift;
           my ( $importer, $specs ) = @_;

           do_option_a() if $specs->config->{optionA};

           do_option_c( $specs->config->{optionC} )
               if $specs->config->{optionC};

           print "-subs tag was used\n"
               if $specs->config->{subs};

           print "exported 'subA'\n"
               if $specs->exports->{subA};
       }

       ...

IMPORTER

       package Some::Importer;
       use Some::Exporter qw/ subA $SCALAR !%HASH /,
                           -default => { -prefix => 'my_' },
                           qw/ -optionA !-optionB /,
                           subB => { -as => 'sub_b' };

       subA();
       print $SCALAR;
       sub_b();
       my_do_the_thing();

       ...

IMPORT INTERFACE

   Importing from a package that uses Exporter::Declare will be familiar
   to anyone who has imported from modules before. Arguments are all
   assumed to be export names, unless prefixed with - or : In which case
   they may be a tag or an option. Exports without a sigil are assumed to
   be code exports, variable exports must be listed with their sigil.

   Items prefixed with the ! symbol are forcefully excluded, regardless of
   any listed item that may normally include them. Tags can also be
   excluded, this will effectively exclude everything in the tag.

   Tags are simply lists of exports, the exporting class may define any
   number of tags. Exporter::Declare also has the concept of options, they
   have the same syntax as tags. Options may be boolean or argument based.
   Boolean options are actually 3 value, undef, false !, or true. Argument
   based options will grab the next value in the arguments list as their
   own, regardless of what type of value it is.

   When you use the module, or call import(), all the arguments are
   transformed into an Exporter::Declare::Specs object. Arguments are
   parsed for you into a list of imports, and a configuration hash in
   which tags/options are keys. Tags are listed in the config hash as
   true, false, or undef depending on if they were included, negated, or
   unlisted. Boolean options will be treated in the same way as tags.
   Options that take arguments will have the argument as their value.

SELECTING ITEMS TO IMPORT

   Exports can be subs, or package variables (scalar, hash, array). For
   subs simply ask for the sub by name, you may optionally prefix the subs
   name with the sub sigil &. For variables list the variable name along
   with its sigil $, %, or @.

       use Some::Exporter qw/ somesub $somescalar %somehash @somearray /;

TAGS

   Every exporter automatically has the following 3 tags, in addition they
   may define any number of custom tags. Tags can be specified by their
   name prefixed by either - or :.

   -all

     This tag may be used to import everything the exporter provides.

   -default

     This tag is used to import the default items exported. This will be
     used when no argument is provided to import.

   -alias

     Every package has an alias that it can export. This is the last
     segment of the packages namespace. IE My::Long::Package::Name::Foo
     could export the Foo() function. These alias functions simply return
     the full package name as a string, in this case
     'My::Long::Package::Name::Foo'. This is similar to aliased.

     The -alias tag is a shortcut so that you do not need to think about
     what the alias name would be when adding it to the import arguments.

         use My::Long::Package::Name::Foo -alias;

         my $foo = Foo()->new(...);

RENAMING IMPORTED ITEMS

   You can prefix, suffix, or completely rename the items you import.
   Whenever an item is followed by a hash in the import list, that hash
   will be used for configuration. Configuration items always start with a
   dash -.

   The 3 available configuration options that effect import names are
   -prefix, -suffix, and -as. If -as is seen it will be used as is. If
   prefix or suffix are seen they will be attached to the original name
   (unless -as is present in which case they are ignored).

       use Some::Exporter subA => { -as => 'DoThing' },
                          subB => { -prefix => 'my_', -suffix => '_ok' };

   The example above will import subA() under the name DoThing(). It will
   also import subB() under the name my_subB_ok().

   You may als specify a prefix and/or suffix for tags. The following
   example will import all the default exports with 'my_' prefixed to each
   name.

       use Some::Exporter -default => { -prefix => 'my_' };

OPTIONS

   Some exporters will recognise options. Options look just like tags, and
   are specified the same way. What options do, and how they effect things
   is exporter-dependant.

       use Some::Exporter qw/ -optionA -optionB /;

ARGUMENTS

   Some options require an argument. These options are just like other
   tags/options except that the next item in the argument list is slurped
   in as the option value.

       use Some::Exporter -ArgOption    => 'Value, not an export',
                          -ArgTakesHash => { ... };

   Once again available options are exporter specific.

PROVIDING ARGUMENTS FOR GENERATED ITEMS

   Some items are generated at import time. These items may accept
   arguments. There are 3 ways to provide arguments, and they may all be
   mixed (though that is not recommended).

   As a hash

       use Some::Exporter generated => { key => 'val', ... };

   As an array

       use Some::Exporter generated => [ 'Arg1', 'Arg2', ... ];

   As an array in a config hash

       use Some::Exporter generated => { -as => 'my_gen', -args => [ 'arg1', ... ]};

   You can use all three at once, but this is really a bad idea,
   documented for completeness:

       use Some::Exporter generated => { -as => 'my_gen, key => 'value', -args => [ 'arg1', 'arg2' ]}
                          generated => [ 'arg3', 'arg4' ];

   The example above will work fine, all the arguments will make it into
   the generator. The only valid reason for this to work is that you may
   provide arguments such as -prefix to a tag that brings in generator(),
   while also desiring to give arguments to generator() independently.

PRIMARY EXPORT API

   With the exception of import(), all the following work equally well as
   functions or class methods.

   import( @args )

     The import() class method. This turns the @args list into an
     Exporter::Declare::Specs object.

   exports( @add_items )

     Add items to be exported.

   @list = exports()

     Retrieve list of exports.

   default_exports( @add_items )

     Add items to be exported, and add them to the -default tag.

   @list = default_exports()

     List of exports in the -default tag

   import_options(@add_items)

     Specify boolean options that should be accepted at import time.

   import_arguments(@add_items)

     Specify options that should be accepted at import that take
     arguments.

   export_tag( $name, @add_items );

     Define an export tag, or add items to an existing tag.

EXTENDED EXPORT API

   These all work fine in function or method form, however the syntax
   sugar will only work in function form.

   reexport( $package )

     Make this exporter inherit all the exports and tags of $package.
     Works for Exporter::Declare or Exporter.pm based exporters.
     Re-Exporting of Sub::Exporter based classes is not currently
     supported.

   export_to( $package, @args )

     Export to the specified class.

   export( $name )

   export( $name, $ref )

     export is a keyword that lets you export any 1 item at a time. The
     item can be exported by name, or name + ref. When a ref is provided,
     the export is created, but there is no corresponding variable/sub in
     the packages namespace.

   default_export( $name )

   default_export( $name, $ref )

   gen_export( $name )

   gen_export( $name, $ref )

   gen_default_export( $name )

   gen_default_export( $name, $ref )

     These all act just like export(), except that they add subrefs as
     generators, and/or add exports to the -default tag.

MAGIC

   Please use Exporter::Declare::Magic directly from now on.

DEPRECATED USAGE OF MAGIC

       use Exporter::Declare '-magic';

   This adds Devel::Declare magic to several functions. It also allows you
   to easily create or use parsers on your own exports. See
   Exporter::Declare::Magic for more details.

   You can also provide import arguments to Devel::Declare::Magic

       # Arguments to -magic must be in an arrayref, not a hashref.
       use Exporter::Declare -magic => [ '-default', '!export', -prefix => 'magic_' ];

INTERNAL API

   Exporter/Declare.pm does not have much logic to speak of. Rather
   Exporter::Declare is sugar on top of class meta data stored in
   Exporter::Declare::Meta objects. Arguments are parsed via
   Exporter::Declare::Specs, and also turned into objects. Even exports
   are blessed references to the exported item itself, and handle the
   injection on their own (See Exporter::Declare::Export).

META CLASS

   All exporters have a meta class, the only way to get the meta object is
   to call the export_meta() method on the class/object that is an
   exporter. Any class that uses Exporter::Declare gets this method, and a
   meta-object.

AUTHORS

   Chad Granum [email protected]

COPYRIGHT

   Copyright (C) 2010 Chad Granum

   Exporter-Declare is free software; Standard perl licence.

   Exporter-Declare is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the license
   for more details.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.