exports(%exports)

    __PACKAGE__->exports(
        all  => '$WIZ $BANG',           # like Exporter's @EXPORT
        any  => '@BING %BONG',          # like @EXPORT_OK
        tags => {                       # like %EXPORT_TAGS
            foobar => 'foo bar',
        },
        hooks => {                      # custom hooks
            hello => sub {
                print "Hello World!\n"
            },
        },
        fail => sub {                   # handle unknown exports
            print "I'm sorry Dave, I can't do that.\n"
        },
    );

Each key correponds to one of the methods below, specified without the "export_" prefix. e.g. "all" for export_all(), "any" for export_any() and so on. The method is called with the corresponding value being passed as an argument.

export_all(@symbols)

    __PACKAGE__->export_all('$WIZ $BANG');

Symbols can be specified as a a string of space-delimited tokens, as a list of items, or by reference to a list of items.

    __PACKAGE__->export_all('$WIZ $BANG');          # string
    __PACKAGE__->export_all(qw( $WIZ $BANG ));      # list
    __PACKAGE__->export_all([qw( $WIZ $BANG )]);    # list ref

These symbols will be imported when the module is loaded.

    use Badger::AnyModule;                  # import $WIZ and $BANG

This behaviour can be overridden by specifying an explicit list of imported symbols.

    use Badger::AnyModule '$BANG';          # $BANG only
    use Badger::AnyModule '$BANG @BONG';    # $BANG and @BONG

If you specify a single string of items to export then it will be split on whitespace or a comma+whitespace combination of characters to extract multiple symbol names from the string. The following three examples all do the same thing. The last two are effectively identical in all but syntax.

    use Badger::AnyModule '$BANG @BONG';    # single string
    use Badger::AnyModule '$BANG' '@BONG';  # two strings
    use Badger::AnyModule qw($BANG @BONG);  # same as above

Note that symbol splitting occurs when you specify a single string. If you specify multiple strings then none are split.

    # this doesn't work
    use Badger::AnyModule '$WIZ' '$BANG $BONG';     # WRONG!

Specify an empty list of arguments if you don't want any symbols imported.

    use Badger::AnyModule qw();             # imports nothing

export_any(@symbols)

    __PACKAGE__->export_any(qw( $WIZ $BANG ));

Symbols can be specified as a space-delimited string, a list, or by reference to a list, as per export_all().

The symbols specified as arguments are imported when the module is loaded.

    use Badger::AnyModule '$BANG';          # $BANG only
    use Badger::AnyModule '$BANG @BONG';    # $BANG and @BONG
    use Badger::AnyModule qw($BANG @BONG);  # $BANG and @BONG

export_tags(%tagsets)

If a symbol appears in a tag set then it is assumed to be safe to export. You don't need to explicitly call export_any() because the export_tags() method does it for you.

    __PACKAGE__->export_tags(
        set1 => [ qw( $WIZ $BANG ) ],
        set2 => [ qw( @BING %BONG ) ],
        set3 => [ qw( foo bar ) ],
    );

The values in the hash array can be specified as references to lists, or space-delimited strings.

    __PACKAGE__->export_tags(
        set1 => '$WIZ $BANG',
        set2 => '@BING %BONG',
        set3 => 'foo bar',
    );

To load a set of symbols, specify the tag name with a '":"' prefix.

    use Badger::AnyModule ':set1';
    use Badger::AnyModule ':set1 :set2';
    use Badger::AnyModule qw(:set1 :set2);

The special '":all"' set imports all symbols.

    use Badger::AnyModule ':all';

The special '":default"' set imports the default set of symbols.

    use Badger::AnyModule ':default @BONG';

You can also use the "export_tags()" method to define a hash array mapping aliases to symbols.

    __PACKAGE__->export_tags(
        set4 => {
            # use hash ref to define aliases for symbols
            foo => '&the_foo_sub',
            bar => '&the_bar_sub',
        }
    );

When this tagset is imported, the symbols identified by the values in the hash reference (&the_foo_sub and &the_bar_sub) are exported into the caller's package as the symbols named in the corresponding keys.

    use Badger::AnyModule ':set4';

    foo();    # Badger::AnyModule::the_foo_sub()
    bar();    # Badger::AnyModule::the_bar_sub()

When defining a tagset with a hash reference, you can provide direct references to subroutines instead of symbol names.

    __PACKAGE__->export_tags(
        set5 => {
            # use hash ref to define aliases for subroutines
            foo => \&the_foo_sub,
            bar => \&the_bar_sub,
        }
    );

You can also explicitly specify the package name for a symbol:

    __PACKAGE__->export_tags(
        set6 => {
            foo  => 'Badger::Example::One::foo',
            bar  => '&Badger:Example::One::bar',
            '$X' => '$Badger::Example::Two:X',
            '$Y' => '$Badger::Example::Two:Y',
        }
    );

