opener-tokenizer-base 1.0.0

data/core/lib/Sub/Exporter/Cookbook.pod

@@ -0,0 +1,309 @@
+
+# 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.984
+
+=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"} = $class;
+   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 write:
+
+  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
+

data/core/lib/Sub/Exporter/Tutorial.pod

@@ -0,0 +1,280 @@
+
+# PODNAME: Sub::Exporter::Tutorial
+# ABSTRACT: a friendly guide to exporting with Sub::Exporter
+
+
+__END__
+=pod
+
+=head1 NAME
+
+Sub::Exporter::Tutorial - a friendly guide to exporting with Sub::Exporter
+
+=head1 VERSION
+
+version 0.984
+
+=head1 DESCRIPTION
+
+=head2 What's an Exporter?
+
+When you C<use> a module, first it is required, then its C<import> method is
+called.  The Perl documentation tells us that the following two lines are
+equivalent:
+
+  use Module LIST;
+
+  BEGIN { require Module; Module->import(LIST); }
+
+The import method is the module's I<exporter>.
+
+=head2 The Basics of Sub::Exporter
+
+Sub::Exporter builds a custom exporter which can then be installed into your
+module.  It builds this method based on configuration passed to its
+C<setup_exporter> method.
+
+A very basic use case might look like this:
+
+  package Addition;
+  use Sub::Exporter;
+  Sub::Exporter::setup_exporter({ exports => [ qw(plus) ]});
+
+  sub plus { my ($x, $y) = @_; return $x + $y; }
+
+This would mean that when someone used your Addition module, they could have
+its C<plus> routine imported into their package:
+
+  use Addition qw(plus);
+
+  my $z = plus(2, 2); # this works, because now plus is in the main package
+
+That syntax to set up the exporter, above, is a little verbose, so for the
+simple case of just naming some exports, you can write this:
+
+  use Sub::Exporter -setup => { exports => [ qw(plus) ] };
+
+...which is the same as the original example -- except that now the exporter is
+built and installed at compile time.  Well, that and you typed less.
+
+=head2 Using Export Groups
+
+You can specify whole groups of things that should be exportable together.
+These are called groups.  L<Exporter> calls these tags.  To specify groups, you
+just pass a C<groups> key in your exporter configuration:
+
+  package Food;
+  use Sub::Exporter -setup => {
+    exports => [ qw(apple banana beef fluff lox rabbit) ],
+    groups  => {
+      fauna  => [ qw(beef lox rabbit) ],
+      flora  => [ qw(apple banana) ],
+    }
+  };
+
+Now, to import all that delicious foreign meat, your consumer needs only to
+write:
+
+  use Food qw(:fauna);
+  use Food qw(-fauna);
+
+Either one of the above is acceptable.  A colon is more traditional, but
+barewords with a leading colon can't be enquoted by a fat arrow.  We'll see why
+that matters later on.
+
+Groups can contain other groups.  If you include a group name (with the leading
+dash or colon) in a group definition, it will be expanded recursively when the
+exporter is called.  The exporter will B<not> recurse into the same group twice
+while expanding groups.
+
+There are two special groups:  C<all> and C<default>.  The C<all> group is
+defined by default, and contains all exportable subs.  You can redefine it,
+if you want to export only a subset when all exports are requested.  The
+C<default> group is the set of routines to export when nothing specific is
+requested.  By default, there is no C<default> group.
+
+=head2 Renaming Your Imports
+
+Sometimes you want to import something, but you don't like the name as which
+it's imported.  Sub::Exporter can rename your imports for you.  If you wanted
+to import C<lox> from the Food package, but you don't like the name, you could
+write this:
+
+  use Food lox => { -as => 'salmon' };
+
+Now you'd get the C<lox> routine, but it would be called salmon in your
+package.  You can also rename entire groups by using the C<prefix> option:
+
+  use Food -fauna => { -prefix => 'cute_little_' };
+
+Now you can call your C<cute_little_rabbit> routine.  (You can also call
+C<cute_little_beef>, but that hardly seems as enticing.)
+
+When you define groups, you can include renaming.
+
+  use Sub::Exporter -setup => {
+    exports => [ qw(apple banana beef fluff lox rabbit) ],
+    groups  => {
+      fauna  => [ qw(beef lox), rabbit => { -as => 'coney' } ],
+    }
+  };
+
+A prefix on a group like that does the right thing.  This is when it's useful
+to use a dash instead of a colon to indicate a group: you can put a fat arrow
+between the group and its arguments, then.
+
+  use Food -fauna => { -prefix => 'lovely_' };
+
+  eat( lovely_coney ); # this works
+
+Prefixes also apply recursively.  That means that this code works:
+
+  use Sub::Exporter -setup => {
+    exports => [ qw(apple banana beef fluff lox rabbit) ],
+    groups  => {
+      fauna   => [ qw(beef lox), rabbit => { -as => 'coney' } ],
+      allowed => [ -fauna => { -prefix => 'willing_' }, 'banana' ],
+    }
+  };
+
+  ...
+
+  use Food -allowed => { -prefix => 'any_' };
+
+  $dinner = any_willing_coney; # yum!
+
+Groups can also be passed a C<-suffix> argument.
+
+Finally, if the C<-as> argument to an exported routine is a reference to a
+scalar, a reference to the routine will be placed in that scalar.
+
+=head2 Building Subroutines to Order
+
+Sometimes, you want to export things that you don't have on hand.  You might
+want to offer customized routines built to the specification of your consumer;
+that's just good business!  With Sub::Exporter, this is easy.
+
+To offer subroutines to order, you need to provide a generator when you set up
+your exporter.  A generator is just a routine that returns a new routine.
+L<perlref> is talking about these when it discusses closures and function
+templates. The canonical example of a generator builds a unique incrementor;
+here's how you'd do that with Sub::Exporter;
+
+  package Package::Counter;
+  use Sub::Exporter -setup => {
+    exports => [ counter => sub { my $i = 0; sub { $i++ } } ],
+    groups  => { default => [ qw(counter) ] },
+  };
+
+Now anyone can use your Package::Counter module and he'll receive a C<counter>
+in his package.  It will count up by one, and will never interfere with anyone
+else's counter.
+
+This isn't very useful, though, unless the consumer can explain what he wants.
+This is done, in part, by supplying arguments when importing.  The following
+example shows how a generator can take and use arguments:
+
+  package Package::Counter;
+
+  sub _build_counter {
+    my ($class, $name, $arg) = @_;
+    $arg ||= {};
+    my $i = $arg->{start} || 0;
+    return sub { $i++ };
+  }
+
+  use Sub::Exporter -setup => {
+    exports => [ counter => \'_build_counter' ],
+    groups  => { default => [ qw(counter) ] },
+  };
+
+Now, the consumer can (if he wants) specify a starting value for his counter:
+
+  use Package::Counter counter => { start => 10 };
+
+Arguments to a group are passed along to the generators of routines in that
+group, but Sub::Exporter arguments -- anything beginning with a dash -- are
+never passed in.  When groups are nested, the arguments are merged as the
+groups are expanded.
+
+Notice, too, that in the example above, we gave a reference to a method I<name>
+rather than a method I<implementation>.  By giving the name rather than the
+subroutine, we make it possible for subclasses of our "Package::Counter" module
+to replace the C<_build_counter> method.
+
+When a generator is called, it is passed four parameters:
+
+=over
+
+=item * the invocant on which the exporter was called
+
+=item * the name of the export being generated (not the name it's being installed as)
+
+=item * the arguments supplied for the routine
+
+=item * the collection of generic arguments
+
+=back
+
+The fourth item is the last major feature that hasn't been covered.
+
+=head2 Argument Collectors
+
+Sometimes you will want to accept arguments once that can then be available to
+any subroutine that you're going to export.  To do this, you specify
+collectors, like this:
+
+  package Menu::Airline
+  use Sub::Exporter -setup => {
+    exports =>  ... ,
+    groups  =>  ... ,
+    collectors => [ qw(allergies ethics) ],
+  };
+
+Collectors look like normal exports in the import call, but they don't do
+anything but collect data which can later be passed to generators.  If the
+module was used like this:
+
+  use Menu::Airline allergies => [ qw(peanuts) ], ethics => [ qw(vegan) ];
+
+...the consumer would get a salad.  Also, all the generators would be passed,
+as their fourth argument, something like this:
+
+  { allerges => [ qw(peanuts) ], ethics => [ qw(vegan) ] }
+
+Generators may have arguments in their definition, as well.  These must be code
+refs that perform validation of the collected values.  They are passed the
+collection value and may return true or false.  If they return false, the
+exporter will throw an exception.
+
+=head2 Generating Many Routines in One Scope
+
+Sometimes it's useful to have multiple routines generated in one scope.  This
+way they can share lexical data which is otherwise unavailable.  To do this,
+you can supply a generator for a group which returns a hashref of names and
+code references.  This generator is passed all the usual data, and the group
+may receive the usual C<-prefix> or C<-suffix> arguments.
+
+=head1 SEE ALSO
+
+=over 4
+
+=item *
+
+L<Sub::Exporter> for complete documentation and references to other exporters
+
+=back
+
+=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
+