Provided by: libexporter-declare-perl_0.113-1_all 
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, $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 forcfully 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 segmant of the
packages namespace. IE "My::Long::Package::Name::Foo" could export the "Foo()"
function. These alias functionis 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()
independantly.
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
exporter_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 exodist7@gmail.com
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.