/ 
Export-Declare-0.002
River stage zero No dependents
++
 / Export::Declare

NAME

Export::Declare - Declarative Exporting, successor of Exporter-Declare.

DESCRIPTION

Declare exports instead of using package vars. Successor to Exporter::Declare which was over complicated. Fully compatible with Importer and Exporter.

SYNOPSYS

DECLARING EXPORTS

    package My::Exporter;
    use Importer 'Export::Declare' => (qw/export exports export_tag export_meta/);

    # You should do one of these, if you do not then 'vars' will be selected
    # automatically.
    export_meta->inject_menu; # Define IMPORTER_MENU
    # and/or
    export_meta->inject_vars; # Define @EXPORT and friends

    # Export an anonymous sub
    export foo => sub { 'foo' };

    # Export package subs
    exports qw/bar baz/;

    # Default export
    export_tag DEFAULT => qw/bat/;

    # Define the subs you are exporting
    sub bar { 'bar' }
    sub baz { 'baz' }
    sub bat { 'bat' }

CONSUMING EXPORTS

    use Importer 'My::Exporter' => qw/foo bar baz bat/;

if the exporter imported import() from Export::Declare then you can use it directly, but this is discouraged.

    use My::Exporter qw/foo bar baz bat/;

USE + IMPORT

You can use Export::Declare directly to bring in the tools. You can specify -menu and/or -vars to inject IMPORTER_MENU() and/or @EXPORT and friends.

    use Export::Declare => qw/-vars -menu export exports/;

EXPORTS

All exports are optinal, none are exported by default.

my $meta = export_meta()

Get the meta-object for the current package.

This is litterally:

    sub export_meta { Export::Declare::Meta->new(scalar caller) }
export $NAME
export $NAME => $REF

Export the specified symbol. if $REF is specified then it will be used as the export. If $REF is not specified then the ref will be pulled from the symbol table for the current package.

$NAME can be a function name, or a symbol name such as '$FOO'. $REF if provided must be the same type as the sigil in $NAME. if $NAME has no sigil then & is assumed.

exports @NAMES

@NAMES is a list of symbol names. A symbol name can be a function name without a sigil, or it can be any type of veriable with a sigil.

export_tag $TAG => @NAMES

$TAG can be any valid tag name (same as any variable name, must start with a word character, and contain only word characters and numbers.

@NAMES is a list of symbol names. A symbol name can be a function name without a sigil, or it can be any type of veriable with a sigil.

The :DEFAULT tag is linked to @EXPORT when the meta-data is linked with package vars.

The :FAIL tag is linked to @EXPORT_FAIL when the meta-data is linked with package vars.

The :ALL tag is linked to @EXPORT_OK when the meta-data is linked with package vars. All exports are added to this tag automatically.

export_gen $NAME => \&GENERATOR
export_gen $NAME => $GENERATOR

Specify that $NAME should be exported, and that the $REF should be generated dynamically using the specified sub. This sub will be used every time something imports $NAME.

$NAME can be a function name, or a symbol name such as '$FOO'. $REF if provided must be the same type as the sigil in $NAME. if $NAME has no sigil then & is assumed.

The second argument can be a reference to a subroutine, or it can be the name of a sub to call on the current package.

The sub gets several arguments:

    export_gen foo => sub {
        my ($from_package, $into_package, $symbol_name) = @_;
        ...
        return $REF;
    };

    export_gen bar => '_gen_bar''
    sub _gen_bar {
        my ($from_package, $into_package, $symbol_name) = @_;
        ...
        return $REF;
    }
export_magic $NAME => sub { ... }

This allows you to define custom actions to run AFTER an export has been injected into the consumers namespace. This is a good place to enable parser hooks like with Devel::Declare.

    export_magic foo => sub {
        my $from = shift;    # Should be the package doing the exporting
        my %args = @_;

        my $into      = $args{into};         # Package symbol was exported into
        my $orig_name = $args{orig_name};    # Original name of the export (in the exporter)
        my $new_name  = $args{new_name};     # Name the symbol was imported as
        my $ref       = $args{ref};          # The reference to the symbol

        ...;                                 # whatever you want, return is ignored.
    };
$CLASS->import(@NAMES)

This is an optinal import() method you can pull into your exporter so that people can consume your exports by directly using your module.

    package My::Exporter;

    use Importer 'Export::Declare' => qw/export import/;

    export foo => sub { 'foo' };

...

    package My::Consumer;

    use My::Exporter qw/foo/;

This is discouraged! it is better if you omit import() and have people do this to get your exports:

    package My::Consumer;

    use Importer 'My::Exporter' => qw/foo/;

DETAILS

This package tracks exports in a meta class. The meta-class is Export::Declare::Meta. All the exports act on the meta-object for the package that calls them. Having this meta-data on its own does not actually make your module an exporter, for that to happen you need to expose the meta-data in a way that Exporter or Importer know how to find it.

    export_meta->inject_vars;
    export_meta->inject_menu;

inject_vars will inject @EXPORT, @EXPORT_OK and other related vars. These vars will be directly linked to the meta-object.

inject_menu injects the IMPORTER_MENU() function that exposes the meta-data.

If you do not specify one, then vars will be selected for you automatically the first time you use an export function.

SOURCE

The source code repository for Export-Declare can be found at http://github.com/exodist/Export-Declare/.

MAINTAINERS

Chad Granum <exodist@cpan.org>

AUTHORS

Chad Granum <exodist@cpan.org>

COPYRIGHT

Copyright 2015 Chad Granum <exodist7@gmail.com>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://dev.perl.org/licenses/