--- name: "Lexical::Persistence" section: "3pm" platform: "linux" package: "liblexical-persistence-perl" version: "1.023-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Lexical::Persistence" --- # Lexical::Persistence(3pm) Persistent lexical variable values for arbitrary calls. ## NAME Lexical::Persistence - Persistent lexical variable values for arbitrary calls. ## VERSION version 1.023 ## 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.