Lexical::Persistence(3)User Contributed Perl DocumentatioLnexical::Persistence(3)


NNAAMMEE
       Lexical::Persistence − Persistent lexical variable values for arbitrary
       calls.

SSYYNNOOPPSSIISS
               #!/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";
               }

DDEESSCCRRIIPPTTIIOONN
       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 perists in the $lp object between _s_e_t_t_e_r_(_) and _g_e_t_t_e_r_(_).

               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 _s_e_t___c_o_n_t_e_x_t_(_) 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, _c_a_l_l_(_) 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 _w_r_a_p_(_) method will
       wrap your function in a small thunk that does the _c_a_l_l_(_) 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 _s_e_t___c_o_n_t_e_x_t_(_), are
       stored in that context.

       The _g_e_t___c_o_n_t_e_x_t_(_) 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

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

       nneeww

       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.

       iinniittiiaalliizzee__ccoonntteexxttss

       This method is called by _n_e_w_(_) 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.

       sseett__ccoonntteexxtt NNAAMMEE,, HHAASSHH

       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 _s_e_t___c_o_n_t_e_x_t_(_)
       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 _p_a_r_s_e___v_a_r_i_a_b_l_e_(_) for information about how Lexical::Persistence
       decides which context a lexical belongs to and how you can change that.

       ggeett__ccoonntteexxtt NNAAMMEE

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

       ccaallll CCOODDEERREEFF,, AARRGGUUMMEENNTT__LLIISSTT

       Call CODEREF with lexical persistence and an optional ARGUMENT_LIST,
       consisting of name => value pairs.  Unlike with _s_e_t___c_o_n_t_e_x_t_(_), 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 _p_u_s_h___a_r_g___c_o_n_t_e_x_t_(_) for information about how $arg_name works, and
       what you can do to change that behavior.

       iinnvvookkee OOBBJJEECCTT,, MMEETTHHOODD,, AARRGGUUMMEENNTT__LLIISSTT

       Invoke OBJECT−>METHOD(ARGUMENT_LIST) while maintaining state for the
       METHOD’s lexical variables.  Written in terms of _c_a_l_l_(_), except that it
       takes OBJECT and METHOD rather than CODEREF.  See _c_a_l_l_(_) for more
       details.

       May have issues with methods invoked via AUTOLOAD, as _i_n_v_o_k_e_(_) uses
       _c_a_n_(_) to find the method’s CODEREF for _c_a_l_l_(_).

       wwrraapp CCOODDEERREEFF

       Wrap a function or anonymous CODEREF so that it’s transparently called
       via _c_a_l_l_(_).  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 _c_a_l_l_(_) and _p_u_s_h___a_r_g___c_o_n_t_e_x_t_(_) for more details.

       ppaarrssee__vvaarriiaabbllee VVAARRIIAABBLLEE__NNAAMMEE

       This method determines whether VARIABLE_NAME should be persistent.  If
       it should, _p_a_r_s_e___v_a_r_i_a_b_l_e_(_) will return three values: the variable’s
       sigil (’$’, ’@’ or ’%’), the context name in which the variable
       persists (see _s_e_t___c_o_n_t_e_x_t_(_)), and the name of the member within that
       context where the value is stored.  _p_a_r_s_e___v_a_r_i_a_b_l_e_(_) returns nothing if
       VARIABLE_NAME should not be persistent.

       _p_a_r_s_e___v_a_r_i_a_b_l_e_(_) 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 _c_a_l_l_(_).

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

       ggeett__mmeemmbbeerr__rreeff SSIIGGIILL,, CCOONNTTEEXXTT,, MMEEMMBBEERR

       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.

       ppuusshh__aarrgg__ccoonntteexxtt AARRGGUUMMEENNTT__LLIISSTT

       Convert a named ARGUMENT_LIST into members of an argument context, and
       call _s_e_t___c_o_n_t_e_x_t_(_) to declare that context.  This is how $arg_foo
       variables are supported.  This method returns the previous context,
       fetched by _g_e_t___c_o_n_t_e_x_t_(_) 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 _p_o_p___a_r_g___c_o_n_t_e_x_t_(_) for the other side of this coin.

       ppoopp__aarrgg__ccoonntteexxtt OOLLDD__AARRGG__CCOONNTTEEXXTT

       Restores OLD_ARG_CONTEXT after a target function has returned.  The
       OLD_ARG_CONTEXT is the return value from the _p_u_s_h___a_r_g___c_o_n_t_e_x_t_(_) 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.

BBUUGGSS
       Read them at
       http://rt.cpan.org/Public/Dist/Display.html?Name=lexical−persistence

       Report them at
       http://rt.cpan.org/Public/Bug/Report.html?Queue=lexical−persistence

SSEEEE AALLSSOO
       POE::Stage, Devel::LexAlias, PadWalker, Catalyst::Controller::BindLex.

CCOOPPYYRRIIGGHHTT
       Lexical::Persistence in copyright 2006 by Rocco Caputo.  All rights
       reserved.  Lexical::Persistence is free software.  It is released under
       the same terms as Perl itself.

AACCKKNNOOWWLLEEDDGGEEMMEENNTTSS
       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.

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

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


perl v5.8.8                       2007‐03‐18           Lexical::Persistence(3)