The "Badger::Exporter" module also recognises the "=" pseudo-sigil which can be used to define constant values.

    __PACKAGE__->export_tags(
        set7 => {
            e   => '=2.718',
            pi  => '=3.142',
            phi => '=1.618',
        }
    );

When this tag set is imported, "Badger::Exporter" will define constant subroutines to represent the imported values.

    use Badger::AnyModule ':set7';

    print e;            # 2.718
    print pi;           # 3.142
    print phi;          # 1.618

export_hooks(%hooks)

    __PACKAGE__->export_hooks(
        hello => sub {
            my ($class, $target, $symbol, $more_symbols) = @_;
            print $symbol, " ", shift(@$more_symbols), "\n";
        }
    );

This would be used like so:

    use Badger::AnyModule hello => 'world', qw( $WIZ $BANG );

The handler is passed four arguments. The first is the package name of the exporting class (e.g. "Badger::AnyModule"). The second argument is the package name of the target class which wants to import the symbol (e.g. "main"). The symbol itself ('"hello"' in this case) is passed as the third argument. The final argument is a reference to a list of remaining symbols ("['world', '$WIZ', '$BANG']").

This example shifts off the next symbol ('"world"') and prints the message to the screen (for debugging purposes only - your handler will most likely do something more useful). The handler may remove any number of symbols from the $more_symbols list to indicate that they have been successfully handled. Any symbols left in the $more_symbols list will continue to be imported as usual.

You can also define export hooks as an array reference. The code reference should be the first item in the array. The second item is the number of arguments it expects. These will be shifted off the $more_symbols list (automatically raising an error if one or more values are missing or undefined) and passed as separate arguments to your handler. The $more_symbols reference will be passed as the final argument.

    __PACKAGE__->export_hooks(
        example => [ \&my_export_hook, 2 ],
    );

    sub my_export_hook {
        my ($self, $target, $symbol, $arg1, $arg2, $more_symbols) = @_;
        # your code...
    }

Hooks expressed this way will have closures created around them on demand by the export_hook_generator() method. Don't worry if that doesn't mean anything much to you. It simply means that we can delay doing any extra preparation work until we're sure that it's going to be used.

export_before(\&handler)

    __PACKAGE__->export_before(
        sub {
            my ($class, $target, $symbols) = @_;
            print "About to import symbols: ", join(', ', @$symbols), "\n";
        }
    );

Multiple handlers can be defined, either in the same class or inherited from base classes. Handlers defined in base classes are called before those in derived classes. Multiple handlers defined in the same class will be called in the order that they were defined in.

export_after(\&handler)

    __PACKAGE__->export_after(
        sub {
            my ($class, $target) = @_;
            print "Finished exporting\n";
        }
    );

Multiple handlers can be defined, as per export_before().

export_fail(\&handler)

    __PACKAGE__->export_fail(
        sub {
            my ($class, $target, $symbol, $more_symbols) = @_;
            if ($symbol eq 'badger') {
                print "OK, we'll let you import a badger\n";
                return 1;
            }
            else {
                print "You cannot import $symbol from $class into $target\n";
                return 0;
            }
        }
    );

An "export_fail" handler may also remove symbols from the $more_symbols list to indicate that they have been handled, as per "export_hooks()".

import(@symbols)

export($package,@symbols)

exportables()

    [\@all, \%any, \%tags, \%hooks, \@fails];

This array reference is cached in the "EXPORTABLES" package variable for future use.

export_symbol($package,$symbol,$coderef)

    Badger::Exporter->export_symbol('My::Package', 'Foo', \&foosub);

export_hook_generator($name,\&code,$nargs)

    sub code {
        my ($self, $target, $symbol, $more_symbols) = @_
        # your code...
    }

Your code is responsible for shifting any arguments it expects off the front of the $more_symbols list. It should also being doing all the messy stuff like making sure the $more_symbols list contains enough arguments and that they're all set to defined values. But I bet you forget sometimes, don't you? That's OK, it's easily done.

The purpose of the "export_hook_generator()" method is to simplify argument processing so that hooks can be specified as:

    [\&my_code, $nargs]

and written as:

    sub code {
        my (
            $self, $target, $symbol,    # the usual first three items
            $arg1, $arg2, ..., $argn,   # your $nargs items
            $more_symbols               # the remaining items
        ) = @_
    }

The method should be called like something like this:

    my $hook = Badger::Exporter->export_hook_generator(
        'wibble', \&code, 2
    );

The first argument should be the name of the option that the hook is being generated for. This is used to report any argument errors, e.g.

    Missing value for the 'wibble' option (2 wanted, 1 available)

Or:

    Missing value for the 'wibble' option (argument 2 of 2 is undefined)

The second argument is a reference to your handler subroutine. The third argument is the number of additional arguments your subroutine expects.