From 3ec63400e347975cd86b1631a489bb9a5d50357a Mon Sep 17 00:00:00 2001 From: Chad Granum Date: Sat, 9 Jul 2016 15:59:27 -0700 Subject: Update README --- README | 112 ++++++++++++++++++++++++++++++++++++++++++++++++------- README.md | 126 +++++++++++++++++++++++++++++++++++++++++++++++++++++--------- 2 files changed, 206 insertions(+), 32 deletions(-) diff --git a/README b/README index 99d2b73..25cc1b5 100644 --- a/README +++ b/README @@ -10,9 +10,6 @@ DESCRIPTION need to use or inherit from the Exporter module, they just need to set @EXPORT and/or other variables. -*** EXPERIMENTAL *** - This module is still experimental. Anything can change at any time. - SYNOPSYS # Import defaults use Importer 'Some::Module'; @@ -33,6 +30,15 @@ SYNOPSYS # Remove all subroutines imported by Importer no Importer; + # Import symbols into variables + my $croak = Importer->get_one(Carp => qw/croak/); + $croak->("This will croak"); + + my $CARP = Importer->get(Carp => qw/croak confess cluck/); + $CARP->{croak}->("This will croak"); + $CARP->{cluck}->("This will cluck"); + $CARP->{confess}->("This will confess"); + WHY? There was recently a discussion on p5p about adding features to Exporter. This conversation raised some significant concerns, those are @@ -111,6 +117,28 @@ IMPORT PARAMETERS $CARP{cluck}->("This will cluck"); $CARP{croak}->("This will croak"); + The first two arguments to the custom sub are the name (no sigil), + and the reference. The additional arguments are key/value pairs: + + sub set_symbol { + my ($name, $ref, %info) = @_; + } + + $info{from} + Package the symbol comes from. + + $info{into} + Package to which the symbol should be added. + + $info{sig} + The sigil that should be used. + + $info{spec} + Extra details. + + $info{symbol} + The original symbol name (with sigil) from the original package. + @SYMBOLS (optional) Symbols you wish to import. If no symbols are specified then the defaults will be used. @@ -207,6 +235,13 @@ SUPPORTED VARIABLES use Importer 'Other::Thing' => ':some_tag'; + Tags can be specified this way: + + our %EXPORT_TAGS = ( + oos => [qw/foo boo zoo/], + ees => [qw/fee bee zee/], + ); + @EXPORT_FAIL This is used exactly the way Exporter uses it. @@ -243,6 +278,7 @@ SUPPORTED VARIABLES our %EXPORT_GEN = ( '&foo' => sub { + my $from_package = shift; my ($into_package, $symbol_name) = @_; ... return sub { ... }; @@ -250,6 +286,28 @@ SUPPORTED VARIABLES ... ); + %EXPORT_MAGIC + This is new to this module. Exporter does not support it. + + 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. These will NOT be run if a + consumer uses a custom assignment callback. + + our %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 METHODS Importer->import($from) Importer->import($from, $version) @@ -303,17 +361,18 @@ USING WITH OTHER EXPORTER IMPLEMENTATIONS my ($into, $caller) = @_; return ( - export => \@EXPORT, # Default exports - export_ok => \@EXPORT_OK, # Other allowed exports - export_tags => \%EXPORT_TAGS, # Define tags - export_fail => \@EXPORT_FAIL, # For subs that may not always be available - export_anon => \%EXPORT_ANON, # Anonymous symbols to export - - generate => \&GENERATE, # Sub to generate dynamic exports - # OR - export_gen => \%EXPORT_GEN, # Hash of builders, key is symbol - # name, value is sub that generates - # the symbol ref. + export => \@EXPORT, # Default exports + export_ok => \@EXPORT_OK, # Other allowed exports + export_tags => \%EXPORT_TAGS, # Define tags + export_fail => \@EXPORT_FAIL, # For subs that may not always be available + export_anon => \%EXPORT_ANON, # Anonymous symbols to export + export_magic => \%EXPORT_MAGIC, # Magic to apply after a symbol is exported + + generate => \&GENERATE, # Sub to generate dynamic exports + # OR + export_gen => \%EXPORT_GEN, # Hash of builders, key is symbol + # name, value is sub that generates + # the symbol ref. ); } @@ -352,6 +411,12 @@ OO Interface $imp->do_import('Destination::Package'); $imp->do_import('Another::Destination', @symbols); + Or, maybe more useful: + + my $imp = Importer->new(from => 'Carp'); + my $croak = $imp->get_one('croak'); + $croak->("This will croak"); + OBJECT CONSTRUCTION $imp = Importer->new(from => 'Some::Exporter') $imp = Importer->new(from => 'Some::Exporter', caller => [$package, @@ -435,6 +500,9 @@ OO Interface # to. tags => { DEFAULT => [...], foo => [...], ... }, + # Magic to apply + magic => { foo => sub { ... }, ... }, + # This is a hashref just like 'lookup'. Keys are symbols which may not # always be available. If there are no symbols in this category then # the value of the 'fail' key will be undef instead of a hashref. @@ -462,6 +530,22 @@ OO Interface This returns a single reference to a single export. If you provide multiple imports then only the LAST one will be used. +FUNCTIONS + These can be imported: + + use Importer 'Importer' => qw/optimal_import/; + + $bool = optimal_import($from, $into, \@caller, @imports) + This function will attempt to import @imports from the $from package + into the $into package. @caller needs to have a package name, + filename, and line number. If this function fails then no exporting + will actually happen. + + If the import is successful this will return true. + + If the import is unsuccessful this will return false, and no + modifications to the symbol table will occur. + SOURCE The source code repository for symbol can be found at http://github.com/exodist/Importer. diff --git a/README.md b/README.md index 24d10fb..7f6535c 100644 --- a/README.md +++ b/README.md @@ -11,10 +11,6 @@ extras. You can use this to import symbols from any exporter that follows or inherit from the [Exporter](https://metacpan.org/pod/Exporter) module, they just need to set `@EXPORT` and/or other variables. -# \*\*\* EXPERIMENTAL \*\*\* - -This module is still experimental. Anything can change at any time. - # SYNOPSYS # Import defaults @@ -36,6 +32,15 @@ This module is still experimental. Anything can change at any time. # Remove all subroutines imported by Importer no Importer; + # Import symbols into variables + my $croak = Importer->get_one(Carp => qw/croak/); + $croak->("This will croak"); + + my $CARP = Importer->get(Carp => qw/croak confess cluck/); + $CARP->{croak}->("This will croak"); + $CARP->{cluck}->("This will cluck"); + $CARP->{confess}->("This will confess"); + # WHY? There was recently a discussion on p5p about adding features to [Exporter](https://metacpan.org/pod/Exporter). @@ -121,6 +126,33 @@ feature (like import renaming). $CARP{cluck}->("This will cluck"); $CARP{croak}->("This will croak"); + The first two arguments to the custom sub are the name (no sigil), and the + reference. The additional arguments are key/value pairs: + + sub set_symbol { + my ($name, $ref, %info) = @_; + } + + - $info{from} + + Package the symbol comes from. + + - $info{into} + + Package to which the symbol should be added. + + - $info{sig} + + The sigil that should be used. + + - $info{spec} + + Extra details. + + - $info{symbol} + + The original symbol name (with sigil) from the original package. + - @SYMBOLS (optional) Symbols you wish to import. If no symbols are specified then the defaults will @@ -230,6 +262,13 @@ This module supports tags exactly the way [Exporter](https://metacpan.org/pod/Ex use Importer 'Other::Thing' => ':some_tag'; +Tags can be specified this way: + + our %EXPORT_TAGS = ( + oos => [qw/foo boo zoo/], + ees => [qw/fee bee zee/], + ); + ## @EXPORT\_FAIL This is used exactly the way [Exporter](https://metacpan.org/pod/Exporter) uses it. @@ -269,6 +308,7 @@ not include sigil for subs). our %EXPORT_GEN = ( '&foo' => sub { + my $from_package = shift; my ($into_package, $symbol_name) = @_; ... return sub { ... }; @@ -276,6 +316,29 @@ not include sigil for subs). ... ); +## %EXPORT\_MAGIC + +This is new to this module. [Exporter](https://metacpan.org/pod/Exporter) does not support it. + +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](https://metacpan.org/pod/Devel::Declare). These will NOT be run if a consumer uses a +custom assignment callback. + + our %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 METHODS - Importer->import($from) @@ -336,17 +399,18 @@ to support Importer by putting this sub in your package. my ($into, $caller) = @_; return ( - export => \@EXPORT, # Default exports - export_ok => \@EXPORT_OK, # Other allowed exports - export_tags => \%EXPORT_TAGS, # Define tags - export_fail => \@EXPORT_FAIL, # For subs that may not always be available - export_anon => \%EXPORT_ANON, # Anonymous symbols to export - - generate => \&GENERATE, # Sub to generate dynamic exports - # OR - export_gen => \%EXPORT_GEN, # Hash of builders, key is symbol - # name, value is sub that generates - # the symbol ref. + export => \@EXPORT, # Default exports + export_ok => \@EXPORT_OK, # Other allowed exports + export_tags => \%EXPORT_TAGS, # Define tags + export_fail => \@EXPORT_FAIL, # For subs that may not always be available + export_anon => \%EXPORT_ANON, # Anonymous symbols to export + export_magic => \%EXPORT_MAGIC, # Magic to apply after a symbol is exported + + generate => \&GENERATE, # Sub to generate dynamic exports + # OR + export_gen => \%EXPORT_GEN, # Hash of builders, key is symbol + # name, value is sub that generates + # the symbol ref. ); } @@ -386,6 +450,12 @@ over them: $imp->do_import('Destination::Package'); $imp->do_import('Another::Destination', @symbols); +Or, maybe more useful: + + my $imp = Importer->new(from => 'Carp'); + my $croak = $imp->get_one('croak'); + $croak->("This will croak"); + ## OBJECT CONSTRUCTION - $imp = Importer->new(from => 'Some::Exporter') @@ -476,6 +546,9 @@ over them: # to. tags => { DEFAULT => [...], foo => [...], ... }, + # Magic to apply + magic => { foo => sub { ... }, ... }, + # This is a hashref just like 'lookup'. Keys are symbols which may not # always be available. If there are no symbols in this category then # the value of the 'fail' key will be undef instead of a hashref. @@ -506,6 +579,23 @@ over them: This returns a single reference to a single export. If you provide multiple imports then only the LAST one will be used. +# FUNCTIONS + +These can be imported: + + use Importer 'Importer' => qw/optimal_import/; + +- $bool = optimal\_import($from, $into, \\@caller, @imports) + + This function will attempt to import `@imports` from the `$from` package into + the `$into` package. `@caller` needs to have a package name, filename, and + line number. If this function fails then no exporting will actually happen. + + If the import is successful this will return true. + + If the import is unsuccessful this will return false, and no modifications to + the symbol table will occur. + # SOURCE The source code repository for symbol can be found at @@ -513,15 +603,15 @@ The source code repository for symbol can be found at # MAINTAINERS -- Chad Granum <exodist@cpan.org> +- Chad Granum # AUTHORS -- Chad Granum <exodist@cpan.org> +- Chad Granum # COPYRIGHT -Copyright 2015 Chad Granum <exodist7@gmail.com>. +Copyright 2015 Chad Granum . This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. -- cgit v1.2.3