Initial Commit

database/perl/lib/Sub/Exporter/Cookbook.pod

@@ -0,0 +1,308 @@
+
+# ABSTRACT: useful, demonstrative, or stupid Sub::Exporter tricks
+# PODNAME: Sub::Exporter::Cookbook
+
+__END__
+
+=pod
+
+=head1 NAME
+
+Sub::Exporter::Cookbook - useful, demonstrative, or stupid Sub::Exporter tricks
+
+=head1 VERSION
+
+version 0.987
+
+=head1 OVERVIEW
+
+Sub::Exporter is a fairly simple tool, and can be used to achieve some very
+simple goals.  Its basic behaviors and their basic application (that is,
+"traditional" exporting of routines) are described in
+L<Sub::Exporter::Tutorial> and L<Sub::Exporter>.  This document presents
+applications that may not be immediately obvious, or that can demonstrate how
+certain features can be put to use (for good or evil).
+
+=head1 THE RECIPES
+
+=head2 Exporting Methods as Routines
+
+With Exporter.pm, exporting methods is a non-starter.  Sub::Exporter makes it
+simple.  By using the C<curry_method> utility provided in
+L<Sub::Exporter::Util>, a method can be exported with the invocant built in.
+
+  package Object::Strenuous;
+
+  use Sub::Exporter::Util 'curry_method';
+  use Sub::Exporter -setup => {
+    exports => [ objection => curry_method('new') ],
+  };
+
+With this configuration, the importing code may contain:
+
+  my $obj = objection("irrelevant");
+
+...and this will be equivalent to:
+
+  my $obj = Object::Strenuous->new("irrelevant");
+
+The built-in invocant is determined by the invocant for the C<import> method.
+That means that if we were to subclass Object::Strenuous as follows:
+
+  package Object::Strenuous::Repeated;
+  @ISA = 'Object::Strenuous';
+
+...then importing C<objection> from the subclass would build-in that subclass.
+
+Finally, since the invocant can be an object, you can write something like
+this:
+
+  package Cypher;
+  use Sub::Exporter::Util 'curry_method';
+  use Sub::Exporter -setup => {
+    exports => [ encypher => curry_method ],
+  };
+
+with the expectation that C<import> will be called on an instantiated Cypher
+object:
+
+  BEGIN {
+    my $cypher = Cypher->new( ... );
+    $cypher->import('encypher');
+  }
+
+Now there is a globally-available C<encypher> routine which calls the encypher
+method on an otherwise unavailable Cypher object.
+
+=head2 Exporting Methods as Methods
+
+While exporting modules usually export subroutines to be called as subroutines,
+it's easy to use Sub::Exporter to export subroutines meant to be called as
+methods on the importing package or its objects.
+
+Here's a trivial (and naive) example:
+
+  package Mixin::DumpObj;
+
+  use Data::Dumper;
+
+  use Sub::Exporter -setup => {
+    exports => [ qw(dump) ]
+  };
+
+  sub dump {
+    my ($self) = @_;
+    return Dumper($self);
+  }
+
+When writing your own object class, you can then import C<dump> to be used as a
+method, called like so:
+
+  $object->dump;
+
+By assuming that the importing class will provide a certain interface, a
+method-exporting module can be used as a simple plugin:
+
+  package Number::Plugin::Upto;
+  use Sub::Exporter -setup => {
+    into    => 'Number',
+    exports => [ qw(upto) ],
+    groups  => [ default => [ qw(upto) ] ],
+  };
+
+  sub upto {
+    my ($self) = @_;
+    return 1 .. abs($self->as_integer);
+  }
+
+The C<into> line in the configuration says that this plugin will export, by
+default, into the Number package, not into the C<use>-ing package.  It can be
+exported anyway, though, and will work as long as the destination provides an
+C<as_integer> method like the one it expects.  To import it to a different
+destination, one can just write:
+
+  use Number::Plugin::Upto { into => 'Quantity' };    
+
+=head2 Mixing-in Complex External Behavior
+
+When exporting methods to be used as methods (see above), one very powerful
+option is to export methods that are generated routines that maintain an
+enclosed reference to the exporting module.  This allows a user to import a
+single method which is implemented in terms of a complete, well-structured
+package.
+
+Here is a very small example:
+
+  package Data::Analyzer;
+
+  use Sub::Exporter -setup => {
+    exports => [ analyze => \'_generate_analyzer' ],
+  };
+
+  sub _generate_analyzer {
+    my ($mixin, $name, $arg, $col) = @_;
+
+    return sub {
+      my ($self) = @_;
+
+      my $values = [ $self->values ];
+
+      my $analyzer = $mixin->new($values);
+      $analyzer->perform_analysis;
+      $analyzer->aggregate_results;
+
+      return $analyzer->summary;
+    };
+  }
+
+If imported by any package providing a C<values> method, this plugin will
+provide a single C<analyze> method that acts as a simple interface to a more
+complex set of behaviors.
+
+Even more importantly, because the C<$mixin> value will be the invocant on
+which the C<import> was actually called, one can subclass C<Data::Analyzer> and
+replace only individual pieces of the complex behavior, making it easy to write
+complex, subclassable toolkits with simple single points of entry for external
+interfaces.
+
+=head2 Exporting Constants
+
+While Sub::Exporter isn't in the constant-exporting business, it's easy to
+export constants by using one of its sister modules, Package::Generator.
+
+  package Important::Constants;
+ 
+  use Sub::Exporter -setup => {
+    collectors => [ constants => \'_set_constants' ],
+  };
+ 
+  sub _set_constants {
+    my ($class, $value, $data) = @_;
+ 
+    Package::Generator->assign_symbols(
+      $data->{into},
+      [
+        MEANING_OF_LIFE => \42,
+        ONE_TRUE_BASE   => \13,
+        FACTORS         => [ 6, 9 ],
+      ],
+    );
+
+    return 1;
+  }
+
+Then, someone can write:
+
+  use Important::Constants 'constants';
+  
+  print "The factors @FACTORS produce $MEANING_OF_LIFE in $ONE_TRUE_BASE.";
+
+(The constants must be exported via a collector, because they are effectively
+altering the importing class in a way other than installing subroutines.)
+
+=head2 Altering the Importer's @ISA
+
+It's trivial to make a collector that changes the inheritance of an importing
+package:
+
+  use Sub::Exporter -setup => {
+    collectors => { -base => \'_make_base' },
+  };
+
+  sub _make_base {
+    my ($class, $value, $data) = @_;
+
+    my $target = $data->{into};
+    push @{"$target\::ISA"}, $class;
+  }
+
+Then, the user of your class can write:
+
+  use Some::Class -base;
+
+and become a subclass.  This can be quite useful in building, for example, a
+module that helps build plugins.  We may want a few utilities imported, but we
+also want to inherit behavior from some base plugin class;
+
+  package Framework::Util;
+
+  use Sub::Exporter -setup => {
+    exports    => [ qw(log global_config) ],
+    groups     => [ _plugin => [ qw(log global_config) ]
+    collectors => { '-plugin' => \'_become_plugin' },
+  };
+
+  sub _become_plugin {
+    my ($class, $value, $data) = @_;
+
+    my $target = $data->{into};
+    push @{"$target\::ISA"}, $class->plugin_base_class;
+
+    push @{ $data->{import_args} }, '-_plugin';
+  }
+
+Now, you can write a plugin like this:
+
+  package Framework::Plugin::AirFreshener;
+  use Framework::Util -plugin;
+
+=head2 Eating Exporter.pm's Brain
+
+You probably shouldn't actually do this in production.  It's offered more as a
+demonstration than a suggestion.
+
+ sub exporter_upgrade {
+   my ($pkg) = @_;
+   my $new_pkg = "$pkg\::UsingSubExporter";
+
+   return $new_pkg if $new_pkg->isa($pkg);
+
+   Sub::Exporter::setup_exporter({
+     as      => 'import',
+     into    => $new_pkg,
+     exports => [ @{"$pkg\::EXPORT_OK"} ],
+     groups  => {
+       %{"$pkg\::EXPORT_TAG"},
+       default => [ @{"$pkg\::EXPORTS"} ],
+     },
+   });
+
+   @{"$new_pkg\::ISA"} = $pkg;
+   return $new_pkg;
+ }
+
+This routine, given the name of an existing package configured to use
+Exporter.pm, returns the name of a new package with a Sub::Exporter-powered
+C<import> routine.  This lets you import C<Toolkit::exported_sub> into the
+current package with the name C<foo> by writing:
+
+  BEGIN {
+    require Toolkit;
+    exporter_upgrade('Toolkit')->import(exported_sub => { -as => 'foo' })
+  }
+
+If you're feeling particularly naughty, this routine could have been declared
+in the UNIVERSAL package, meaning you could write:
+
+  BEGIN {
+    require Toolkit;
+    Toolkit->exporter_upgrade->import(exported_sub => { -as => 'foo' })
+  }
+
+The new package will have all the same exporter configuration as the original,
+but will support export and group renaming, including exporting into scalar
+references.  Further, since Sub::Exporter uses C<can> to find the routine being
+exported, the new package may be subclassed and some of its exports replaced.
+
+=head1 AUTHOR
+
+Ricardo Signes <rjbs@cpan.org>
+
+=head1 COPYRIGHT AND LICENSE
+
+This software is copyright (c) 2007 by Ricardo Signes.
+
+This is free software; you can redistribute it and/or modify it under
+the same terms as the Perl 5 programming language system itself.
+
+=cut