-
-
27 Jan 2016 15:25:32 UTC
- Distribution: Export-Declare
- Module version: 0.002
- Source (raw)
- Browse (raw)
- Changes
- How to Contribute
- Repository
- Issues (0)
- Testers (457 / 0 / 0)
- Kwalitee
Bus factor: 1- % Coverage
- License: perl_5
- Perl: v5.8.1
- Activity
24 month- Tools
- Download (15.7KB)
- MetaCPAN Explorer
- Permissions
- Subscribe to distribution
- Permalinks
- This version
- Latest version
- Dependencies
- Carp
- Importer
- Reverse dependencies
- CPAN Testers List
- Dependency graph
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 injectIMPORTER_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 theIMPORTER_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
AUTHORS
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/
Module Install Instructions
To install Export::Declare, copy and paste the appropriate command in to your terminal.
cpanm Export::Declare
perl -MCPAN -e shell install Export::Declare
For more information on module installation, please visit the detailed CPAN module installation guide.