Toby Inkster avatar Toby Inkster committed cad3ec3

include more pod from Exporter::TypeTiny into Exporter::Tiny

Comments (0)

Files changed (2)

devel.forked/p5-exporter-tiny/lib/Exporter/Tiny.pm

 use warnings; no warnings qw(void once uninitialized numeric redefine);
 
 our $AUTHORITY = 'cpan:TOBYINK';
-our $VERSION   = '0.026';
+our $VERSION   = '0.028';
 our @EXPORT_OK = qw< mkopt mkopt_hash _croak >;
 
 sub _croak ($;@) { require Carp; my $fmt = shift; @_ = sprintf($fmt, @_); goto \&Carp::croak }
 
 =head1 HISTORY
 
-Exporter::Tiny is a fork of L<Exporter::TypeTiny>. CHOCOLATEBOY convinced
-me that the Exporter from Type-Tiny was mature enough to live a life of its
-own.
+B<< Why >> bundle an exporter with Type-Tiny?
 
-The two modules should stay fairly synchronized in terms of features,
-bug fixes and so on.
+Well, it wasn't always that way. L<Type::Library> had a bunch of custom
+exporting code which poked coderefs into its caller's stash. It needed this
+so that it could switch between exporting Moose, Mouse and Moo-compatible
+objects on request.
 
-See L<Exporter::TypeTiny/HISTORY> for further history and rationale.
+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.
+
+As of version 0.026, this module is also available as L<Exporter::Tiny>,
+distributed independently on CPAN. The long-term future of the bundled
+L<Exporter::Tiny> module is uncertain.
 
 =head1 OBLIGATORY EXPORTER COMPARISON
 
-Exporter::Tiny offers almost all Sub::Exporter's features, but runs more
-than twice as fast; uses less than half the memory and has no non-core
-dependencies.
+Exporting is unlikely to be your application's performance bottleneck, but
+nonetheless here are some comparisons.
 
-See L<Exporter::TypeTiny/OBLIGATORY EXPORTER COMPARISON> details.
+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      ExpTT SubExpProg      ExpPM
+SubExp      2489/s         --       -56%       -85%       -88%
+ExpTT       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) Depenendencies: >>
+
+   Exporter                    -1
+   Exporter::Renaming           0
+   Exporter::Tiny           0
+   Sub::Exporter::Progressive   0   
+   Sub::Exporter                3
+
+B<< Features: >>
+
+                                      ExpPM   ExpTT   SubExp  SubExpProg
+ Can export code symbols............. Yes     Yes     Yes     Yes      
+ Can export non-code symbols......... Yes                              
+ Groups/tags......................... Yes     Yes     Yes     Yes      
+ Config avoids package variables.....                 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    
+ Supports generators.................         Yes     Yes              
+ Sane API for generators.............         Yes     Yes              
+
+(Certain Sub::Exporter::Progressive features are only available if
+Sub::Exporter is installed.)
 
 =head1 BUGS
 

devel.forked/update-exporter-tiny.pl

 
 POD
 
-'HISTORY'=><<POD,
-
-Exporter::Tiny is a fork of L<Exporter::TypeTiny>. CHOCOLATEBOY convinced
-me that the Exporter from Type-Tiny was mature enough to live a life of its
-own.
-
-The two modules should stay fairly synchronized in terms of features,
-bug fixes and so on.
-
-See L<Exporter::TypeTiny/HISTORY> for further history and rationale.
-
-POD
-
-'OBLIGATORY EXPORTER COMPARISON'=><<POD,
-
-Exporter::Tiny offers almost all Sub::Exporter's features, but runs more
-than twice as fast; uses less than half the memory and has no non-core
-dependencies.
-
-See L<Exporter::TypeTiny/OBLIGATORY EXPORTER COMPARISON> details.
-
-POD
-
 'SEE ALSO'=><<POD,
 
 L<Exporter::TypeTiny>,
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.