Exporter::Declare - Exporting done right

       Chad Granum exodist7@gmail.com

       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.

perl v5.34.0                                       2022-06-13                             Exporter::Declare(3pm)

       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.

       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.

       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

       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.

   SELECTINGITEMSTOIMPORT
       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(...);

   RENAMINGIMPORTEDITEMS
       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.

   PROVIDINGARGUMENTSFORGENERATEDITEMS
       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.

       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).

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

   DEPRECATEDUSAGEOFMAGIC
           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_' ];

       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.

       Exporter::Declare - Exporting done right

       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.

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();

           ...