Provided by: liblexical-persistence-perl_1.022-1_all bug

NAME

       Lexical::Persistence - Persistent lexical variable values for arbitrary calls.

VERSION

       version 1.022

SYNOPSIS

               #!/usr/bin/perl

               use Lexical::Persistence;

               my $persistence = Lexical::Persistence->new();
               foreach my $number (qw(one two three four five)) {
                       $persistence->call(\&target, number => $number);
               }

               exit;

               sub target {
                       my $arg_number;   # Argument.
                       my $narf_x++;     # Persistent.
                       my $_i++;         # Dynamic.
                       my $j++;          # Persistent.

                       print "arg_number = $arg_number\n";
                       print "\tnarf_x = $narf_x\n";
                       print "\t_i = $_i\n";
                       print "\tj = $j\n";
               }

DESCRIPTION

       Lexical::Persistence does a few things, all related.  Note that all the behaviors listed
       here are the defaults.  Subclasses can override nearly every aspect of
       Lexical::Persistence's behavior.

       Lexical::Persistence lets your code access persistent data through lexical variables.
       This example prints "some value" because the value of $x persists in the $lp object
       between setter() and getter().

               use Lexical::Persistence;

               my $lp = Lexical::Persistence->new();
               $lp->call(\&setter);
               $lp->call(\&getter);

               sub setter { my $x = "some value" }
               sub getter { print my $x, "\n" }

       Lexicals with leading underscores are not persistent.

       By default, Lexical::Persistence supports accessing data from multiple sources through the
       use of variable prefixes.  The set_context() member sets each data source.  It takes a
       prefix name and a hash of key/value pairs.  By default, the keys must have sigils
       representing their variable types.

               use Lexical::Persistence;

               my $lp = Lexical::Persistence->new();
               $lp->set_context( pi => { '$member' => 3.141 } );
               $lp->set_context( e => { '@member' => [ 2, '.', 7, 1, 8 ] } );
               $lp->set_context(
                       animal => {
                               '%member' => { cat => "meow", dog => "woof" }
                       }
               );

               $lp->call(\&display);

               sub display {
                       my ($pi_member, @e_member, %animal_member);

                       print "pi = $pi_member\n";
                       print "e = @e_member\n";
                       while (my ($animal, $sound) = each %animal_member) {
                               print "The $animal goes... $sound!\n";
                       }
               }

       And the corresponding output:

               pi = 3.141
               e = 2 . 7 1 8
               The cat goes... meow!
               The dog goes... woof!

       By default, call() takes a single subroutine reference and an optional list of named
       arguments.  The arguments will be passed directly to the called subroutine, but
       Lexical::Persistence also makes the values available from the "arg" prefix.

               use Lexical::Persistence;

               my %animals = (
                       snake => "hiss",
                       plane => "I'm Cartesian",
               );

               my $lp = Lexical::Persistence->new();
               while (my ($animal, $sound) = each %animals) {
                       $lp->call(\&display, animal => $animal, sound => $sound);
               }

               sub display {
                       my ($arg_animal, $arg_sound);
                       print "The $arg_animal goes... $arg_sound!\n";
               }

       And the corresponding output:

               The plane goes... I'm Cartesian!
               The snake goes... hiss!

       Sometimes you want to call functions normally.  The wrap() method will wrap your function
       in a small thunk that does the call() for you, returning a coderef.

               use Lexical::Persistence;

               my $lp = Lexical::Persistence->new();
               my $thunk = $lp->wrap(\&display);

               $thunk->(animal => "squirrel", sound => "nuts");

               sub display {
                       my ($arg_animal, $arg_sound);
                       print "The $arg_animal goes... $arg_sound!\n";
               }

       And the corresponding output:

               The squirrel goes... nuts!

       Prefixes are the characters leading up to the first underscore in a lexical variable's
       name.  However, there's also a default context named underscore.  It's literally "_"
       because the underscore is not legal in a context name by default.  Variables without
       prefixes, or with prefixes that have not been previously defined by set_context(), are
       stored in that context.

       The get_context() member returns a hash for a named context.  This allows your code to
       manipulate the values within a persistent context.

               use Lexical::Persistence;

               my $lp = Lexical::Persistence->new();
               $lp->set_context(
                       _ => {
                               '@mind' => [qw(My mind is going. I can feel it.)]
                       }
               );

               while (1) {
                       $lp->call(\&display);
                       my $mind = $lp->get_context("_")->{'@mind'};
                       splice @$mind, rand(@$mind), 1;
                       last unless @$mind;
               }

               sub display {
                       my @mind;
                       print "@mind\n";
               }

       Displays something like:

               My mind is going. I can feel it.
               My is going. I can feel it.
               My is going. I feel it.
               My going. I feel it.
               My going. I feel
               My I feel
               My I
               My

       It's possible to create multiple Lexical::Persistence objects, each with a unique state.

               use Lexical::Persistence;

               my $lp_1 = Lexical::Persistence->new();
               $lp_1->set_context( _ => { '$foo' => "context 1's foo" } );

               my $lp_2 = Lexical::Persistence->new();
               $lp_2->set_context( _ => { '$foo' => "the foo in context 2" } );

               $lp_1->call(\&display);
               $lp_2->call(\&display);

               sub display {
                       print my $foo, "\n";
               }

       Gets you this output:

               context 1's foo
               the foo in context 2

       You can also compile and execute perl code contained in plain strings in a a lexical
       environment that already contains the persisted variables.

               use Lexical::Persistence;

               my $lp = Lexical::Persistence->new();

               $lp->do( 'my $message = "Hello, world" );

               $lp->do( 'print "$message\n"' );

       Which gives the output:

               Hello, world

       If you come up with other fun uses, let us know.

   new
       Create a new lexical persistence object.  This object will store one or more persistent
       contexts.  When called by this object, lexical variables will take on the values kept in
       this object.

   initialize_contexts
       This method is called by new() to declare the initial contexts for a new
       Lexical::Persistence object.  The default implementation declares the default "_" context.

       Override or extend it to create others as needed.

   set_context NAME, HASH
       Store a context HASH within the persistence object, keyed on a NAME.  Members of the
       context HASH are unprefixed versions of the lexicals they'll persist, including the sigil.
       For example, this set_context() call declares a "request" context with predefined values
       for three variables: $request_foo, @request_foo, and %request_foo:

               $lp->set_context(
                       request => {
                               '$foo' => 'value of $request_foo',
                               '@foo' => [qw( value of @request_foo )],
                               '%foo' => { key => 'value of $request_foo{key}' }
                       }
               );

       See parse_variable() for information about how Lexical::Persistence decides which context
       a lexical belongs to and how you can change that.

   get_context NAME
       Returns a context hash associated with a particular context name.  Autovivifies the
       context if it doesn't already exist, so be careful there.

   call CODEREF, ARGUMENT_LIST
       Call CODEREF with lexical persistence and an optional ARGUMENT_LIST, consisting of name =>
       value pairs.  Unlike with set_context(), however, argument names do not need sigils.  This
       may change in the future, however, as it's easy to access an argument with the wrong
       variable type.

       The ARGUMENT_LIST is passed to the called CODEREF through @_ in the usual way.  They're
       also available as $arg_name variables for convenience.

       See push_arg_context() for information about how $arg_name works, and what you can do to
       change that behavior.

   invoke OBJECT, METHOD, ARGUMENT_LIST
       Invoke OBJECT->METHOD(ARGUMENT_LIST) while maintaining state for the METHOD's lexical
       variables.  Written in terms of call(), except that it takes OBJECT and METHOD rather than
       CODEREF.  See call() for more details.

       May have issues with methods invoked via AUTOLOAD, as invoke() uses can() to find the
       method's CODEREF for call().

   wrap CODEREF
       Wrap a function or anonymous CODEREF so that it's transparently called via call().
       Returns a coderef which can be called directly.  Named arguments to the call will
       automatically become available as $arg_name lexicals within the called CODEREF.

       See call() and push_arg_context() for more details.

   prepare CODE
       Wrap a CODE string in a subroutine definition, and prepend declarations for all the
       variables stored in the Lexical::Persistence default context.  This avoids having to
       declare variables explicitly in the code using 'my'.  Returns a new code string ready for
       Perl's built-in eval().  From there, a program may $lp->call() the code or $lp->wrap() it.

       Also see "compile()", which is a convenient wrapper for prepare() and Perl's built-in
       eval().

       Also see "do()", which is a convenient way to prepare(), eval() and call() in one step.

   compile CODE
       compile() is a convenience method to prepare() a CODE string, eval() it, and then return
       the resulting coderef.  If it fails, it returns false, and $@ will explain why.

   do CODE
       do() is a convenience method to compile() a CODE string and execute it.  It returns the
       result of CODE's execution, or it throws an exception on failure.

       This example prints the numbers 1 through 10.  Note, however, that do() compiles the same
       code each time.

               use Lexical::Persistence;

               my $lp = Lexical::Persistence->new();
               $lp->do('my $count = 0');
               $lp->do('print ++$count, "\\n"') for 1..10;

       Lexical declarations are preserved across do() invocations, such as with $count in the
       surrounding examples.  This behavior is part of prepare(), which do() uses via compile().

       The previous example may be rewritten in terms of compile() and call() to avoid
       recompiling code every iteration.  Lexical declarations are preserved between do() and
       compile() as well:

               use Lexical::Persistence;

               my $lp = Lexical::Persistence->new();
               $lp->do('my $count = 0');
               my $coderef = $lp->compile('print ++$count, "\\n"');
               $lp->call($coderef) for 1..10;

       do() inherits some limitations from PadWalker's peek_sub().  For instance, it cannot alias
       lexicals within sub() definitions in the supplied CODE string.  However,
       Lexical::Persistence can do this with careful use of eval() and some custom CODE
       preparation.

   parse_variable VARIABLE_NAME
       This method determines whether VARIABLE_NAME should be persistent.  If it should,
       parse_variable() will return three values: the variable's sigil ('$', '@' or '%'), the
       context name in which the variable persists (see set_context()), and the name of the
       member within that context where the value is stored.  parse_variable() returns nothing if
       VARIABLE_NAME should not be persistent.

       parse_variable() also determines whether the member name includes its sigil.  By default,
       the "arg" context is the only one with members that have no sigils.  This is done to
       support the unadorned argument names used by call().

       This method implements a default behavior.  It's intended to be overridden or extended by
       subclasses.

   get_member_ref SIGIL, CONTEXT, MEMBER
       This method fetches a reference to the named MEMBER of a particular named CONTEXT.  The
       returned value type will be governed by the given SIGIL.

       Scalar values are stored internally as scalars to be consistent with how most people store
       scalars.

       The persistent value is created if it doesn't exist.  The initial value is undef or empty,
       depending on its type.

       This method implements a default behavior.  It's intended to be overridden or extended by
       subclasses.

   push_arg_context ARGUMENT_LIST
       Convert a named ARGUMENT_LIST into members of an argument context, and call set_context()
       to declare that context.  This is how $arg_foo variables are supported.  This method
       returns the previous context, fetched by get_context() before the new context is set.

       This method implements a default behavior.  It's intended to be overridden or extended by
       subclasses.  For example, to redefine the parameters as $param_foo.

       See pop_arg_context() for the other side of this coin.

   pop_arg_context OLD_ARG_CONTEXT
       Restores OLD_ARG_CONTEXT after a target function has returned.  The OLD_ARG_CONTEXT is the
       return value from the push_arg_context() call just prior to the target function's call.

       This method implements a default behavior.  It's intended to be overridden or extended by
       subclasses.

SEE ALSO

       POE::Stage, Devel::LexAlias, PadWalker, Catalyst::Controller::BindLex.

   BUG TRACKER
       https://rt.cpan.org/Dist/Display.html?Status=Active&Queue=Lexical-Persistence

   REPOSITORY
       http://github.com/rcaputo/lexical-persistence http://gitorious.org/lexical-persistence

   OTHER RESOURCES
       http://search.cpan.org/dist/Lexical-Persistence/

COPYRIGHT

       Lexical::Persistence in copyright 2006-2013 by Rocco Caputo.  All rights reserved.
       Lexical::Persistence is free software.  It is released under the same terms as Perl
       itself.

ACKNOWLEDGEMENTS

       Thanks to Matt Trout and Yuval Kogman for lots of inspiration.  They were the demon and
       the other demon sitting on my shoulders.

       Nick Perez convinced me to make this a class rather than persist with the original,
       functional design.  While Higher Order Perl is fun for development, I have to say the move
       to OO was a good one.

       Paul "LeoNerd" Evans contributed the compile() and eval() methods.

       The South Florida Perl Mongers, especially Jeff Bisbee and Marlon Bailey, for
       documentation feedback.

       irc://irc.perl.org/poe for support and feedback.