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/

