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

    ...

SELECTING ITEMS TO IMPORT

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

TAGS

-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

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

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

ARGUMENTS

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

Once again available options are exporter specific.

PROVIDING ARGUMENTS FOR GENERATED ITEMS

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.

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