[libexporter-tiny-perl] 01/11: New upstream version 1.000000
Damyan Ivanov
dmn at moszumanska.debian.org
Sat Nov 11 08:29:58 UTC 2017
This is an automated email from the git hooks/post-receive script.
dmn pushed a commit to annotated tag debian/1.000000-1
in repository libexporter-tiny-perl.
commit 426c4605b10f930db7a49c253df0d91d58f69517
Author: Damyan Ivanov <dmn at debian.org>
Date: Sat Nov 11 08:12:31 2017 +0000
New upstream version 1.000000
---
CONTRIBUTING | 83 ------
COPYRIGHT | 65 +++--
Changes | 23 ++
LICENSE | 6 +-
MANIFEST | 5 +-
META.json | 11 +-
META.yml | 11 +-
Makefile.PL | 16 +-
README | 382 +--------------------------
SIGNATURE | 55 ++--
doap.ttl | 104 +++++++-
lib/Exporter/Shiny.pm | 11 +-
lib/Exporter/Tiny.pm | 439 +++-----------------------------
lib/Exporter/Tiny/Manual/Etc.pod | 134 ++++++++++
lib/Exporter/Tiny/Manual/Exporting.pod | 256 +++++++++++++++++++
lib/Exporter/Tiny/Manual/Importing.pod | 253 ++++++++++++++++++
lib/Exporter/Tiny/Manual/QuickStart.pod | 195 ++++++++++++++
t/01basic.t | 2 +-
t/02renaming.t | 2 +-
t/03generators.t | 2 +-
t/04into.t | 2 +-
t/05shiny.t | 2 +-
t/06notwant.t | 2 +-
t/07regexp.t | 2 +-
t/08tags.t | 2 +-
t/09warnings.t | 2 +-
t/10no.t | 2 +-
27 files changed, 1114 insertions(+), 955 deletions(-)
diff --git a/CONTRIBUTING b/CONTRIBUTING
deleted file mode 100644
index ba115b4..0000000
--- a/CONTRIBUTING
+++ /dev/null
@@ -1,83 +0,0 @@
-NAME
- CONTRIBUTING
-
-DESCRIPTION
- If you're reading this document, that means you might be thinking about
- helping me out with this project. Thanks!
-
- Here's some ways you could help out:
-
- * Bug reports
-
- Found a bug? Great! (Well, not so great I suppose.)
-
- The place to report them is <https://rt.cpan.org/>. Don't e-mail me
- about it, as your e-mail is more than likely to get lost amongst the
- spam.
-
- An example script clearly demonstrating the bug (preferably written
- using Test::More) would be greatly appreciated.
-
- * Patches
-
- If you've found a bug and written a fix for it, even better!
-
- Generally speaking you should check out the latest copy of the code
- from the source repository rather than using the CPAN distribution.
- The file META.yml should contain a link to the source repository. If
- not, then try <https://github.com/tobyink> or submit a bug report.
- (As far as I'm concerned the lack of a link is a bug.) Many of my
- distributions are also mirrored at <https://bitbucket.org/tobyink>.
-
- To submit the patch, do a pull request on GitHub or Bitbucket, or
- attach a diff file to a bug report. Unless otherwise stated, I'll
- assume that your contributions are licensed under the same terms as
- the rest of the project.
-
- (If using git, feel free to work in a branch. For Mercurial, I'd
- prefer bookmarks within the default branch.)
-
- * Documentation
-
- If there's anything unclear in the documentation, please submit this
- as a bug report or patch as above.
-
- Non-toy example scripts that I can bundle would also be appreciated.
-
- * Translation
-
- Translations of documentation would be welcome.
-
- For translations of error messages and other strings embedded in the
- code, check with me first. Sometimes the English strings may not in
- a stable state, so it would be a waste of time translating them.
-
- Coding Style
- I tend to write using something approximating the Allman style, using
- tabs for indentation and Unix-style line breaks.
-
- * <http://en.wikipedia.org/wiki/Indent_style#Allman_style>
-
- * <http://www.derkarl.org/why_to_tabs.html>
-
- I nominally encode all source files as UTF-8, though in practice most of
- them use a 7-bit-safe ASCII-compatible subset of UTF-8.
-
-AUTHOR
- Toby Inkster <tobyink at cpan.org>.
-
-COPYRIGHT AND LICENCE
- Copyright (c) 2012-2014 by Toby Inkster.
-
- CONTRIBUTING is available under three different licences permitting its
- redistribution: the CC-BY-SA_UK-2.0 licence, plus the same licences as
- Perl itself, which is distributed under the GNU General Public Licence
- version 1, and the Artistic Licence.
-
- This file is licensed under the Creative Commons Attribution-ShareAlike
- 2.0 UK: England & Wales License. To view a copy of this license, visit
- <http://creativecommons.org/licenses/by-sa/2.0/uk/>.
-
- This file is free software; you can redistribute it and/or modify it
- under the same terms as the Perl 5 programming language system itself.
-
diff --git a/COPYRIGHT b/COPYRIGHT
index a25d300..1bf7b17 100644
--- a/COPYRIGHT
+++ b/COPYRIGHT
@@ -3,6 +3,31 @@ Upstream-Name: Exporter-Tiny
Upstream-Contact: Toby Inkster (TOBYINK) <tobyink at cpan.org>
Source: https://metacpan.org/release/Exporter-Tiny
+Files: README
+ lib/Exporter/Tiny.pm
+ lib/Exporter/Tiny/Manual/Etc.pod
+ lib/Exporter/Tiny/Manual/Exporting.pod
+ lib/Exporter/Tiny/Manual/Importing.pod
+ lib/Exporter/Tiny/Manual/QuickStart.pod
+ t/01basic.t
+ t/02renaming.t
+ t/03generators.t
+ t/04into.t
+Copyright: This software is copyright (c) 2013-2014, 2017 by Toby Inkster.
+License: GPL-1.0+ or Artistic-1.0
+
+Files: COPYRIGHT
+ CREDITS
+ Changes
+ INSTALL
+ LICENSE
+ META.json
+ META.yml
+ Makefile.PL
+ doap.ttl
+Copyright: Copyright 2017 Toby Inkster.
+License: GPL-1.0+ or Artistic-1.0
+
Files: lib/Exporter/Shiny.pm
t/05shiny.t
t/06notwant.t
@@ -10,55 +35,27 @@ Files: lib/Exporter/Shiny.pm
t/08tags.t
t/09warnings.t
t/10no.t
-Copyright: This software is copyright (c) 2014 by Toby Inkster.
+Copyright: This software is copyright (c) 2014, 2017 by Toby Inkster.
License: GPL-1.0+ or Artistic-1.0
-Files: Changes
- META.json
- META.yml
- doap.ttl
-Copyright: Copyright 2014 Toby Inkster.
-License: GPL-1.0+ or Artistic-1.0
-
-Files: CONTRIBUTING
- INSTALL
- LICENSE
+Files: dist.ini
examples/Example/Exporter.pm
-Copyright: Unknown
-License: Unknown
-
-Files: t/01basic.t
- t/02renaming.t
- t/03generators.t
- t/04into.t
-Copyright: This software is copyright (c) 2013 by Toby Inkster.
+Copyright: Copyright 2013 Toby Inkster.
License: GPL-1.0+ or Artistic-1.0
-Files: COPYRIGHT
- CREDITS
- SIGNATURE
+Files: SIGNATURE
Copyright: None
License: public-domain
-Files: README
- lib/Exporter/Tiny.pm
-Copyright: This software is copyright (c) 2013-2014 by Toby Inkster.
-License: GPL-1.0+ or Artistic-1.0
-
-Files: Makefile.PL
- dist.ini
-Copyright: Copyright 2013 Toby Inkster.
-License: GPL-1.0+ or Artistic-1.0
-
License: Artistic-1.0
- This software is Copyright (c) 2014 by the copyright holder(s).
+ This software is Copyright (c) 2017 by the copyright holder(s).
This is free software, licensed under:
The Artistic License 1.0
License: GPL-1.0
- This software is Copyright (c) 2014 by the copyright holder(s).
+ This software is Copyright (c) 2017 by the copyright holder(s).
This is free software, licensed under:
diff --git a/Changes b/Changes
index 2598ecb..e8545f8 100644
--- a/Changes
+++ b/Changes
@@ -6,6 +6,29 @@ Home page: <https://metacpan.org/release/Exporter-Tiny>
Bug tracker: <http://rt.cpan.org/Dist/Display.html?Queue=Exporter-Tiny>
Maintainer: Toby Inkster (TOBYINK) <tobyink at cpan.org>
+1.000000 2017-05-22
+
+ [ Packaging ]
+ - Repackage as 1.000000.
+
+0.044 2017-01-30
+
+ [ Packaging ]
+ - Repackage as a stable release.
+
+0.043_02 2017-01-30
+
+ [ Packaging ]
+ - Release using newer versions of toolchain stuff.
+
+0.043_01 2014-11-09
+
+ [ Documentation ]
+ - Restructure documentation.
+
+ [ Other ]
+ - Support { -as => CODE } to programatically rename functions.
+
0.042 2014-10-04
[ Documentation ]
diff --git a/LICENSE b/LICENSE
index 351778e..3bc8459 100644
--- a/LICENSE
+++ b/LICENSE
@@ -1,4 +1,4 @@
-This software is copyright (c) 2014 by Toby Inkster.
+This software is copyright (c) 2017 by Toby Inkster.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
@@ -12,7 +12,7 @@ b) the "Artistic License"
--- The GNU General Public License, Version 1, February 1989 ---
-This software is Copyright (c) 2014 by Toby Inkster.
+This software is Copyright (c) 2017 by Toby Inkster.
This is free software, licensed under:
@@ -272,7 +272,7 @@ That's all there is to it!
--- The Artistic License 1.0 ---
-This software is Copyright (c) 2014 by Toby Inkster.
+This software is Copyright (c) 2017 by Toby Inkster.
This is free software, licensed under:
diff --git a/MANIFEST b/MANIFEST
index 26d4441..79d2702 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -1,4 +1,3 @@
-CONTRIBUTING
COPYRIGHT
CREDITS
Changes
@@ -15,6 +14,10 @@ doap.ttl
examples/Example/Exporter.pm
lib/Exporter/Shiny.pm
lib/Exporter/Tiny.pm
+lib/Exporter/Tiny/Manual/Etc.pod
+lib/Exporter/Tiny/Manual/Exporting.pod
+lib/Exporter/Tiny/Manual/Importing.pod
+lib/Exporter/Tiny/Manual/QuickStart.pod
t/01basic.t
t/02renaming.t
t/03generators.t
diff --git a/META.json b/META.json
index 79ece81..9af7c24 100644
--- a/META.json
+++ b/META.json
@@ -3,8 +3,8 @@
"author" : [
"Toby Inkster (TOBYINK) <tobyink at cpan.org>"
],
- "dynamic_config" : 0,
- "generated_by" : "Dist::Inkt::Profile::TOBYINK version 0.023, CPAN::Meta::Converter version 2.140640",
+ "dynamic_config" : 1,
+ "generated_by" : "Dist::Inkt::Profile::TOBYINK version 0.024, CPAN::Meta::Converter version 2.150005",
"keywords" : [],
"license" : [
"perl_5"
@@ -48,11 +48,11 @@
"provides" : {
"Exporter::Shiny" : {
"file" : "lib/Exporter/Shiny.pm",
- "version" : "0.042"
+ "version" : "1.000000"
},
"Exporter::Tiny" : {
"file" : "lib/Exporter/Tiny.pm",
- "version" : "0.042"
+ "version" : "1.000000"
}
},
"release_status" : "stable",
@@ -72,5 +72,6 @@
"x_IRC" : "irc://irc.perl.org/#moops",
"x_identifier" : "http://purl.org/NET/cpan-uri/dist/Exporter-Tiny/project"
},
- "version" : "0.042"
+ "version" : "1.000000",
+ "x_serialization_backend" : "JSON::PP version 2.27300_01"
}
diff --git a/META.yml b/META.yml
index d83f602..164864b 100644
--- a/META.yml
+++ b/META.yml
@@ -6,8 +6,8 @@ build_requires:
Test::More: '0.47'
configure_requires:
ExtUtils::MakeMaker: '6.17'
-dynamic_config: 0
-generated_by: 'Dist::Inkt::Profile::TOBYINK version 0.023, CPAN::Meta::Converter version 2.140640'
+dynamic_config: 1
+generated_by: 'Dist::Inkt::Profile::TOBYINK version 0.024, CPAN::Meta::Converter version 2.150005'
keywords: []
license: perl
meta-spec:
@@ -25,10 +25,10 @@ optional_features: {}
provides:
Exporter::Shiny:
file: lib/Exporter/Shiny.pm
- version: '0.042'
+ version: '1.000000'
Exporter::Tiny:
file: lib/Exporter/Tiny.pm
- version: '0.042'
+ version: '1.000000'
requires:
perl: '5.006001'
resources:
@@ -38,4 +38,5 @@ resources:
homepage: https://metacpan.org/release/Exporter-Tiny
license: http://dev.perl.org/licenses/
repository: git://github.com/tobyink/p5-exporter-tiny.git
-version: '0.042'
+version: '1.000000'
+x_serialization_backend: 'CPAN::Meta::YAML version 0.018'
diff --git a/Makefile.PL b/Makefile.PL
index 4578ac2..1f9f53f 100644
--- a/Makefile.PL
+++ b/Makefile.PL
@@ -6,8 +6,8 @@ my $EUMM = eval( $ExtUtils::MakeMaker::VERSION );
my $meta = {
"abstract" => "an exporter with the features of Sub::Exporter but only core dependencies",
"author" => ["Toby Inkster (TOBYINK) <tobyink\@cpan.org>"],
- "dynamic_config" => 0,
- "generated_by" => "Dist::Inkt::Profile::TOBYINK version 0.023, CPAN::Meta::Converter version 2.140640",
+ "dynamic_config" => 1,
+ "generated_by" => "Dist::Inkt::Profile::TOBYINK version 0.024, CPAN::Meta::Converter version 2.150005",
"keywords" => [],
"license" => ["perl_5"],
"meta-spec" => {
@@ -25,8 +25,8 @@ my $meta = {
},
},
"provides" => {
- "Exporter::Shiny" => { file => "lib/Exporter/Shiny.pm", version => 0.042 },
- "Exporter::Tiny" => { file => "lib/Exporter/Tiny.pm", version => 0.042 },
+ "Exporter::Shiny" => { file => "lib/Exporter/Shiny.pm", version => "1.000000" },
+ "Exporter::Tiny" => { file => "lib/Exporter/Tiny.pm", version => "1.000000" },
},
"release_status" => "stable",
"resources" => {
@@ -43,10 +43,16 @@ my $meta = {
x_identifier => "http://purl.org/NET/cpan-uri/dist/Exporter-Tiny/project",
x_IRC => "irc://irc.perl.org/#moops",
},
- "version" => 0.042,
+ "version" => "1.000000",
};
my %dynamic_config;
+do {
+# idk, this should be automatic or summint? put it in explicitly.
+$meta->{prereqs}{runtime}{requires}{'Test::More'} = '0.47'
+ if $] < 5.006002;
+
+};
my %WriteMakefileArgs = (
ABSTRACT => $meta->{abstract},
diff --git a/README b/README
index 6c702ef..8b114b9 100644
--- a/README
+++ b/README
@@ -6,7 +6,7 @@ SYNOPSIS
package MyUtils;
use base "Exporter::Tiny";
our @EXPORT = qw(frobnicate);
- sub frobnicate { my $n = shift; ... }
+ sub frobnicate { ... }
1;
package MyScript;
@@ -18,381 +18,23 @@ DESCRIPTION
Exporter::Tiny supports many of Sub::Exporter's external-facing features
including renaming imported functions with the `-as`, `-prefix` and
`-suffix` options; explicit destinations with the `into` option; and
- alternative installers with the `installler` option. But it's written in
+ alternative installers with the `installer` option. But it's written in
only about 40% as many lines of code and with zero non-core dependencies.
Its internal-facing interface is closer to Exporter.pm, with configuration
done through the @EXPORT, @EXPORT_OK and %EXPORT_TAGS package variables.
- Exporter::Tiny performs most of its internal duties (including resolution
- of tag names to sub names, resolution of sub names to coderefs, and
- installation of coderefs into the target package) as method calls, which
- means they can be overridden to provide interesting behaviour.
+ If you are trying to write a module that inherits from Exporter::Tiny,
+ then look at:
- Utility Functions
- These are really for internal use, but can be exported if you need them.
+ * Exporter::Tiny::Manual::QuickStart
- `mkopt(\@array)`
- Similar to `mkopt` from Data::OptList. It doesn't support all the
- fancy options that Data::OptList does (`moniker`, `require_unique`,
- `must_be` and `name_test`) but runs about 50% faster.
+ * Exporter::Tiny::Manual::Exporting
- `mkopt_hash(\@array)`
- Similar to `mkopt_hash` from Data::OptList. See also `mkopt`.
+ If you are trying to use a module that inherits from Exporter::Tiny, then
+ look at:
-TIPS AND TRICKS IMPORTING FROM EXPORTER::TINY
- For the purposes of this discussion we'll assume we have a module called
- `MyUtils` which exports one function, `frobnicate`. `MyUtils` inherits
- from Exporter::Tiny.
-
- Many of these tricks may seem familiar from Sub::Exporter. That is
- intentional. Exporter::Tiny doesn't attempt to provide every feature of
- Sub::Exporter, but where it does it usually uses a fairly similar API.
-
- Basic importing
- # import "frobnicate" function
- use MyUtils "frobnicate";
-
- # import all functions that MyUtils offers
- use MyUtils -all;
-
- Renaming imported functions
- # call it "frob"
- use MyUtils "frobnicate" => { -as => "frob" };
-
- # call it "my_frobnicate"
- use MyUtils "frobnicate" => { -prefix => "my_" };
-
- # can set a prefix for *all* functions imported from MyUtils
- # by placing the options hashref *first*.
- use MyUtils { prefix => "my_" }, "frobnicate";
- # (note the lack of hyphen before `prefix`.)
-
- # call it "frobnicate_util"
- use MyUtils "frobnicate" => { -suffix => "_util" };
- use MyUtils { suffix => "_util" }, "frobnicate";
-
- # import it twice with two different names
- use MyUtils
- "frobnicate" => { -as => "frob" },
- "frobnicate" => { -as => "frbnct" };
-
- Lexical subs
- {
- use Sub::Exporter::Lexical lexical_installer => { -as => "lex" };
- use MyUtils { installer => lex }, "frobnicate";
-
- frobnicate(...); # ok
- }
-
- frobnicate(...); # not ok
-
- Import functions into another package
- use MyUtils { into => "OtherPkg" }, "frobnicate";
-
- OtherPkg::frobincate(...);
-
- Import functions into a scalar
- my $func;
- use MyUtils "frobnicate" => { -as => \$func };
-
- $func->(...);
-
- Import functions into a hash
- OK, Sub::Exporter doesn't do this...
-
- my %funcs;
- use MyUtils { into => \%funcs }, "frobnicate";
-
- $funcs{frobnicate}->(...);
-
- DO NOT WANT!
- This imports everything except "frobnicate":
-
- use MyUtils qw( -all !frobnicate );
-
- Negated imports always "win", so the following will not import
- "frobnicate", no matter how many times you repeat it...
-
- use MyUtils qw( !frobnicate frobnicate frobnicate frobnicate );
-
- Importing by regexp
- Here's how you could import all functions beginning with an "f":
-
- use MyUtils qw( /^F/i );
-
- Or import everything except functions beginning with a "z":
-
- use MyUtils qw( -all !/^Z/i );
-
- Note that regexps are always supplied as *strings* starting with "/", and
- not as quoted regexp references (`qr/.../`).
-
- Unimporting
- You can unimport the functions that MyUtils added to your namespace:
-
- no MyUtils;
-
- Or just specific ones:
-
- no MyUtils qw(frobnicate);
-
- If you renamed a function when you imported it, you should unimport by the
- new name:
-
- use MyUtils frobnicate => { -as => "frob" };
- ...;
- no MyUtils "frob";
-
- Unimporting using tags and regexps should mostly do what you want.
-
-TIPS AND TRICKS EXPORTING USING EXPORTER::TINY
- Simple configuration works the same as Exporter; inherit from this module,
- and use the @EXPORT, @EXPORT_OK and %EXPORT_TAGS package variables to list
- subs to export.
-
- Generators
- Exporter::Tiny has always allowed exported subs to be generated (like
- Sub::Exporter), but until version 0.025 did not have an especially nice
- API for it.
-
- Now, it's easy. If you want to generate a sub `foo` to export, list it in
- @EXPORT or @EXPORT_OK as usual, and then simply give your exporter module
- a class method called `_generate_foo`.
-
- push @EXPORT_OK, 'foo';
-
- sub _generate_foo {
- my $class = shift;
- my ($name, $args, $globals) = @_;
-
- return sub {
- ...;
- }
- }
-
- You can also generate tags:
-
- my %constants;
- BEGIN {
- %constants = (FOO => 1, BAR => 2);
- }
- use constant \%constants;
-
- $EXPORT_TAGS{constants} = sub {
- my $class = shift;
- my ($name, $args, $globals) = @_;
-
- return keys(%constants);
- };
-
- Overriding Internals
- An important difference between Exporter and Exporter::Tiny is that the
- latter calls all its internal functions as *class methods*. This means
- that your subclass can *override them* to alter their behaviour.
-
- The following methods are available to be overridden. Despite being named
- with a leading underscore, they are considered public methods. (The
- underscore is there to avoid accidentally colliding with any of your own
- function names.)
-
- `_exporter_validate_opts($globals)`
- This method is called once each time `import` is called. It is passed
- a reference to the global options hash. (That is, the optional leading
- hashref in the `use` statement, where the `into` and `installer`
- options can be provided.)
-
- You may use this method to munge the global options, or validate them,
- throwing an exception or printing a warning.
-
- The default implementation does nothing interesting.
-
- `_exporter_validate_unimport_opts($globals)`
- Like `_exporter_validate_opts`, but called for `unimport`.
-
- `_exporter_merge_opts($tag_opts, $globals, @exports)`
- Called to merge options which have been provided for a tag into the
- options provided for the exports that the tag expanded to.
-
- `_exporter_expand_tag($name, $args, $globals)`
- This method is called to expand an import tag (e.g. ":constants"). It
- is passed the tag name (minus the leading ":"), an optional hashref of
- options (like `{ -prefix => "foo_" }`), and the global options
- hashref.
-
- It is expected to return a list of ($name, $args) arrayref pairs.
- These names can be sub names to export, or further tag names (which
- must have their ":"). If returning tag names, be careful to avoid
- creating a tag expansion loop!
-
- The default implementation uses %EXPORT_TAGS to expand tags, and
- provides fallbacks for the `:default` and `:all` tags.
-
- `_exporter_expand_regexp($regexp, $args, $globals)`
- Like `_exporter_expand_regexp`, but given a regexp-like string instead
- of a tag name.
-
- The default implementation greps through @EXPORT_OK for imports, and
- the list of already-imported functions for exports.
-
- `_exporter_expand_sub($name, $args, $globals)`
- This method is called to translate a sub name to a hash of name =>
- coderef pairs for exporting to the caller. In general, this would just
- be a hash with one key and one value, but, for example, Type::Library
- overrides this method so that "+Foo" gets expanded to:
-
- (
- Foo => sub { $type },
- is_Foo => sub { $type->check(@_) },
- to_Foo => sub { $type->assert_coerce(@_) },
- assert_Foo => sub { $type->assert_return(@_) },
- )
-
- The default implementation checks that the name is allowed to be
- exported (using the `_exporter_permitted_regexp` method), gets the
- coderef using the generator if there is one (or by calling `can` on
- your exporter otherwise) and calls `_exporter_fail` if it's unable to
- generate or retrieve a coderef.
-
- `_exporter_permitted_regexp($globals)`
- This method is called to retrieve a regexp for validating the names of
- exportable subs. If a sub doesn't match the regexp, then the default
- implementation of `_exporter_expand_sub` will refuse to export it. (Of
- course, you may override the default `_exporter_expand_sub`.)
-
- The default implementation of this method assembles the regexp from
- @EXPORT and @EXPORT_OK.
-
- `_exporter_fail($name, $args, $globals)`
- Called by `_exporter_expand_sub` if it can't find a coderef to export.
-
- The default implementation just throws an exception. But you could
- emit a warning instead, or just ignore the failed export.
-
- If you don't throw an exception then you should be aware that this
- method is called in list context, and any list it returns will be
- treated as an `_exporter_expand_sub`-style hash of names and coderefs
- for export.
-
- `_exporter_install_sub($name, $args, $globals, $coderef)`
- This method actually installs the exported sub into its new
- destination. Its return value is ignored.
-
- The default implementation handles sub renaming (i.e. the `-as`,
- `-prefix` and `-suffix` functions. This method does a lot of stuff; if
- you need to override it, it's probably a good idea to just pre-process
- the arguments and then call the super method rather than trying to
- handle all of it yourself.
-
- `_exporter_uninstall_sub($name, $args, $globals)`
- The opposite of `_exporter_install_sub`.
-
-DIAGNOSTICS
- Overwriting existing sub '%s::%s' with sub '%s' exported by %s
- A warning issued if Exporter::Tiny is asked to export a symbol which
- will result in an existing sub being overwritten. This warning can be
- suppressed using either of the following:
-
- use MyUtils { replace => 1 }, "frobnicate";
- use MyUtils "frobnicate" => { -replace => 1 };
-
- Or can be upgraded to a fatal error:
-
- use MyUtils { replace => "die" }, "frobnicate";
- use MyUtils "frobnicate" => { -replace => "die" };
-
- Refusing to overwrite existing sub '%s::%s' with sub '%s' exported by %s
- The fatal version of the above warning.
-
- Could not find sub '%s' exported by %s
- You requested to import a sub which the package does not provide.
-
- Cannot provide an -as option for tags
- Because a tag may provide more than one function, it does not make
- sense to request a single name for it. Instead use `-prefix` or
- `-suffix`.
-
- Passing options to unimport '%s' makes no sense
- When you import a sub, it occasionally makes sense to pass some
- options for it. However, when unimporting, options do nothing, so this
- warning is issued.
-
-HISTORY
- Type::Library had a bunch of custom exporting code which poked coderefs
- into its caller's stash. It needed this to be something more powerful than
- most exporters so that it could switch between exporting Moose, Mouse and
- Moo-compatible objects on request. Sub::Exporter would have been capable,
- but had too many dependencies for the Type::Tiny project.
-
- Meanwhile Type::Utils, Types::TypeTiny and Test::TypeTiny each used the
- venerable Exporter.pm. However, this meant they were unable to use the
- features like Sub::Exporter-style function renaming which I'd built into
- Type::Library:
-
- ## import "Str" but rename it to "String".
- use Types::Standard "Str" => { -as => "String" };
-
- And so I decided to factor out code that could be shared by all
- Type-Tiny's exporters into a single place: Exporter::TypeTiny.
-
- As of version 0.026, Exporter::TypeTiny was also made available as
- Exporter::Tiny, distributed independently on CPAN. CHOCOLATEBOY had
- convinced me that it was mature enough to live a life of its own.
-
- As of version 0.030, Type-Tiny depends on Exporter::Tiny and
- Exporter::TypeTiny is being phased out.
-
-OBLIGATORY EXPORTER COMPARISON
- Exporting is unlikely to be your application's performance bottleneck, but
- nonetheless here are some comparisons.
-
- Comparative sizes according to Devel::SizeMe:
-
- Exporter 217.1Kb
- Sub::Exporter::Progressive 263.2Kb
- Exporter::Tiny 267.7Kb
- Exporter + Exporter::Heavy 281.5Kb
- Exporter::Renaming 406.2Kb
- Sub::Exporter 701.0Kb
-
- Performance exporting a single sub:
-
- Rate SubExp ExpTiny SubExpProg ExpPM
- SubExp 2489/s -- -56% -85% -88%
- ExpTiny 5635/s 126% -- -67% -72%
- SubExpProg 16905/s 579% 200% -- -16%
- ExpPM 20097/s 707% 257% 19% --
-
- (Exporter::Renaming globally changes the behaviour of Exporter.pm, so
- could not be included in the same benchmarks.)
-
- (Non-Core) Dependencies:
-
- Exporter -1
- Exporter::Renaming 0
- Exporter::Tiny 0
- Sub::Exporter::Progressive 0
- Sub::Exporter 3
-
- Features:
-
- ExpPM ExpTiny SubExp SubExpProg
- Can export code symbols............. Yes Yes Yes Yes
- Can export non-code symbols......... Yes
- Groups/tags......................... Yes Yes Yes Yes
- Export by regexp.................... Yes Yes
- Bang prefix......................... Yes Yes
- Allows renaming of subs............. Yes Yes Maybe
- Install code into scalar refs....... Yes Yes Maybe
- Can be passed an "into" parameter... Yes Yes Maybe
- Can be passed an "installer" sub.... Yes Yes Maybe
- Config avoids package variables..... Yes
- Supports generators................. Yes Yes
- Sane API for generators............. Yes Yes
- Unimport............................ Yes
-
- (Certain Sub::Exporter::Progressive features are only available if
- Sub::Exporter is installed.)
+ * Exporter::Tiny::Manual::Importing
BUGS
Please report any bugs to
@@ -403,13 +45,15 @@ SUPPORT
<http://www.irc.perl.org/channels.html>.
SEE ALSO
- Exporter::Shiny, Sub::Exporter, Exporter.
+ Simplified interface to this module: Exporter::Shiny.
+
+ Other interesting exporters: Sub::Exporter, Exporter.
AUTHOR
Toby Inkster <tobyink at cpan.org>.
COPYRIGHT AND LICENCE
- This software is copyright (c) 2013-2014 by Toby Inkster.
+ This software is copyright (c) 2013-2014, 2017 by Toby Inkster.
This is free software; you can redistribute it and/or modify it under the
same terms as the Perl 5 programming language system itself.
diff --git a/SIGNATURE b/SIGNATURE
index 4d30a89..ad0d1c6 100644
--- a/SIGNATURE
+++ b/SIGNATURE
@@ -1,5 +1,5 @@
This file contains message digests of all files listed in MANIFEST,
-signed via the Module::Signature module, version 0.73.
+signed via the Module::Signature module, version 0.81.
To verify the content in this distribution, first make sure you have
Module::Signature installed, then type:
@@ -14,36 +14,39 @@ not run its Makefile.PL or Build.PL.
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
-SHA1 33317486c4fa2cf7fec85bf92ed38ac0f64233a0 CONTRIBUTING
-SHA1 5980cc638348a4f7438480d881a82ae5e17a1630 COPYRIGHT
+SHA1 58970c16dff93a4e1d6e8c405c5bc8188be49799 COPYRIGHT
SHA1 e3b0c464bb56d4285fa64e31a70b301692dd825c CREDITS
-SHA1 5c7b2ac127f2c84b4bac86a882a671fe17a933e3 Changes
+SHA1 0e8eebbb4ee5e34fb15e90510bdf54d53a539c3c Changes
SHA1 3b20e9835f489bbf71b1deb6aa7c10729482aa77 INSTALL
-SHA1 34f5e12514b91055de4b164a1f2327ef5c30ba53 LICENSE
-SHA1 7d98e1b385b7b5d70cb9a1497eea3b233f4baa8a MANIFEST
-SHA1 525d4669e3507fc769ab765d6438218af3e9adbb META.json
-SHA1 e50e4613cc1d1abd87c290d1f2953eedad430de2 META.yml
-SHA1 1c9cf0c5db5b9abf7a137c2db5eebd93baafce48 Makefile.PL
-SHA1 29f2538f2e202b70d54cf08d0d7499fa7ddf4c5d README
+SHA1 c4c1e6c578edcfd14d13eadebc8f56dd9ca46821 LICENSE
+SHA1 97bc2eb47523ed9f03f47271b29959b1f3edce24 MANIFEST
+SHA1 d262494ba318b185a27a034e950663303120ed94 META.json
+SHA1 5ae4c8c6bbdeb24edd37b2024ec4139be090a7a1 META.yml
+SHA1 9d43607022577d07f3a2df4494a4f743809d2f9e Makefile.PL
+SHA1 2d5592860cac601d95b1a00863f3b4fc29639d2f README
SHA1 a43593d3e3a79c5f455977ba75083d9f191f6af6 dist.ini
-SHA1 066ce57aee9422a1789f0b42a968b3bb16a4c117 doap.ttl
+SHA1 0fdb2b1f95a4562ece610412c6c78cc7e6a2adc2 doap.ttl
SHA1 3f65666b300ab7e7a1e5e25fb69e4ce6675e0f63 examples/Example/Exporter.pm
-SHA1 90df17b2a1b5cf0ddf5e81d7f8c6fcdf6152f800 lib/Exporter/Shiny.pm
-SHA1 57ff9abef5131446f439a23224522805307fc743 lib/Exporter/Tiny.pm
-SHA1 6ba2757140a1c118ae5bac4c10ea8a6275ee15f2 t/01basic.t
-SHA1 8b9c883098fbdaf8999c6f8f909a79297870af86 t/02renaming.t
-SHA1 103845d83b41f8d3c503d50e9d6012790b25f77f t/03generators.t
-SHA1 6a20cb44b8b22885209f6c3f30cbcf5adb80c52c t/04into.t
-SHA1 e50bb7649f42c23b8873dd2e72ef63d85e443b28 t/05shiny.t
-SHA1 8c545aab416cd36ee4fde0cc50cf6b59200a9aac t/06notwant.t
-SHA1 803a876d8e5e5b5af567f7a3a6e7a1071a4a48ed t/07regexp.t
-SHA1 dbce3f55c87fefdfe5abba21afa5a9c9a9a08cf0 t/08tags.t
-SHA1 9cc0bdbc9fd24f98161b4d314bc7c841f2fa8efc t/09warnings.t
-SHA1 2b5c5da82a5c8f2d69d46915b9921d2ceb6ca214 t/10no.t
+SHA1 4b548adad97a2f9a52c6d691af847f829e850684 lib/Exporter/Shiny.pm
+SHA1 fc49e39bcb17b8124912d64f43c52c2db4a2a08e lib/Exporter/Tiny.pm
+SHA1 0e4aab8c35fbbdb9f7d7bad7ca0b09dbdcf49622 lib/Exporter/Tiny/Manual/Etc.pod
+SHA1 5d0f275559385cbd4fe9da7b5d815af5d65151ef lib/Exporter/Tiny/Manual/Exporting.pod
+SHA1 6c9e12d234866ef242447be427583ea4cdba85a9 lib/Exporter/Tiny/Manual/Importing.pod
+SHA1 d3490992563cb4fc178b9d1da0a7449a1f726560 lib/Exporter/Tiny/Manual/QuickStart.pod
+SHA1 634706978c1b96226b35b763bfec74602303dbc6 t/01basic.t
+SHA1 287d93a6d4ea7364f251dfabc18f49911eb34278 t/02renaming.t
+SHA1 25a63815d24aff25751dc194be0c4cc950c47104 t/03generators.t
+SHA1 99b8cbf69c65338c0b502b0351b5580c306235f3 t/04into.t
+SHA1 db0c8bf9facceb64971e5eeebd6592508d9335dd t/05shiny.t
+SHA1 f97e9d2cb58bf5fab88585a2b215c2840c129b00 t/06notwant.t
+SHA1 db742ca2aac48c6fa0fb167796726d520f00d49b t/07regexp.t
+SHA1 1f08eb2996c19c4f85483d9b66d0223dd3da80f1 t/08tags.t
+SHA1 57670cc5578a2aaf3932c18bf2c379b710229675 t/09warnings.t
+SHA1 11c0f79936b27cfd46bf5f27c1e8cb7455a6463f t/10no.t
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1
-iEYEARECAAYFAlQwL/wACgkQzr+BKGoqfTkonACeP1ZH9sdg3mJTHQpxoxdgTNQP
-I8YAnjYQAQLXP2fg8wYUZKcbDS5aFJml
-=JZvp
+iEYEARECAAYFAlkixzcACgkQzr+BKGoqfTk6UQCeKkh68lWNgfAXaP8c63pASGhD
+A9UAoI5BKRLBiajpluddNiiXxqvuIS+A
+=fuCC
-----END PGP SIGNATURE-----
diff --git a/doap.ttl b/doap.ttl
index 29c03f0..23ead1d 100644
--- a/doap.ttl
+++ b/doap.ttl
@@ -4,6 +4,7 @@
@prefix doap-changeset: <http://ontologi.es/doap-changeset#> .
@prefix doap-deps: <http://ontologi.es/doap-deps#> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
+ at prefix nfo: <http://www.semanticdesktop.org/ontologies/2007/03/22/nfo#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@@ -26,7 +27,7 @@
doap:maintainer <http://purl.org/NET/cpan-uri/person/tobyink>;
doap:name "Exporter-Tiny";
doap:programming-language "Perl";
- doap:release <http://purl.org/NET/cpan-uri/dist/Exporter-Tiny/v_0-026>, <http://purl.org/NET/cpan-uri/dist/Exporter-Tiny/v_0-029_01>, <http://purl.org/NET/cpan-uri/dist/Exporter-Tiny/v_0-030>, <http://purl.org/NET/cpan-uri/dist/Exporter-Tiny/v_0-031_01>, <http://purl.org/NET/cpan-uri/dist/Exporter-Tiny/v_0-032>, <http://purl.org/NET/cpan-uri/dist/Exporter-Tiny/v_0-033_01>, <http://purl.org/NET/cpan-uri/dist/Exporter-Tiny/v_0-034>, <http://purl.org/NET/cpan-uri/dist/Exporter-Tiny [...]
+ doap:release <http://purl.org/NET/cpan-uri/dist/Exporter-Tiny/v_0-026>, <http://purl.org/NET/cpan-uri/dist/Exporter-Tiny/v_0-029_01>, <http://purl.org/NET/cpan-uri/dist/Exporter-Tiny/v_0-030>, <http://purl.org/NET/cpan-uri/dist/Exporter-Tiny/v_0-031_01>, <http://purl.org/NET/cpan-uri/dist/Exporter-Tiny/v_0-032>, <http://purl.org/NET/cpan-uri/dist/Exporter-Tiny/v_0-033_01>, <http://purl.org/NET/cpan-uri/dist/Exporter-Tiny/v_0-034>, <http://purl.org/NET/cpan-uri/dist/Exporter-Tiny [...]
doap:repository [
a doap:GitRepository;
doap:browse <https://github.com/tobyink/p5-exporter-tiny>;
@@ -318,6 +319,69 @@
doap:file-release <http://backpan.cpan.org/authors/id/T/TO/TOBYINK/Exporter-Tiny-0.042.tar.gz>;
doap:revision "0.042"^^xsd:string.
+<http://purl.org/NET/cpan-uri/dist/Exporter-Tiny/v_0-043_01>
+ a cpan-uri:DeveloperRelease, doap:Version;
+ dc:identifier "Exporter-Tiny-0.043_01"^^xsd:string;
+ dc:issued "2014-11-09"^^xsd:date;
+ doap-changeset:changeset [
+ doap-changeset:item [
+ a doap-changeset:Documentation;
+ rdfs:label "Restructure documentation.";
+ ], [
+ a doap-changeset:Change;
+ rdfs:label "Support { -as => CODE } to programatically rename functions.";
+ ];
+ doap-changeset:versus <http://purl.org/NET/cpan-uri/dist/Exporter-Tiny/v_0-042>;
+ ];
+ doap-changeset:released-by <http://purl.org/NET/cpan-uri/person/tobyink>;
+ doap:file-release <http://backpan.cpan.org/authors/id/T/TO/TOBYINK/Exporter-Tiny-0.043_01.tar.gz>;
+ doap:revision "0.043_01"^^xsd:string.
+
+<http://purl.org/NET/cpan-uri/dist/Exporter-Tiny/v_0-043_02>
+ a cpan-uri:DeveloperRelease, doap:Version;
+ dc:identifier "Exporter-Tiny-0.043_02"^^xsd:string;
+ dc:issued "2017-01-30"^^xsd:date;
+ doap-changeset:changeset [
+ doap-changeset:item [
+ a doap-changeset:Packaging;
+ rdfs:label "Release using newer versions of toolchain stuff.";
+ ];
+ doap-changeset:versus <http://purl.org/NET/cpan-uri/dist/Exporter-Tiny/v_0-043_01>;
+ ];
+ doap-changeset:released-by <http://purl.org/NET/cpan-uri/person/tobyink>;
+ doap:file-release <http://backpan.cpan.org/authors/id/T/TO/TOBYINK/Exporter-Tiny-0.043_02.tar.gz>;
+ doap:revision "0.043_02"^^xsd:string.
+
+<http://purl.org/NET/cpan-uri/dist/Exporter-Tiny/v_0-044>
+ a doap:Version;
+ dc:identifier "Exporter-Tiny-0.044"^^xsd:string;
+ dc:issued "2017-01-30"^^xsd:date;
+ doap-changeset:changeset [
+ doap-changeset:item [
+ a doap-changeset:Packaging;
+ rdfs:label "Repackage as a stable release.";
+ ];
+ doap-changeset:versus <http://purl.org/NET/cpan-uri/dist/Exporter-Tiny/v_0-043_02>;
+ ];
+ doap-changeset:released-by <http://purl.org/NET/cpan-uri/person/tobyink>;
+ doap:file-release <http://backpan.cpan.org/authors/id/T/TO/TOBYINK/Exporter-Tiny-0.044.tar.gz>;
+ doap:revision "0.044"^^xsd:string.
+
+<http://purl.org/NET/cpan-uri/dist/Exporter-Tiny/v_1-000000>
+ a doap:Version;
+ dc:identifier "Exporter-Tiny-1.000000"^^xsd:string;
+ dc:issued "2017-05-22"^^xsd:date;
+ doap-changeset:changeset [
+ doap-changeset:item [
+ a doap-changeset:Packaging;
+ rdfs:label "Repackage as 1.000000.";
+ ];
+ doap-changeset:versus <http://purl.org/NET/cpan-uri/dist/Exporter-Tiny/v_0-044>;
+ ];
+ doap-changeset:released-by <http://purl.org/NET/cpan-uri/person/tobyink>;
+ doap:file-release <http://backpan.cpan.org/authors/id/T/TO/TOBYINK/Exporter-Tiny-1.000000.tar.gz>;
+ doap:revision "1.000000"^^xsd:string.
+
<http://purl.org/NET/cpan-uri/dist/Type-Tiny/project>
a doap:Project;
dc:contributor <http://purl.org/NET/cpan-uri/person/tobyink>;
@@ -346,3 +410,41 @@
foaf:nick "TOBYINK";
foaf:page <https://metacpan.org/author/TOBYINK>.
+[]
+ a nfo:FileDataObject;
+ dc:license <http://dev.perl.org/licenses/>;
+ dc:rightsHolder <http://purl.org/NET/cpan-uri/person/tobyink>;
+ nfo:fileName "COPYRIGHT".
+
+[]
+ a nfo:FileDataObject;
+ dc:license <http://dev.perl.org/licenses/>;
+ dc:rightsHolder <http://purl.org/NET/cpan-uri/person/tobyink>;
+ nfo:fileName "CREDITS".
+
+[]
+ a nfo:FileDataObject, nfo:TextDocument;
+ dc:license <http://dev.perl.org/licenses/>;
+ dc:rightsHolder <http://purl.org/NET/cpan-uri/person/tobyink>;
+ nfo:fileName "INSTALL".
+
+[]
+ a nfo:FileDataObject, nfo:TextDocument;
+ dc:license <http://dev.perl.org/licenses/>;
+ dc:rightsHolder <http://purl.org/NET/cpan-uri/person/tobyink>;
+ nfo:fileName "LICENSE".
+
+[]
+ a nfo:FileDataObject, nfo:SourceCode;
+ dc:license <http://dev.perl.org/licenses/>;
+ dc:rightsHolder <http://purl.org/NET/cpan-uri/person/tobyink>;
+ nfo:fileName "Makefile.PL";
+ nfo:programmingLanguage "Perl".
+
+[]
+ a nfo:FileDataObject, nfo:SourceCode;
+ dc:license <http://dev.perl.org/licenses/>;
+ dc:rightsHolder <http://purl.org/NET/cpan-uri/person/tobyink>;
+ nfo:fileName "examples/Example/Exporter.pm";
+ nfo:programmingLanguage "Perl".
+
diff --git a/lib/Exporter/Shiny.pm b/lib/Exporter/Shiny.pm
index 063cb47..f119409 100644
--- a/lib/Exporter/Shiny.pm
+++ b/lib/Exporter/Shiny.pm
@@ -7,7 +7,7 @@ use warnings;
use Exporter::Tiny ();
our $AUTHORITY = 'cpan:TOBYINK';
-our $VERSION = '0.042';
+our $VERSION = '1.000000';
sub import {
my $me = shift;
@@ -90,7 +90,12 @@ L<http://rt.cpan.org/Dist/Display.html?Queue=Exporter-Tiny>.
=head1 SEE ALSO
-L<Exporter::Tiny>.
+This module is just a wrapper around L<Exporter::Tiny>, so take a look
+at L<Exporter::Tiny::Manual::QuickStart> and
+L<Exporter::Tiny::Manual::Exporting> for further information on what
+features are available.
+
+Other interesting exporters: L<Sub::Exporter>, L<Exporter>.
=head1 AUTHOR
@@ -98,7 +103,7 @@ Toby Inkster E<lt>tobyink at cpan.orgE<gt>.
=head1 COPYRIGHT AND LICENCE
-This software is copyright (c) 2014 by Toby Inkster.
+This software is copyright (c) 2014, 2017 by Toby Inkster.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
diff --git a/lib/Exporter/Tiny.pm b/lib/Exporter/Tiny.pm
index 6e77338..6a45d1a 100644
--- a/lib/Exporter/Tiny.pm
+++ b/lib/Exporter/Tiny.pm
@@ -5,7 +5,7 @@ use strict;
use warnings; no warnings qw(void once uninitialized numeric redefine);
our $AUTHORITY = 'cpan:TOBYINK';
-our $VERSION = '0.042';
+our $VERSION = '1.000000';
our @EXPORT_OK = qw< mkopt mkopt_hash _croak _carp >;
sub _croak ($;@) { require Carp; my $fmt = shift; @_ = sprintf($fmt, @_); goto \&Carp::croak }
@@ -116,7 +116,7 @@ sub _exporter_merge_opts
$tag_opts = {} unless ref($tag_opts) eq q(HASH);
_croak('Cannot provide an -as option for tags')
- if exists $tag_opts->{-as};
+ if exists $tag_opts->{-as} && ref $tag_opts->{-as} ne 'CODE';
my $optlist = mkopt(\@stuff);
for my $export (@$optlist)
@@ -239,16 +239,23 @@ sub _exporter_install_sub
my $into = $globals->{into};
my $installer = $globals->{installer} || $globals->{exporter};
- $name = $value->{-as} || $name;
- unless (ref($name) eq q(SCALAR))
+ $name =
+ ref $globals->{as} ? $globals->{as}->($name) :
+ ref $value->{-as} ? $value->{-as}->($name) :
+ exists $value->{-as} ? $value->{-as} :
+ $name;
+
+ return unless defined $name;
+
+ unless (ref($name))
{
my ($prefix) = grep defined, $value->{-prefix}, $globals->{prefix}, q();
my ($suffix) = grep defined, $value->{-suffix}, $globals->{suffix}, q();
$name = "$prefix$name$suffix";
}
- return ($$name = $sym) if ref($name) eq q(SCALAR);
- return ($into->{$name} = $sym) if ref($into) eq q(HASH);
+ return ($$name = $sym) if ref($name) eq q(SCALAR);
+ return ($into->{$name} = $sym) if ref($into) eq q(HASH);
no strict qw(refs);
@@ -364,7 +371,7 @@ Exporter::Tiny - an exporter with the features of Sub::Exporter but only core de
package MyUtils;
use base "Exporter::Tiny";
our @EXPORT = qw(frobnicate);
- sub frobnicate { my $n = shift; ... }
+ sub frobnicate { ... }
1;
package MyScript;
@@ -377,427 +384,39 @@ Exporter::Tiny - an exporter with the features of Sub::Exporter but only core de
Exporter::Tiny supports many of Sub::Exporter's external-facing features
including renaming imported functions with the C<< -as >>, C<< -prefix >> and
C<< -suffix >> options; explicit destinations with the C<< into >> option;
-and alternative installers with the C<< installler >> option. But it's written
+and alternative installers with the C<< installer >> option. But it's written
in only about 40% as many lines of code and with zero non-core dependencies.
Its internal-facing interface is closer to Exporter.pm, with configuration
done through the C<< @EXPORT >>, C<< @EXPORT_OK >> and C<< %EXPORT_TAGS >>
package variables.
-Exporter::Tiny performs most of its internal duties (including resolution
-of tag names to sub names, resolution of sub names to coderefs, and
-installation of coderefs into the target package) as method calls, which
-means they can be overridden to provide interesting behaviour.
-
-=head2 Utility Functions
-
-These are really for internal use, but can be exported if you need them.
-
-=over
-
-=item C<< mkopt(\@array) >>
-
-Similar to C<mkopt> from L<Data::OptList>. It doesn't support all the
-fancy options that Data::OptList does (C<moniker>, C<require_unique>,
-C<must_be> and C<name_test>) but runs about 50% faster.
-
-=item C<< mkopt_hash(\@array) >>
-
-Similar to C<mkopt_hash> from L<Data::OptList>. See also C<mkopt>.
-
-=back
-
-=head1 TIPS AND TRICKS IMPORTING FROM EXPORTER::TINY
-
-For the purposes of this discussion we'll assume we have a module called
-C<< MyUtils >> which exports one function, C<< frobnicate >>. C<< MyUtils >>
-inherits from Exporter::Tiny.
-
-Many of these tricks may seem familiar from L<Sub::Exporter>. That is
-intentional. Exporter::Tiny doesn't attempt to provide every feature of
-Sub::Exporter, but where it does it usually uses a fairly similar API.
-
-=head2 Basic importing
-
- # import "frobnicate" function
- use MyUtils "frobnicate";
-
- # import all functions that MyUtils offers
- use MyUtils -all;
-
-=head2 Renaming imported functions
-
- # call it "frob"
- use MyUtils "frobnicate" => { -as => "frob" };
-
- # call it "my_frobnicate"
- use MyUtils "frobnicate" => { -prefix => "my_" };
-
- # can set a prefix for *all* functions imported from MyUtils
- # by placing the options hashref *first*.
- use MyUtils { prefix => "my_" }, "frobnicate";
- # (note the lack of hyphen before `prefix`.)
-
- # call it "frobnicate_util"
- use MyUtils "frobnicate" => { -suffix => "_util" };
- use MyUtils { suffix => "_util" }, "frobnicate";
-
- # import it twice with two different names
- use MyUtils
- "frobnicate" => { -as => "frob" },
- "frobnicate" => { -as => "frbnct" };
-
-=head2 Lexical subs
-
- {
- use Sub::Exporter::Lexical lexical_installer => { -as => "lex" };
- use MyUtils { installer => lex }, "frobnicate";
-
- frobnicate(...); # ok
- }
-
- frobnicate(...); # not ok
-
-=head2 Import functions into another package
-
- use MyUtils { into => "OtherPkg" }, "frobnicate";
-
- OtherPkg::frobincate(...);
-
-=head2 Import functions into a scalar
-
- my $func;
- use MyUtils "frobnicate" => { -as => \$func };
-
- $func->(...);
-
-=head2 Import functions into a hash
-
-OK, Sub::Exporter doesn't do this...
-
- my %funcs;
- use MyUtils { into => \%funcs }, "frobnicate";
-
- $funcs{frobnicate}->(...);
-
-=head2 DO NOT WANT!
-
-This imports everything except "frobnicate":
-
- use MyUtils qw( -all !frobnicate );
-
-Negated imports always "win", so the following will not import
-"frobnicate", no matter how many times you repeat it...
-
- use MyUtils qw( !frobnicate frobnicate frobnicate frobnicate );
-
-=head2 Importing by regexp
-
-Here's how you could import all functions beginning with an "f":
-
- use MyUtils qw( /^F/i );
-
-Or import everything except functions beginning with a "z":
-
- use MyUtils qw( -all !/^Z/i );
-
-Note that regexps are always supplied as I<strings> starting with
-C<< "/" >>, and not as quoted regexp references (C<< qr/.../ >>).
-
-=head2 Unimporting
-
-You can unimport the functions that MyUtils added to your namespace:
-
- no MyUtils;
-
-Or just specific ones:
-
- no MyUtils qw(frobnicate);
-
-If you renamed a function when you imported it, you should unimport by
-the new name:
-
- use MyUtils frobnicate => { -as => "frob" };
- ...;
- no MyUtils "frob";
-
-Unimporting using tags and regexps should mostly do what you want.
-
-=head1 TIPS AND TRICKS EXPORTING USING EXPORTER::TINY
-
-Simple configuration works the same as L<Exporter>; inherit from this module,
-and use the C<< @EXPORT >>, C<< @EXPORT_OK >> and C<< %EXPORT_TAGS >>
-package variables to list subs to export.
-
-=head2 Generators
-
-Exporter::Tiny has always allowed exported subs to be generated (like
-L<Sub::Exporter>), but until version 0.025 did not have an especially nice
-API for it.
-
-Now, it's easy. If you want to generate a sub C<foo> to export, list it in
-C<< @EXPORT >> or C<< @EXPORT_OK >> as usual, and then simply give your
-exporter module a class method called C<< _generate_foo >>.
-
- push @EXPORT_OK, 'foo';
-
- sub _generate_foo {
- my $class = shift;
- my ($name, $args, $globals) = @_;
-
- return sub {
- ...;
- }
- }
-
-You can also generate tags:
-
- my %constants;
- BEGIN {
- %constants = (FOO => 1, BAR => 2);
- }
- use constant \%constants;
-
- $EXPORT_TAGS{constants} = sub {
- my $class = shift;
- my ($name, $args, $globals) = @_;
-
- return keys(%constants);
- };
-
-=head2 Overriding Internals
-
-An important difference between L<Exporter> and Exporter::Tiny is that
-the latter calls all its internal functions as I<< class methods >>. This
-means that your subclass can I<< override them >> to alter their behaviour.
-
-The following methods are available to be overridden. Despite being named
-with a leading underscore, they are considered public methods. (The underscore
-is there to avoid accidentally colliding with any of your own function names.)
+If you are trying to B<write> a module that inherits from Exporter::Tiny,
+then look at:
=over
-=item C<< _exporter_validate_opts($globals) >>
-
-This method is called once each time C<import> is called. It is passed a
-reference to the global options hash. (That is, the optional leading hashref
-in the C<use> statement, where the C<into> and C<installer> options can be
-provided.)
-
-You may use this method to munge the global options, or validate them,
-throwing an exception or printing a warning.
-
-The default implementation does nothing interesting.
-
-=item C<< _exporter_validate_unimport_opts($globals) >>
-
-Like C<_exporter_validate_opts>, but called for C<unimport>.
-
-=item C<< _exporter_merge_opts($tag_opts, $globals, @exports) >>
-
-Called to merge options which have been provided for a tag into the
-options provided for the exports that the tag expanded to.
-
-=item C<< _exporter_expand_tag($name, $args, $globals) >>
-
-This method is called to expand an import tag (e.g. C<< ":constants" >>).
-It is passed the tag name (minus the leading ":"), an optional hashref
-of options (like C<< { -prefix => "foo_" } >>), and the global options
-hashref.
-
-It is expected to return a list of ($name, $args) arrayref pairs. These
-names can be sub names to export, or further tag names (which must have
-their ":"). If returning tag names, be careful to avoid creating a tag
-expansion loop!
-
-The default implementation uses C<< %EXPORT_TAGS >> to expand tags, and
-provides fallbacks for the C<< :default >> and C<< :all >> tags.
-
-=item C<< _exporter_expand_regexp($regexp, $args, $globals) >>
-
-Like C<_exporter_expand_regexp>, but given a regexp-like string instead
-of a tag name.
+=item *
-The default implementation greps through C<< @EXPORT_OK >> for imports,
-and the list of already-imported functions for exports.
+L<Exporter::Tiny::Manual::QuickStart>
-=item C<< _exporter_expand_sub($name, $args, $globals) >>
+=item *
-This method is called to translate a sub name to a hash of name => coderef
-pairs for exporting to the caller. In general, this would just be a hash with
-one key and one value, but, for example, L<Type::Library> overrides this
-method so that C<< "+Foo" >> gets expanded to:
-
- (
- Foo => sub { $type },
- is_Foo => sub { $type->check(@_) },
- to_Foo => sub { $type->assert_coerce(@_) },
- assert_Foo => sub { $type->assert_return(@_) },
- )
-
-The default implementation checks that the name is allowed to be exported
-(using the C<_exporter_permitted_regexp> method), gets the coderef using
-the generator if there is one (or by calling C<< can >> on your exporter
-otherwise) and calls C<_exporter_fail> if it's unable to generate or
-retrieve a coderef.
-
-=item C<< _exporter_permitted_regexp($globals) >>
-
-This method is called to retrieve a regexp for validating the names of
-exportable subs. If a sub doesn't match the regexp, then the default
-implementation of C<_exporter_expand_sub> will refuse to export it. (Of
-course, you may override the default C<_exporter_expand_sub>.)
-
-The default implementation of this method assembles the regexp from
-C<< @EXPORT >> and C<< @EXPORT_OK >>.
-
-=item C<< _exporter_fail($name, $args, $globals) >>
-
-Called by C<_exporter_expand_sub> if it can't find a coderef to export.
-
-The default implementation just throws an exception. But you could emit
-a warning instead, or just ignore the failed export.
-
-If you don't throw an exception then you should be aware that this
-method is called in list context, and any list it returns will be treated
-as an C<_exporter_expand_sub>-style hash of names and coderefs for
-export.
-
-=item C<< _exporter_install_sub($name, $args, $globals, $coderef) >>
-
-This method actually installs the exported sub into its new destination.
-Its return value is ignored.
-
-The default implementation handles sub renaming (i.e. the C<< -as >>,
-C<< -prefix >> and C<< -suffix >> functions. This method does a lot of
-stuff; if you need to override it, it's probably a good idea to just
-pre-process the arguments and then call the super method rather than
-trying to handle all of it yourself.
-
-=item C<< _exporter_uninstall_sub($name, $args, $globals) >>
-
-The opposite of C<_exporter_install_sub>.
+L<Exporter::Tiny::Manual::Exporting>
=back
-=head1 DIAGNOSTICS
+If you are trying to B<use> a module that inherits from Exporter::Tiny,
+then look at:
=over
-=item B<< Overwriting existing sub '%s::%s' with sub '%s' exported by %s >>
-
-A warning issued if Exporter::Tiny is asked to export a symbol which
-will result in an existing sub being overwritten. This warning can be
-suppressed using either of the following:
+=item *
- use MyUtils { replace => 1 }, "frobnicate";
- use MyUtils "frobnicate" => { -replace => 1 };
-
-Or can be upgraded to a fatal error:
-
- use MyUtils { replace => "die" }, "frobnicate";
- use MyUtils "frobnicate" => { -replace => "die" };
-
-=item B<< Refusing to overwrite existing sub '%s::%s' with sub '%s' exported by %s >>
-
-The fatal version of the above warning.
-
-=item B<< Could not find sub '%s' exported by %s >>
-
-You requested to import a sub which the package does not provide.
-
-=item B<< Cannot provide an -as option for tags >>
-
-Because a tag may provide more than one function, it does not make sense
-to request a single name for it. Instead use C<< -prefix >> or C<< -suffix >>.
-
-=item B<< Passing options to unimport '%s' makes no sense >>
-
-When you import a sub, it occasionally makes sense to pass some options
-for it. However, when unimporting, options do nothing, so this warning
-is issued.
+L<Exporter::Tiny::Manual::Importing>
=back
-=head1 HISTORY
-
-L<Type::Library> had a bunch of custom exporting code which poked coderefs
-into its caller's stash. It needed this to be something more powerful than
-most exporters so that it could switch between exporting Moose, Mouse and
-Moo-compatible objects on request. L<Sub::Exporter> would have been capable,
-but had too many dependencies for the Type::Tiny project.
-
-Meanwhile L<Type::Utils>, L<Types::TypeTiny> and L<Test::TypeTiny> each
-used the venerable L<Exporter.pm|Exporter>. However, this meant they were
-unable to use the features like L<Sub::Exporter>-style function renaming
-which I'd built into Type::Library:
-
- ## import "Str" but rename it to "String".
- use Types::Standard "Str" => { -as => "String" };
-
-And so I decided to factor out code that could be shared by all Type-Tiny's
-exporters into a single place: Exporter::TypeTiny.
-
-As of version 0.026, Exporter::TypeTiny was also made available as
-L<Exporter::Tiny>, distributed independently on CPAN. CHOCOLATEBOY had
-convinced me that it was mature enough to live a life of its own.
-
-As of version 0.030, Type-Tiny depends on Exporter::Tiny and
-Exporter::TypeTiny is being phased out.
-
-=head1 OBLIGATORY EXPORTER COMPARISON
-
-Exporting is unlikely to be your application's performance bottleneck, but
-nonetheless here are some comparisons.
-
-B<< Comparative sizes according to L<Devel::SizeMe>: >>
-
- Exporter 217.1Kb
- Sub::Exporter::Progressive 263.2Kb
- Exporter::Tiny 267.7Kb
- Exporter + Exporter::Heavy 281.5Kb
- Exporter::Renaming 406.2Kb
- Sub::Exporter 701.0Kb
-
-B<< Performance exporting a single sub: >>
-
- Rate SubExp ExpTiny SubExpProg ExpPM
-SubExp 2489/s -- -56% -85% -88%
-ExpTiny 5635/s 126% -- -67% -72%
-SubExpProg 16905/s 579% 200% -- -16%
-ExpPM 20097/s 707% 257% 19% --
-
-(Exporter::Renaming globally changes the behaviour of Exporter.pm, so could
-not be included in the same benchmarks.)
-
-B<< (Non-Core) Dependencies: >>
-
- Exporter -1
- Exporter::Renaming 0
- Exporter::Tiny 0
- Sub::Exporter::Progressive 0
- Sub::Exporter 3
-
-B<< Features: >>
-
- ExpPM ExpTiny SubExp SubExpProg
- Can export code symbols............. Yes Yes Yes Yes
- Can export non-code symbols......... Yes
- Groups/tags......................... Yes Yes Yes Yes
- Export by regexp.................... Yes Yes
- Bang prefix......................... Yes Yes
- Allows renaming of subs............. Yes Yes Maybe
- Install code into scalar refs....... Yes Yes Maybe
- Can be passed an "into" parameter... Yes Yes Maybe
- Can be passed an "installer" sub.... Yes Yes Maybe
- Config avoids package variables..... Yes
- Supports generators................. Yes Yes
- Sane API for generators............. Yes Yes
- Unimport............................ Yes
-
-(Certain Sub::Exporter::Progressive features are only available if
-Sub::Exporter is installed.)
-
=head1 BUGS
Please report any bugs to
@@ -810,9 +429,9 @@ on L<irc.perl.org|http://www.irc.perl.org/channels.html>.
=head1 SEE ALSO
-L<Exporter::Shiny>,
-L<Sub::Exporter>,
-L<Exporter>.
+Simplified interface to this module: L<Exporter::Shiny>.
+
+Other interesting exporters: L<Sub::Exporter>, L<Exporter>.
=head1 AUTHOR
@@ -820,7 +439,7 @@ Toby Inkster E<lt>tobyink at cpan.orgE<gt>.
=head1 COPYRIGHT AND LICENCE
-This software is copyright (c) 2013-2014 by Toby Inkster.
+This software is copyright (c) 2013-2014, 2017 by Toby Inkster.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
diff --git a/lib/Exporter/Tiny/Manual/Etc.pod b/lib/Exporter/Tiny/Manual/Etc.pod
new file mode 100644
index 0000000..ddded35
--- /dev/null
+++ b/lib/Exporter/Tiny/Manual/Etc.pod
@@ -0,0 +1,134 @@
+=pod
+
+=encoding utf-8
+
+=for stopwords frobnicate greps regexps
+
+=head1 NAME
+
+Exporter::Tiny::Manual::Etc - odds and ends
+
+=head1 DESCRIPTION
+
+=head2 Utility Functions
+
+Exporter::Tiny is itself an exporter!
+
+These functions are really for internal use, but can be exported if you
+need them:
+
+=over
+
+=item C<< mkopt(\@array) >>
+
+Similar to C<mkopt> from L<Data::OptList>. It doesn't support all the
+fancy options that Data::OptList does (C<moniker>, C<require_unique>,
+C<must_be> and C<name_test>) but runs about 50% faster.
+
+=item C<< mkopt_hash(\@array) >>
+
+Similar to C<mkopt_hash> from L<Data::OptList>. See also C<mkopt>.
+
+=back
+
+=head2 History
+
+L<Type::Library> had a bunch of custom exporting code which poked coderefs
+into its caller's stash. It needed this to be something more powerful than
+most exporters so that it could switch between exporting Moose, Mouse and
+Moo-compatible objects on request. L<Sub::Exporter> would have been capable,
+but had too many dependencies for the Type::Tiny project.
+
+Meanwhile L<Type::Utils>, L<Types::TypeTiny> and L<Test::TypeTiny> each
+used the venerable L<Exporter.pm|Exporter>. However, this meant they were
+unable to use the features like L<Sub::Exporter>-style function renaming
+which I'd built into Type::Library:
+
+ ## import "Str" but rename it to "String".
+ use Types::Standard "Str" => { -as => "String" };
+
+And so I decided to factor out code that could be shared by all Type-Tiny's
+exporters into a single place: Exporter::TypeTiny.
+
+As of version 0.026, Exporter::TypeTiny was also made available as
+L<Exporter::Tiny>, distributed independently on CPAN. CHOCOLATEBOY had
+convinced me that it was mature enough to live a life of its own.
+
+As of version 0.030, Type-Tiny depends on Exporter::Tiny and
+Exporter::TypeTiny is being phased out.
+
+=head2 Obligatory Exporter Comparison
+
+Exporting is unlikely to be your application's performance bottleneck, but
+nonetheless here are some comparisons.
+
+B<< Comparative sizes according to L<Devel::SizeMe>: >>
+
+ Exporter 217.1Kb
+ Sub::Exporter::Progressive 263.2Kb
+ Exporter::Tiny 267.7Kb
+ Exporter + Exporter::Heavy 281.5Kb
+ Exporter::Renaming 406.2Kb
+ Sub::Exporter 701.0Kb
+
+B<< Performance exporting a single sub: >>
+
+ Rate SubExp ExpTiny SubExpProg ExpPM
+SubExp 2489/s -- -56% -85% -88%
+ExpTiny 5635/s 126% -- -67% -72%
+SubExpProg 16905/s 579% 200% -- -16%
+ExpPM 20097/s 707% 257% 19% --
+
+(Exporter::Renaming globally changes the behaviour of Exporter.pm, so could
+not be included in the same benchmarks.)
+
+B<< (Non-Core) Dependencies: >>
+
+ Exporter -1
+ Exporter::Renaming 0
+ Exporter::Tiny 0
+ Sub::Exporter::Progressive 0
+ Sub::Exporter 3
+
+B<< Features: >>
+
+ ExpPM ExpTiny SubExp SubExpProg
+ Can export code symbols............. Yes Yes Yes Yes
+ Can export non-code symbols......... Yes
+ Groups/tags......................... Yes Yes Yes Yes
+ Export by regexp.................... Yes Yes
+ Bang prefix......................... Yes Yes
+ Allows renaming of subs............. Yes Yes Maybe
+ Install code into scalar refs....... Yes Yes Maybe
+ Can be passed an "into" parameter... Yes Yes Maybe
+ Can be passed an "installer" sub.... Yes Yes Maybe
+ Config avoids package variables..... Yes
+ Supports generators................. Yes Yes
+ Sane API for generators............. Yes Yes
+ Unimport............................ Yes
+
+(Certain Sub::Exporter::Progressive features are only available if
+Sub::Exporter is installed.)
+
+=head1 SEE ALSO
+
+L<Exporter::Shiny>,
+L<Exporter::Tiny>.
+
+=head1 AUTHOR
+
+Toby Inkster E<lt>tobyink at cpan.orgE<gt>.
+
+=head1 COPYRIGHT AND LICENCE
+
+This software is copyright (c) 2013-2014, 2017 by Toby Inkster.
+
+This is free software; you can redistribute it and/or modify it under
+the same terms as the Perl 5 programming language system itself.
+
+=head1 DISCLAIMER OF WARRANTIES
+
+THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
+MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+
diff --git a/lib/Exporter/Tiny/Manual/Exporting.pod b/lib/Exporter/Tiny/Manual/Exporting.pod
new file mode 100644
index 0000000..099cc0c
--- /dev/null
+++ b/lib/Exporter/Tiny/Manual/Exporting.pod
@@ -0,0 +1,256 @@
+=pod
+
+=encoding utf-8
+
+=for stopwords frobnicate greps regexps
+
+=head1 NAME
+
+Exporter::Tiny::Manual::Exporting - creating an exporter using Exporter::Tiny
+
+=head1 SYNOPSIS
+
+B<< Read L<Exporter::Tiny::Manual::QuickStart> first! >>
+
+=head1 DESCRIPTION
+
+Simple configuration works the same as L<Exporter>; inherit from
+L<Exporter::Tiny>, and use the C<< @EXPORT >>, C<< @EXPORT_OK >>,
+and C<< %EXPORT_TAGS >> package variables to list subs to export.
+
+Unlike Exporter, Exporter::Tiny performs most of its internal duties
+(including resolution of tag names to sub names, resolution of sub
+names to coderefs, and installation of coderefs into the target
+package) as B<method calls>, which means that your module (which is a
+subclass of Exporter::Tiny) can override them to provide interesting
+behaviour.
+
+=head2 Advanced Tag Stuff
+
+You can define tags using other tags:
+
+ use Exporter::Shiny qw(
+ black white red green blue cyan magenta yellow
+ );
+
+ our %EXPORT_TAGS = (
+ rgb => [qw( red green blue )],
+ cym => [qw( cyan magenta yellow )],
+ cymk => [qw( black :cym )],
+ monochrome => [qw( black white )],
+ all => [qw( :rgb :cymk :monochrome )],
+ );
+
+B<< CAVEAT: >> If you create a cycle in the tags, this could put
+Exporter::Tiny into an infinite loop expanding the tags. Don't do that.
+
+=head2 More on Generators
+
+Exporter::Tiny has always allowed exported subs to be generated (like
+L<Sub::Exporter>), but until version 0.025 did not have an especially nice
+API for it.
+
+Now, it's easy. If you want to generate a sub C<foo> to export, list it in
+C<< @EXPORT >> or C<< @EXPORT_OK >> as usual, and then simply give your
+exporter module a class method called C<< _generate_foo >>.
+
+ push @EXPORT_OK, 'foo';
+
+ sub _generate_foo {
+ my $class = shift;
+ my ($name, $args, $globals) = @_;
+
+ return sub {
+ ...;
+ }
+ }
+
+We showed how to do that in L<Exporter::Tiny::Manual::QuickStart>, but
+one thing we didn't show was that C<< $globals >> gets passed in there.
+This is the global options hash, as described in
+L<Exporter::Tiny::Manual::Importing>. It can often be useful. In
+particular it will tell you what package the generated sub is destined
+to be installed into.
+
+You can also generate tags:
+
+ my %constants;
+ BEGIN {
+ %constants = (FOO => 1, BAR => 2);
+ }
+ use constant \%constants;
+
+ $EXPORT_TAGS{constants} = sub {
+ my $class = shift;
+ my ($name, $args, $globals) = @_;
+
+ return keys(%constants);
+ };
+
+=head2 Hooks
+
+Sometimes as well as exporting stuff, you want to do some setup or
+something.
+
+You can define a couple of class methods in your package, and they'll
+get called at the appropriate time:
+
+ package MyUtils;
+
+ ...;
+
+ sub _exporter_validate_opts {
+ my $class = shift;
+ my ($globals) = @_;
+
+ ...; # do stuff here
+
+ $class->SUPER::_exporter_validate_opts(@_);
+ }
+
+ sub _exporter_validate_unimport_opts {
+ my $class = shift;
+ my ($globals) = @_;
+
+ ...; # do stuff here
+
+ $class->SUPER::_exporter_validate_unimport_opts(@_);
+ }
+
+The C<< $globals >> variable is that famous global options hash. In
+particular, C<< $globals->{into} >> is useful because it tells you what
+package has imported you.
+
+As you might have guessed, these methods were originally intended to
+validate the global options hash, but can be used to perform any
+general duties before the real exporting work is done.
+
+=head2 Overriding Internals
+
+An important difference between L<Exporter> and Exporter::Tiny is that
+the latter calls all its internal functions as I<< class methods >>. This
+means that your subclass can I<< override them >> to alter their behaviour.
+
+The following methods are available to be overridden. Despite being named
+with a leading underscore, they are considered public methods. (The underscore
+is there to avoid accidentally colliding with any of your own function names.)
+
+=over
+
+=item C<< _exporter_validate_opts($globals) >>
+
+Documented above.
+
+=item C<< _exporter_validate_unimport_opts($globals) >>
+
+Documented above.
+
+=item C<< _exporter_merge_opts($tag_opts, $globals, @exports) >>
+
+Called to merge options which have been provided for a tag into the
+options provided for the exports that the tag expanded to.
+
+=item C<< _exporter_expand_tag($name, $args, $globals) >>
+
+This method is called to expand an import tag (e.g. C<< ":constants" >>).
+It is passed the tag name (minus the leading ":"), an optional hashref
+of options (like C<< { -prefix => "foo_" } >>), and the global options
+hashref.
+
+It is expected to return a list of ($name, $args) arrayref pairs. These
+names can be sub names to export, or further tag names (which must have
+their ":"). If returning tag names, be careful to avoid creating a tag
+expansion loop!
+
+The default implementation uses C<< %EXPORT_TAGS >> to expand tags, and
+provides fallbacks for the C<< :default >> and C<< :all >> tags.
+
+=item C<< _exporter_expand_regexp($regexp, $args, $globals) >>
+
+Like C<_exporter_expand_regexp>, but given a regexp-like string instead
+of a tag name.
+
+The default implementation greps through C<< @EXPORT_OK >> for imports,
+and the list of already-imported functions for exports.
+
+=item C<< _exporter_expand_sub($name, $args, $globals) >>
+
+This method is called to translate a sub name to a hash of name => coderef
+pairs for exporting to the caller. In general, this would just be a hash with
+one key and one value, but, for example, L<Type::Library> overrides this
+method so that C<< "+Foo" >> gets expanded to:
+
+ (
+ Foo => sub { $type },
+ is_Foo => sub { $type->check(@_) },
+ to_Foo => sub { $type->assert_coerce(@_) },
+ assert_Foo => sub { $type->assert_return(@_) },
+ )
+
+The default implementation checks that the name is allowed to be exported
+(using the C<_exporter_permitted_regexp> method), gets the coderef using
+the generator if there is one (or by calling C<< can >> on your exporter
+otherwise) and calls C<_exporter_fail> if it's unable to generate or
+retrieve a coderef.
+
+=item C<< _exporter_permitted_regexp($globals) >>
+
+This method is called to retrieve a regexp for validating the names of
+exportable subs. If a sub doesn't match the regexp, then the default
+implementation of C<_exporter_expand_sub> will refuse to export it. (Of
+course, you may override the default C<_exporter_expand_sub>.)
+
+The default implementation of this method assembles the regexp from
+C<< @EXPORT >> and C<< @EXPORT_OK >>.
+
+=item C<< _exporter_fail($name, $args, $globals) >>
+
+Called by C<_exporter_expand_sub> if it can't find a coderef to export.
+
+The default implementation just throws an exception. But you could emit
+a warning instead, or just ignore the failed export.
+
+If you don't throw an exception then you should be aware that this
+method is called in list context, and any list it returns will be treated
+as an C<_exporter_expand_sub>-style hash of names and coderefs for
+export.
+
+=item C<< _exporter_install_sub($name, $args, $globals, $coderef) >>
+
+This method actually installs the exported sub into its new destination.
+Its return value is ignored.
+
+The default implementation handles sub renaming (i.e. the C<< -as >>,
+C<< -prefix >> and C<< -suffix >> functions. This method does a lot of
+stuff; if you need to override it, it's probably a good idea to just
+pre-process the arguments and then call the super method rather than
+trying to handle all of it yourself.
+
+=item C<< _exporter_uninstall_sub($name, $args, $globals) >>
+
+The opposite of C<_exporter_install_sub>.
+
+=back
+
+=head1 SEE ALSO
+
+L<Exporter::Shiny>,
+L<Exporter::Tiny>.
+
+=head1 AUTHOR
+
+Toby Inkster E<lt>tobyink at cpan.orgE<gt>.
+
+=head1 COPYRIGHT AND LICENCE
+
+This software is copyright (c) 2013-2014, 2017 by Toby Inkster.
+
+This is free software; you can redistribute it and/or modify it under
+the same terms as the Perl 5 programming language system itself.
+
+=head1 DISCLAIMER OF WARRANTIES
+
+THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
+MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+
diff --git a/lib/Exporter/Tiny/Manual/Importing.pod b/lib/Exporter/Tiny/Manual/Importing.pod
new file mode 100644
index 0000000..ffbdc73
--- /dev/null
+++ b/lib/Exporter/Tiny/Manual/Importing.pod
@@ -0,0 +1,253 @@
+=pod
+
+=encoding utf-8
+
+=for stopwords frobnicate greps regexps
+
+=head1 NAME
+
+Exporter::Tiny::Manual::Importing - importing from Exporter::Tiny-based modules
+
+=head1 DESCRIPTION
+
+For the purposes of this discussion we'll assume we have a module called
+C<< MyUtils >> which exports functions called C<frobnicate>, C<red>,
+C<blue>, and C<green>. It has a tag set up called C<:colours> which
+corresponds to C<red>, C<blue>, and C<green>.
+
+Many of these tricks may seem familiar from L<Sub::Exporter>. That is
+intentional. Exporter::Tiny doesn't attempt to provide every feature of
+Sub::Exporter, but where it does it usually uses a fairly similar API.
+
+=head2 Basic importing
+
+It's easy to import a single function from a module:
+
+ use MyUtils "frobnicate";
+
+Or a list of functions:
+
+ use MyUtils "red", "green";
+
+Perl's C<< qw() >> shorthand for a list of words is pretty useful:
+
+ use MyUtils qw( red green );
+
+If the module defines tags, you can import them like this:
+
+ use MyUtils qw( :colours );
+
+Or with a hyphen instead of a colon:
+
+ use MyUtils qw( -colours );
+
+Hyphens are good because Perl will autoquote a bareword that follows
+them:
+
+ use MyUtils -colours;
+
+And it's possible to mix function names and tags in the same list:
+
+ use MyUtils qw( frobnicate :colours );
+
+=head2 Renaming imported functions
+
+It's possible to rename a function you're importing:
+
+ use MyUtils "frobnicate" => { -as => "frob" };
+
+Or you can apply a prefix and/or suffix. The following imports the
+function and calls it C<my_frobinate_thing>.
+
+ use MyUtils "frobnicate" => { -prefix => "my_", -suffix => "_thing" };
+
+You can apply a prefix/suffix to B<all> functions you import by
+placing the hashref B<first> in the import list. (This first hashref
+is referred to as the global options hash, and can do some special
+things.)
+
+ use MyUtils { prefix => "my_" }, "frobnicate";
+
+Did you notice that we used C<< -prefix >> and C<< -suffix >> in the
+normal options hash, but C<< prefix >> and C<< suffix >> (no hyphen)
+in the global options hash? That's a common pattern with this module.
+
+You can import the same function multiple times with different names:
+
+ use MyUtils
+ "frobnicate" => { -as => "frob" },
+ "frobnicate" => { -as => "frbnct" };
+
+Tags can take the C<< -prefix >> and C<< -suffix >> options too. The
+following imports C<colour_red>, C<colour_green>, and C<colour_blue>:
+
+ use MyUtils -colours => { -prefix => "colour_" };
+
+You can also set C<< -as >> to be a coderef to generate a function
+name. This imports functions called C<RED>, C<GREEN>, and C<BLUE>:
+
+ use MyUtils -colours => { -as => sub { uc($_[0]) } };
+
+Note that it doesn't make sense to use C<< -as >> with a tag unless
+you're doing this coderef thing. Coderef C<< as >> also works in the
+global options hash.
+
+=head2 DO NOT WANT!
+
+Sometimes you want to supply a list of functions you B<< don't >> want
+to import. To do that, prefix the function with a bang. This imports
+everything except "frobnicate":
+
+ use MyUtils qw( -all !frobnicate );
+
+You can add the bang prefix to tags too. This will import everything
+except the colours.
+
+ use MyUtils qw( -all !:colours );
+
+Negated imports always "win", so the following will not import
+"frobnicate", no matter how many times you repeat it...
+
+ use MyUtils qw( !frobnicate frobnicate frobnicate frobnicate );
+
+=head2 Importing by regexp
+
+Here's how you could import all functions beginning with an "f":
+
+ use MyUtils qw( /^F/i );
+
+Or import everything except functions beginning with a "z":
+
+ use MyUtils qw( -all !/^Z/i );
+
+Note that regexps are always supplied as I<strings> starting with
+C<< "/" >>, and not as quoted regexp references (C<< qr/.../ >>).
+
+=head2 Import functions into another package
+
+Occasionally you need to import functions not into your own package,
+but into a different package. You can do that like this:
+
+ use MyUtils { into => "OtherPkg" }, "frobnicate";
+
+ OtherPkg::frobincate(...);
+
+However, L<Import::Into> will probably provide you with a better
+approach which doesn't just work with Exporter::Tiny, but B<all>
+exporters.
+
+=head2 Lexical subs
+
+Often you want to make use of an exported function, but don't want
+it to "pollute" your namespace.
+
+There is this L<Sub::Exporter::Lexical> thing that was designed as a
+plugin for L<Sub::Exporter>, but Exporter::Tiny's API is close enough
+that it will work. Do you remember that global options hash? Just
+use that to tell Exporter::Tiny to use an alternative sub installer.
+
+ {
+ use Sub::Exporter::Lexical lexical_installer => { -as => "lex" };
+ use MyUtils { installer => lex }, "frobnicate";
+
+ frobnicate(...); # ok
+ }
+
+ frobnicate(...); # not ok
+
+Another way to do lexical functions is to import a function into a
+scalar variable:
+
+ my $func;
+ use MyUtils "frobnicate" => { -as => \$func };
+
+ $func->(...);
+
+You can even provide a hashref to put all imported functions into as
+part of that global options hash I mentioned earlier.
+
+ my %funcs;
+ use MyUtils { into => \%funcs }, "frobnicate";
+
+ $funcs{frobnicate}->(...);
+
+=head2 Unimporting
+
+You can unimport the functions that MyUtils added to your namespace:
+
+ no MyUtils;
+
+Or just specific ones:
+
+ no MyUtils qw(frobnicate);
+
+If you renamed a function when you imported it, you should unimport by
+the new name:
+
+ use MyUtils frobnicate => { -as => "frob" };
+ ...;
+ no MyUtils "frob";
+
+Unimporting using tags and regexps should mostly do what you want.
+
+=head1 DIAGNOSTICS
+
+=over
+
+=item B<< Overwriting existing sub '%s::%s' with sub '%s' exported by %s >>
+
+A warning issued if Exporter::Tiny is asked to export a symbol which
+will result in an existing sub being overwritten. This warning can be
+suppressed using either of the following:
+
+ use MyUtils { replace => 1 }, "frobnicate";
+ use MyUtils "frobnicate" => { -replace => 1 };
+
+Or can be upgraded to a fatal error:
+
+ use MyUtils { replace => "die" }, "frobnicate";
+ use MyUtils "frobnicate" => { -replace => "die" };
+
+=item B<< Refusing to overwrite existing sub '%s::%s' with sub '%s' exported by %s >>
+
+The fatal version of the above warning.
+
+=item B<< Could not find sub '%s' exported by %s >>
+
+You requested to import a sub which the package does not provide.
+
+=item B<< Cannot provide an -as option for tags >>
+
+Because a tag may provide more than one function, it does not make sense
+to request a single name for it. Instead use C<< -prefix >> or C<< -suffix >>.
+
+=item B<< Passing options to unimport '%s' makes no sense >>
+
+When you import a sub, it occasionally makes sense to pass some options
+for it. However, when unimporting, options do nothing, so this warning
+is issued.
+
+=back
+
+=head1 SEE ALSO
+
+L<Exporter::Shiny>,
+L<Exporter::Tiny>.
+
+=head1 AUTHOR
+
+Toby Inkster E<lt>tobyink at cpan.orgE<gt>.
+
+=head1 COPYRIGHT AND LICENCE
+
+This software is copyright (c) 2013-2014, 2017 by Toby Inkster.
+
+This is free software; you can redistribute it and/or modify it under
+the same terms as the Perl 5 programming language system itself.
+
+=head1 DISCLAIMER OF WARRANTIES
+
+THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
+MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+
diff --git a/lib/Exporter/Tiny/Manual/QuickStart.pod b/lib/Exporter/Tiny/Manual/QuickStart.pod
new file mode 100644
index 0000000..5ab5404
--- /dev/null
+++ b/lib/Exporter/Tiny/Manual/QuickStart.pod
@@ -0,0 +1,195 @@
+=pod
+
+=encoding utf-8
+
+=for stopwords frobnicate greps regexps
+
+=head1 NAME
+
+Exporter::Tiny::Manual::QuickStart - the quickest way to get up and running with Exporter::Tiny
+
+=head1 SYNOPSIS
+
+ package MyUtils;
+
+ use Exporter::Shiny qw( frobnicate );
+
+ sub frobnicate {
+ ...; # your code here
+ }
+
+ 1;
+
+Now people can use your module like this:
+
+ use MyUtils "frobnicate";
+
+ frobnicate(42);
+
+Or like this:
+
+ use MyUtils "frobnicate" => { -as => "frob" };
+
+ frob(42);
+
+=head1 DESCRIPTION
+
+See the synopsis. Yes, it's that simple.
+
+=head2 Next steps
+
+=head3 Default exports
+
+Note that the module in the synopsis doesn't export anything by default.
+If people load C<MyUtils> like this:
+
+ use MyUtils;
+
+Then they haven't imported any functions. You can specify a default set
+of functions to be exported like this:
+
+ package MyUtils;
+
+ use Exporter::Shiny qw( frobnicate );
+
+ our @EXPORT = qw( frobnicate );
+
+ sub frobnicate { ... }
+
+ 1;
+
+Or, if you want to be a superstar rock god:
+
+ package MyUtils;
+
+ use Exporter::Shiny our @EXPORT = qw( frobnicate );
+
+ sub frobnicate { ... }
+
+ 1;
+
+=head3 Tags
+
+You can provide tags for people to use:
+
+ package MyUtils;
+
+ use Exporter::Shiny qw( frobnicate red green blue );
+
+ our %EXPORT_TAGS = (
+ utils => [qw/ frobnicate /],
+ colours => [qw/ red green blue /],
+ );
+
+ sub frobnicate { ... }
+ sub red { ... }
+ sub green { ... }
+ sub blue { ... }
+
+ 1;
+
+And people can now import your functions like this:
+
+ use MyUtils ":colours";
+
+Or this:
+
+ use MyUtils "-colours";
+
+Or take advantage of the fact that Perl magically quotes barewords
+preceded by a hyphen:
+
+ use MyUtils -colours;
+
+Two tags are automatically defined for you: C<< -default >> (which is
+just the same as C<< @EXPORT >>) and C<< -all >> (which is the union of
+C<< @EXPORT >> and C<< @EXPORT_OK >>). If you don't like them, then you
+can override them:
+
+ our %EXPORT_TAGS = (
+ default => \@some_other_stuff,
+ all => \@more_stuff,
+ );
+
+=head3 Generators
+
+Exporting normally just works by copying a sub from your package into
+your caller's package. But sometimes it's useful instead to generate
+a I<custom> sub to insert into your caller's package. This is pretty
+easy to do.
+
+ package MyUtils;
+
+ use Exporter::Shiny qw( frobnicate );
+
+ sub _generate_frobnicate {
+ my $me = shift;
+ my $caller = caller;
+ my ($name, $args) = @_;
+
+ return sub {
+ ...; # your code here
+ };
+ }
+
+ 1;
+
+The parameter C<< $me >> here is a string containing the package name
+which is being imported from; C<< $caller >> is the destination package;
+C<< $name >> is the name of the sub (in this case "frobnicate"); and
+C<< $args >> is a hashref of custom arguments for this function.
+
+ # The hashref { foo => 42 } is $args above.
+ #
+ use MyUtils "frobnicate" => { foo => 42 };
+
+=head2 Avoiding Exporter::Shiny
+
+Exporter::Shiny is a tiny shim around Exporter::Tiny. It should mostly
+do what you want, but you may sometimes prefer to use Exporter::Tiny
+directly.
+
+The example in the synopsis could have been written as:
+
+ package MyUtils;
+
+ use parent "Exporter::Tiny";
+ our @EXPORT_OK = qw( frobnicate );
+
+ sub frobnicate {
+ ...; # your code here
+ }
+
+ 1;
+
+What Exporter::Shiny does is mostly just to set C<< @EXPORT_OK >> for
+you and set up inheritance from the base class (Exporter::Tiny).
+
+Exporter::Shiny also sets C<< $INC{'MyUtils.pm} >> for you, which in
+usually makes little difference, but is useful in some edge cases.
+
+=head1 SEE ALSO
+
+L<Exporter::Shiny>,
+L<Exporter::Tiny>.
+
+For more advanced information, see
+L<Exporter::Tiny::Manual::Exporting>.
+
+=head1 AUTHOR
+
+Toby Inkster E<lt>tobyink at cpan.orgE<gt>.
+
+=head1 COPYRIGHT AND LICENCE
+
+This software is copyright (c) 2013-2014, 2017 by Toby Inkster.
+
+This is free software; you can redistribute it and/or modify it under
+the same terms as the Perl 5 programming language system itself.
+
+=head1 DISCLAIMER OF WARRANTIES
+
+THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
+MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+
diff --git a/t/01basic.t b/t/01basic.t
index 72dd3d7..efe66e8 100644
--- a/t/01basic.t
+++ b/t/01basic.t
@@ -14,7 +14,7 @@ Toby Inkster E<lt>tobyink at cpan.orgE<gt>.
=head1 COPYRIGHT AND LICENCE
-This software is copyright (c) 2013 by Toby Inkster.
+This software is copyright (c) 2013-2014, 2017 by Toby Inkster.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
diff --git a/t/02renaming.t b/t/02renaming.t
index 857b81c..e525069 100644
--- a/t/02renaming.t
+++ b/t/02renaming.t
@@ -12,7 +12,7 @@ Toby Inkster E<lt>tobyink at cpan.orgE<gt>.
=head1 COPYRIGHT AND LICENCE
-This software is copyright (c) 2013 by Toby Inkster.
+This software is copyright (c) 2013-2014, 2017 by Toby Inkster.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
diff --git a/t/03generators.t b/t/03generators.t
index 1f69d10..2ab3f40 100644
--- a/t/03generators.t
+++ b/t/03generators.t
@@ -12,7 +12,7 @@ Toby Inkster E<lt>tobyink at cpan.orgE<gt>.
=head1 COPYRIGHT AND LICENCE
-This software is copyright (c) 2013 by Toby Inkster.
+This software is copyright (c) 2013-2014, 2017 by Toby Inkster.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
diff --git a/t/04into.t b/t/04into.t
index d621fef..c684c78 100644
--- a/t/04into.t
+++ b/t/04into.t
@@ -12,7 +12,7 @@ Toby Inkster E<lt>tobyink at cpan.orgE<gt>.
=head1 COPYRIGHT AND LICENCE
-This software is copyright (c) 2013 by Toby Inkster.
+This software is copyright (c) 2013-2014, 2017 by Toby Inkster.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
diff --git a/t/05shiny.t b/t/05shiny.t
index 9b5875d..1ce32a7 100644
--- a/t/05shiny.t
+++ b/t/05shiny.t
@@ -12,7 +12,7 @@ Toby Inkster E<lt>tobyink at cpan.orgE<gt>.
=head1 COPYRIGHT AND LICENCE
-This software is copyright (c) 2014 by Toby Inkster.
+This software is copyright (c) 2014, 2017 by Toby Inkster.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
diff --git a/t/06notwant.t b/t/06notwant.t
index 992bbd7..69ca360 100644
--- a/t/06notwant.t
+++ b/t/06notwant.t
@@ -12,7 +12,7 @@ Toby Inkster E<lt>tobyink at cpan.orgE<gt>.
=head1 COPYRIGHT AND LICENCE
-This software is copyright (c) 2014 by Toby Inkster.
+This software is copyright (c) 2014, 2017 by Toby Inkster.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
diff --git a/t/07regexp.t b/t/07regexp.t
index 998dc4e..28cf5f9 100644
--- a/t/07regexp.t
+++ b/t/07regexp.t
@@ -12,7 +12,7 @@ Toby Inkster E<lt>tobyink at cpan.orgE<gt>.
=head1 COPYRIGHT AND LICENCE
-This software is copyright (c) 2014 by Toby Inkster.
+This software is copyright (c) 2014, 2017 by Toby Inkster.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
diff --git a/t/08tags.t b/t/08tags.t
index 036dc3b..6156084 100644
--- a/t/08tags.t
+++ b/t/08tags.t
@@ -12,7 +12,7 @@ Toby Inkster E<lt>tobyink at cpan.orgE<gt>.
=head1 COPYRIGHT AND LICENCE
-This software is copyright (c) 2014 by Toby Inkster.
+This software is copyright (c) 2014, 2017 by Toby Inkster.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
diff --git a/t/09warnings.t b/t/09warnings.t
index 72d40f3..d3203f8 100644
--- a/t/09warnings.t
+++ b/t/09warnings.t
@@ -12,7 +12,7 @@ Toby Inkster E<lt>tobyink at cpan.orgE<gt>.
=head1 COPYRIGHT AND LICENCE
-This software is copyright (c) 2014 by Toby Inkster.
+This software is copyright (c) 2014, 2017 by Toby Inkster.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
diff --git a/t/10no.t b/t/10no.t
index 66b0f82..cc4da2f 100644
--- a/t/10no.t
+++ b/t/10no.t
@@ -12,7 +12,7 @@ Toby Inkster E<lt>tobyink at cpan.orgE<gt>.
=head1 COPYRIGHT AND LICENCE
-This software is copyright (c) 2014 by Toby Inkster.
+This software is copyright (c) 2014, 2017 by Toby Inkster.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-perl/packages/libexporter-tiny-perl.git
More information about the Pkg-perl-cvs-commits
mailing list