.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Exporter::Declare 3pm"
.TH Exporter::Declare 3pm "2022-06-13" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Exporter::Declare \- Exporting done right
.SH "DESCRIPTION"
.IX Header "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.
.SH "FEATURES"
.IX Header "FEATURES"
.IP "Declarative exporting (like Moose for exporting)" 4
.IX Item "Declarative exporting (like Moose for exporting)"
.PD 0
.IP "Meta-driven for introspection" 4
.IX Item "Meta-driven for introspection"
.IP "Customizable \fBimport()\fR method" 4
.IX Item "Customizable import() method"
.IP "Export groups (tags)" 4
.IX Item "Export groups (tags)"
.IP "Export generators for subs and variables" 4
.IX Item "Export generators for subs and variables"
.IP "Clear and concise \s-1OO API\s0" 4
.IX Item "Clear and concise OO API"
.IP "Exports are blessed, allowing for more introspection" 4
.IX Item "Exports are blessed, allowing for more introspection"
.IP "Import syntax based off of Sub::Exporter" 4
.IX Item "Import syntax based off of Sub::Exporter"
.IP "Packages export aliases" 4
.IX Item "Packages export aliases"
.PD
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.SS "\s-1EXPORTER\s0"
.IX Subsection "EXPORTER"
.Vb 2
\&    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 \*(Aq\-optionA\*(Aq to enable it.
\&    import_options   qw/ optionA optionB /;
\&
\&    # These are options which slurp in the next argument as their value, pass
\&    # \*(Aq\-optionC\*(Aq => \*(Aqfoo\*(Aq to give it a value.
\&    import_arguments qw/ optionC optionD /;
\&
\&    export anon_export => sub { ... };
\&    export \*(Aq@anon_var\*(Aq => [...];
\&
\&    default_export a_default => sub { \*(Aqdefault!\*(Aq }
\&
\&    our $X = "x";
\&    default_export \*(Aq$X\*(Aq;
\&
\&    my $iterator = \*(Aqa\*(Aq;
\&    gen_export unique_class_id => sub {
\&        my $current = $iterator++;
\&        return sub { $current };
\&    };
\&
\&    gen_default_export \*(Aq$my_letter\*(Aq => sub {
\&        my $letter = $iterator++;
\&        return \e$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\en"
\&            if $specs\->config\->{subs};
\&
\&        print "exported \*(AqsubA\*(Aq\en"
\&            if $specs\->exports\->{subA};
\&    }
\&
\&    ...
.Ve
.SS "\s-1IMPORTER\s0"
.IX Subsection "IMPORTER"
.Vb 5
\&    package Some::Importer;
\&    use Some::Exporter qw/ subA $SCALAR !%HASH /,
\&                        \-default => { \-prefix => \*(Aqmy_\*(Aq },
\&                        qw/ \-optionA !\-optionB /,
\&                        subB => { \-as => \*(Aqsub_b\*(Aq };
\&
\&    subA();
\&    print $SCALAR;
\&    sub_b();
\&    my_do_the_thing();
\&
\&    ...
.Ve
.SH "IMPORT INTERFACE"
.IX Header "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 \f(CW\*(C`\-\*(C'\fR or \f(CW\*(C`:\*(C'\fR 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.
.PP
Items prefixed with the \f(CW\*(C`!\*(C'\fR 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.
.PP
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 \f(CW\*(C`!\*(C'\fR, 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.
.PP
When you use the module, or call \fBimport()\fR, 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.
.SS "\s-1SELECTING ITEMS TO IMPORT\s0"
.IX Subsection "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 \f(CW\*(C`&\*(C'\fR. For variables list the variable name along with its sigil
\&\f(CW\*(C`$, %, or @\*(C'\fR.
.PP
.Vb 1
\&    use Some::Exporter qw/ somesub $somescalar %somehash @somearray /;
.Ve
.SS "\s-1TAGS\s0"
.IX Subsection "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 \f(CW\*(C`\-\*(C'\fR or \f(CW\*(C`:\*(C'\fR.
.IP "\-all" 4
.IX Item "-all"
This tag may be used to import everything the exporter provides.
.IP "\-default" 4
.IX Item "-default"
This tag is used to import the default items exported. This will be used when
no argument is provided to import.
.IP "\-alias" 4
.IX Item "-alias"
Every package has an alias that it can export. This is the last segment of the
packages namespace. \s-1IE\s0 \f(CW\*(C`My::Long::Package::Name::Foo\*(C'\fR could export the \f(CW\*(C`Foo()\*(C'\fR
function. These alias functions simply return the full package name as a
string, in this case \f(CW\*(AqMy::Long::Package::Name::Foo\*(Aq\fR. This is similar to
aliased.
.Sp
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.
.Sp
.Vb 1
\&    use My::Long::Package::Name::Foo \-alias;
\&
\&    my $foo = Foo()\->new(...);
.Ve
.SS "\s-1RENAMING IMPORTED ITEMS\s0"
.IX Subsection "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 \f(CW\*(C`\-\*(C'\fR.
.PP
The 3 available configuration options that effect import names are \f(CW\*(C`\-prefix\*(C'\fR,
\&\f(CW\*(C`\-suffix\*(C'\fR, and \f(CW\*(C`\-as\*(C'\fR. If \f(CW\*(C`\-as\*(C'\fR 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).
.PP
.Vb 2
\&    use Some::Exporter subA => { \-as => \*(AqDoThing\*(Aq },
\&                       subB => { \-prefix => \*(Aqmy_\*(Aq, \-suffix => \*(Aq_ok\*(Aq };
.Ve
.PP
The example above will import \f(CW\*(C`subA()\*(C'\fR under the name \f(CW\*(C`DoThing()\*(C'\fR. It will
also import \f(CW\*(C`subB()\*(C'\fR under the name \f(CW\*(C`my_subB_ok()\*(C'\fR.
.PP
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.
.PP
.Vb 1
\&    use Some::Exporter \-default => { \-prefix => \*(Aqmy_\*(Aq };
.Ve
.SS "\s-1OPTIONS\s0"
.IX Subsection "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.
.PP
.Vb 1
\&    use Some::Exporter qw/ \-optionA \-optionB /;
.Ve
.SS "\s-1ARGUMENTS\s0"
.IX Subsection "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.
.PP
.Vb 2
\&    use Some::Exporter \-ArgOption    => \*(AqValue, not an export\*(Aq,
\&                       \-ArgTakesHash => { ... };
.Ve
.PP
Once again available options are exporter specific.
.SS "\s-1PROVIDING ARGUMENTS FOR GENERATED ITEMS\s0"
.IX Subsection "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).
.PP
As a hash
.PP
.Vb 1
\&    use Some::Exporter generated => { key => \*(Aqval\*(Aq, ... };
.Ve
.PP
As an array
.PP
.Vb 1
\&    use Some::Exporter generated => [ \*(AqArg1\*(Aq, \*(AqArg2\*(Aq, ... ];
.Ve
.PP
As an array in a config hash
.PP
.Vb 1
\&    use Some::Exporter generated => { \-as => \*(Aqmy_gen\*(Aq, \-args => [ \*(Aqarg1\*(Aq, ... ]};
.Ve
.PP
You can use all three at once, but this is really a bad idea, documented for completeness:
.PP
.Vb 2
\&    use Some::Exporter generated => { \-as => \*(Aqmy_gen, key => \*(Aqvalue\*(Aq, \-args => [ \*(Aqarg1\*(Aq, \*(Aqarg2\*(Aq ]}
\&                       generated => [ \*(Aqarg3\*(Aq, \*(Aqarg4\*(Aq ];
.Ve
.PP
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 \f(CW\*(C`\-prefix\*(C'\fR to a tag that brings in \fBgenerator()\fR, while also
desiring to give arguments to \fBgenerator()\fR independently.
.SH "PRIMARY EXPORT API"
.IX Header "PRIMARY EXPORT API"
With the exception of \fBimport()\fR, all the following work equally well as
functions or class methods.
.ie n .IP "import( @args )" 4
.el .IP "import( \f(CW@args\fR )" 4
.IX Item "import( @args )"
The \fBimport()\fR class method. This turns the \f(CW@args\fR list into an
Exporter::Declare::Specs object.
.ie n .IP "exports( @add_items )" 4
.el .IP "exports( \f(CW@add_items\fR )" 4
.IX Item "exports( @add_items )"
Add items to be exported.
.ie n .IP "@list = \fBexports()\fR" 4
.el .IP "\f(CW@list\fR = \fBexports()\fR" 4
.IX Item "@list = exports()"
Retrieve list of exports.
.ie n .IP "default_exports( @add_items )" 4
.el .IP "default_exports( \f(CW@add_items\fR )" 4
.IX Item "default_exports( @add_items )"
Add items to be exported, and add them to the \-default tag.
.ie n .IP "@list = \fBdefault_exports()\fR" 4
.el .IP "\f(CW@list\fR = \fBdefault_exports()\fR" 4
.IX Item "@list = default_exports()"
List of exports in the \-default tag
.IP "import_options(@add_items)" 4
.IX Item "import_options(@add_items)"
Specify boolean options that should be accepted at import time.
.IP "import_arguments(@add_items)" 4
.IX Item "import_arguments(@add_items)"
Specify options that should be accepted at import that take arguments.
.ie n .IP "export_tag( $name, @add_items );" 4
.el .IP "export_tag( \f(CW$name\fR, \f(CW@add_items\fR );" 4
.IX Item "export_tag( $name, @add_items );"
Define an export tag, or add items to an existing tag.
.SH "EXTENDED EXPORT API"
.IX Header "EXTENDED EXPORT API"
These all work fine in function or method form, however the syntax sugar will
only work in function form.
.ie n .IP "reexport( $package )" 4
.el .IP "reexport( \f(CW$package\fR )" 4
.IX Item "reexport( $package )"
Make this exporter inherit all the exports and tags of \f(CW$package\fR. Works for
Exporter::Declare or Exporter.pm based exporters. Re-Exporting of
Sub::Exporter based classes is not currently supported.
.ie n .IP "export_to( $package, @args )" 4
.el .IP "export_to( \f(CW$package\fR, \f(CW@args\fR )" 4
.IX Item "export_to( $package, @args )"
Export to the specified class.
.ie n .IP "export( $name )" 4
.el .IP "export( \f(CW$name\fR )" 4
.IX Item "export( $name )"
.PD 0
.ie n .IP "export( $name, $ref )" 4
.el .IP "export( \f(CW$name\fR, \f(CW$ref\fR )" 4
.IX Item "export( $name, $ref )"
.PD
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.
.ie n .IP "default_export( $name )" 4
.el .IP "default_export( \f(CW$name\fR )" 4
.IX Item "default_export( $name )"
.PD 0
.ie n .IP "default_export( $name, $ref )" 4
.el .IP "default_export( \f(CW$name\fR, \f(CW$ref\fR )" 4
.IX Item "default_export( $name, $ref )"
.ie n .IP "gen_export( $name )" 4
.el .IP "gen_export( \f(CW$name\fR )" 4
.IX Item "gen_export( $name )"
.ie n .IP "gen_export( $name, $ref )" 4
.el .IP "gen_export( \f(CW$name\fR, \f(CW$ref\fR )" 4
.IX Item "gen_export( $name, $ref )"
.ie n .IP "gen_default_export( $name )" 4
.el .IP "gen_default_export( \f(CW$name\fR )" 4
.IX Item "gen_default_export( $name )"
.ie n .IP "gen_default_export( $name, $ref )" 4
.el .IP "gen_default_export( \f(CW$name\fR, \f(CW$ref\fR )" 4
.IX Item "gen_default_export( $name, $ref )"
.PD
These all act just like \fBexport()\fR, except that they add subrefs as generators,
and/or add exports to the \-default tag.
.SH "MAGIC"
.IX Header "MAGIC"
Please use Exporter::Declare::Magic directly from now on.
.SS "\s-1DEPRECATED USAGE OF MAGIC\s0"
.IX Subsection "DEPRECATED USAGE OF MAGIC"
.Vb 1
\&    use Exporter::Declare \*(Aq\-magic\*(Aq;
.Ve
.PP
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.
.PP
You can also provide import arguments to Devel::Declare::Magic
.PP
.Vb 2
\&    # Arguments to \-magic must be in an arrayref, not a hashref.
\&    use Exporter::Declare \-magic => [ \*(Aq\-default\*(Aq, \*(Aq!export\*(Aq, \-prefix => \*(Aqmagic_\*(Aq ];
.Ve
.SH "INTERNAL API"
.IX Header "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).
.SH "META CLASS"
.IX Header "META CLASS"
All exporters have a meta class, the only way to get the meta object is to call
the \fBexport_meta()\fR method on the class/object that is an exporter. Any class
that uses Exporter::Declare gets this method, and a meta-object.
.SH "AUTHORS"
.IX Header "AUTHORS"
Chad Granum exodist7@gmail.com
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2010 Chad Granum
.PP
Exporter-Declare is free software; Standard perl licence.
.PP
Exporter-Declare is distributed in the hope that it will be useful, but
\&\s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of \s-1MERCHANTABILITY\s0 or
\&\s-1FITNESS FOR A PARTICULAR PURPOSE.\s0  See the license for more details.