Permalink
Browse files

docs, dist.ini; ready to release?

  • Loading branch information...
1 parent d435b93 commit 3a45853bdf6a5681218b03fb89b1f6b782eaa614 @rjbs committed Jun 30, 2009
Showing with 80 additions and 0 deletions.
  1. +10 −0 dist.ini
  2. +70 −0 lib/Sub/Exporter/ForMethods.pm
View
@@ -0,0 +1,10 @@
+name = Sub-Exporter-ForMethods
+author = Ricardo Signes <rjbs@cpan.org>
+license = Perl_5
+copyright_holder = Ricardo Signes
+
+[@RJBS]
+
+[Prereq]
+Sub::Name = 0
+Sub::Exporter = 0.978 ; installer / generator stuff
@@ -1,13 +1,83 @@
use strict;
use warnings;
package Sub::Exporter::ForMethods;
+# ABSTRACT: helper routines for using Sub::Exporter to build methods
use Sub::Name ();
use Sub::Exporter -setup => {
exports => [ qw(method_installer) ],
};
+=head1 SYNOPSIS
+
+In an exporting library:
+
+ package Method::Builder;
+
+ use Sub::Exporter::ForMethods qw(method_installer);
+
+ use Sub::Exporter -setup => {
+ exports => [ method => \'_method_generator' ],
+ installer => method_installer,
+ };
+
+ sub _method_generator {
+ my ($self, $name, $arg, $col) = @_;
+ return sub { ... };
+ };
+
+In an importing library:
+
+ package Vehicle::Autobot;
+ use Method::Builder method => { -as => 'transform' };
+
+=head1 DESCRIPTION
+
+The synopsis section, above, looks almost indistinguishable from any other
+use of L<Sub::Exporter|Sub::Exporter>, apart from the use of
+C<method_installer>. It is nearly indistinguishable in behavior, too. The
+only change is that subroutines exported from Method::Builder into named slots
+in Vehicle::Autobot will be wrapped in a subroutine called
+C<Vehicle::Autobot::transform>. This will insert a named frame into stack
+traces to aid in debugging.
+
+More importantly (for the author, anyway), they will not be removed by
+L<namespace::autoclean|namespace::autoclean>. This makes the following code
+work:
+
+ package MyLibrary;
+
+ use Math::Trig qw(tan); # uses Exporter.pm
+ use String::Truncate qw(trunc); # uses Sub::Exporter's defaults
+
+ use Sub::Exporter::ForMethods qw(method_installer);
+ use Mixin::Linewise { installer => method_installer }, qw(read_file);
+
+ use namespace::autoclean;
+
+ ...
+
+ 1;
+
+After MyLibrary is compiled, C<namespace::autoclean> will remove C<tan> and
+C<trunc> as foreign contaminants, but will leave C<read_file> in place. It
+will also remove C<method_installer>, an added win.
+
+=head1 EXPORTS
+
+Sub::Exporter::ForMethods offers only one routine for export, and it may also
+be called by its full package name:
+
+=head2 method_installer
+
+This routine returns an installer suitable for use as the C<installer> argument
+to Sub::Exporter. It updates the C<\@to_export> argument to wrap all code that
+will be installed by name in a named subroutine, then passes control to the
+default Sub::Exporter installer.
+
+=cut
+
sub method_installer {
sub {
my ($arg, $to_export) = @_;

0 comments on commit 3a45853

Please sign in to comment.