1Lexical::Persistence(3)User Contributed Perl DocumentatioLnexical::Persistence(3)
2
3
4

NAME

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

VERSION

10       version 1.023
11

SYNOPSIS

13               #!/usr/bin/perl
14
15               use Lexical::Persistence;
16
17               my $persistence = Lexical::Persistence->new();
18               foreach my $number (qw(one two three four five)) {
19                       $persistence->call(\&target, number => $number);
20               }
21
22               exit;
23
24               sub target {
25                       my $arg_number;   # Argument.
26                       my $narf_x++;     # Persistent.
27                       my $_i++;         # Dynamic.
28                       my $j++;          # Persistent.
29
30                       print "arg_number = $arg_number\n";
31                       print "\tnarf_x = $narf_x\n";
32                       print "\t_i = $_i\n";
33                       print "\tj = $j\n";
34               }
35

DESCRIPTION

37       Lexical::Persistence does a few things, all related.  Note that all the
38       behaviors listed here are the defaults.  Subclasses can override nearly
39       every aspect of Lexical::Persistence's behavior.
40
41       Lexical::Persistence lets your code access persistent data through
42       lexical variables.  This example prints "some value" because the value
43       of $x persists in the $lp object between setter() and getter().
44
45               use Lexical::Persistence;
46
47               my $lp = Lexical::Persistence->new();
48               $lp->call(\&setter);
49               $lp->call(\&getter);
50
51               sub setter { my $x = "some value" }
52               sub getter { print my $x, "\n" }
53
54       Lexicals with leading underscores are not persistent.
55
56       By default, Lexical::Persistence supports accessing data from multiple
57       sources through the use of variable prefixes.  The set_context() member
58       sets each data source.  It takes a prefix name and a hash of key/value
59       pairs.  By default, the keys must have sigils representing their
60       variable types.
61
62               use Lexical::Persistence;
63
64               my $lp = Lexical::Persistence->new();
65               $lp->set_context( pi => { '$member' => 3.141 } );
66               $lp->set_context( e => { '@member' => [ 2, '.', 7, 1, 8 ] } );
67               $lp->set_context(
68                       animal => {
69                               '%member' => { cat => "meow", dog => "woof" }
70                       }
71               );
72
73               $lp->call(\&display);
74
75               sub display {
76                       my ($pi_member, @e_member, %animal_member);
77
78                       print "pi = $pi_member\n";
79                       print "e = @e_member\n";
80                       while (my ($animal, $sound) = each %animal_member) {
81                               print "The $animal goes... $sound!\n";
82                       }
83               }
84
85       And the corresponding output:
86
87               pi = 3.141
88               e = 2 . 7 1 8
89               The cat goes... meow!
90               The dog goes... woof!
91
92       By default, call() takes a single subroutine reference and an optional
93       list of named arguments.  The arguments will be passed directly to the
94       called subroutine, but Lexical::Persistence also makes the values
95       available from the "arg" prefix.
96
97               use Lexical::Persistence;
98
99               my %animals = (
100                       snake => "hiss",
101                       plane => "I'm Cartesian",
102               );
103
104               my $lp = Lexical::Persistence->new();
105               while (my ($animal, $sound) = each %animals) {
106                       $lp->call(\&display, animal => $animal, sound => $sound);
107               }
108
109               sub display {
110                       my ($arg_animal, $arg_sound);
111                       print "The $arg_animal goes... $arg_sound!\n";
112               }
113
114       And the corresponding output:
115
116               The plane goes... I'm Cartesian!
117               The snake goes... hiss!
118
119       Sometimes you want to call functions normally.  The wrap() method will
120       wrap your function in a small thunk that does the call() for you,
121       returning a coderef.
122
123               use Lexical::Persistence;
124
125               my $lp = Lexical::Persistence->new();
126               my $thunk = $lp->wrap(\&display);
127
128               $thunk->(animal => "squirrel", sound => "nuts");
129
130               sub display {
131                       my ($arg_animal, $arg_sound);
132                       print "The $arg_animal goes... $arg_sound!\n";
133               }
134
135       And the corresponding output:
136
137               The squirrel goes... nuts!
138
139       Prefixes are the characters leading up to the first underscore in a
140       lexical variable's name.  However, there's also a default context named
141       underscore.  It's literally "_" because the underscore is not legal in
142       a context name by default.  Variables without prefixes, or with
143       prefixes that have not been previously defined by set_context(), are
144       stored in that context.
145
146       The get_context() member returns a hash for a named context.  This
147       allows your code to manipulate the values within a persistent context.
148
149               use Lexical::Persistence;
150
151               my $lp = Lexical::Persistence->new();
152               $lp->set_context(
153                       _ => {
154                               '@mind' => [qw(My mind is going. I can feel it.)]
155                       }
156               );
157
158               while (1) {
159                       $lp->call(\&display);
160                       my $mind = $lp->get_context("_")->{'@mind'};
161                       splice @$mind, rand(@$mind), 1;
162                       last unless @$mind;
163               }
164
165               sub display {
166                       my @mind;
167                       print "@mind\n";
168               }
169
170       Displays something like:
171
172               My mind is going. I can feel it.
173               My is going. I can feel it.
174               My is going. I feel it.
175               My going. I feel it.
176               My going. I feel
177               My I feel
178               My I
179               My
180
181       It's possible to create multiple Lexical::Persistence objects, each
182       with a unique state.
183
184               use Lexical::Persistence;
185
186               my $lp_1 = Lexical::Persistence->new();
187               $lp_1->set_context( _ => { '$foo' => "context 1's foo" } );
188
189               my $lp_2 = Lexical::Persistence->new();
190               $lp_2->set_context( _ => { '$foo' => "the foo in context 2" } );
191
192               $lp_1->call(\&display);
193               $lp_2->call(\&display);
194
195               sub display {
196                       print my $foo, "\n";
197               }
198
199       Gets you this output:
200
201               context 1's foo
202               the foo in context 2
203
204       You can also compile and execute perl code contained in plain strings
205       in a a lexical environment that already contains the persisted
206       variables.
207
208               use Lexical::Persistence;
209
210               my $lp = Lexical::Persistence->new();
211
212               $lp->do( 'my $message = "Hello, world" );
213
214               $lp->do( 'print "$message\n"' );
215
216       Which gives the output:
217
218               Hello, world
219
220       If you come up with other fun uses, let us know.
221
222   new
223       Create a new lexical persistence object.  This object will store one or
224       more persistent contexts.  When called by this object, lexical
225       variables will take on the values kept in this object.
226
227   initialize_contexts
228       This method is called by new() to declare the initial contexts for a
229       new Lexical::Persistence object.  The default implementation declares
230       the default "_" context.
231
232       Override or extend it to create others as needed.
233
234   set_context NAME, HASH
235       Store a context HASH within the persistence object, keyed on a NAME.
236       Members of the context HASH are unprefixed versions of the lexicals
237       they'll persist, including the sigil.  For example, this set_context()
238       call declares a "request" context with predefined values for three
239       variables: $request_foo, @request_foo, and %request_foo:
240
241               $lp->set_context(
242                       request => {
243                               '$foo' => 'value of $request_foo',
244                               '@foo' => [qw( value of @request_foo )],
245                               '%foo' => { key => 'value of $request_foo{key}' }
246                       }
247               );
248
249       See parse_variable() for information about how Lexical::Persistence
250       decides which context a lexical belongs to and how you can change that.
251
252   get_context NAME
253       Returns a context hash associated with a particular context name.
254       Autovivifies the context if it doesn't already exist, so be careful
255       there.
256
257   call CODEREF, ARGUMENT_LIST
258       Call CODEREF with lexical persistence and an optional ARGUMENT_LIST,
259       consisting of name => value pairs.  Unlike with set_context(), however,
260       argument names do not need sigils.  This may change in the future,
261       however, as it's easy to access an argument with the wrong variable
262       type.
263
264       The ARGUMENT_LIST is passed to the called CODEREF through @_ in the
265       usual way.  They're also available as $arg_name variables for
266       convenience.
267
268       See push_arg_context() for information about how $arg_name works, and
269       what you can do to change that behavior.
270
271   invoke OBJECT, METHOD, ARGUMENT_LIST
272       Invoke OBJECT->METHOD(ARGUMENT_LIST) while maintaining state for the
273       METHOD's lexical variables.  Written in terms of call(), except that it
274       takes OBJECT and METHOD rather than CODEREF.  See call() for more
275       details.
276
277       May have issues with methods invoked via AUTOLOAD, as invoke() uses
278       can() to find the method's CODEREF for call().
279
280   wrap CODEREF
281       Wrap a function or anonymous CODEREF so that it's transparently called
282       via call().  Returns a coderef which can be called directly.  Named
283       arguments to the call will automatically become available as $arg_name
284       lexicals within the called CODEREF.
285
286       See call() and push_arg_context() for more details.
287
288   prepare CODE
289       Wrap a CODE string in a subroutine definition, and prepend declarations
290       for all the variables stored in the Lexical::Persistence default
291       context.  This avoids having to declare variables explicitly in the
292       code using 'my'.  Returns a new code string ready for Perl's built-in
293       eval().  From there, a program may $lp->call() the code or $lp->wrap()
294       it.
295
296       Also see "compile()", which is a convenient wrapper for prepare() and
297       Perl's built-in eval().
298
299       Also see "do()", which is a convenient way to prepare(), eval() and
300       call() in one step.
301
302   compile CODE
303       compile() is a convenience method to prepare() a CODE string, eval()
304       it, and then return the resulting coderef.  If it fails, it returns
305       false, and $@ will explain why.
306
307   do CODE
308       do() is a convenience method to compile() a CODE string and execute it.
309       It returns the result of CODE's execution, or it throws an exception on
310       failure.
311
312       This example prints the numbers 1 through 10.  Note, however, that do()
313       compiles the same code each time.
314
315               use Lexical::Persistence;
316
317               my $lp = Lexical::Persistence->new();
318               $lp->do('my $count = 0');
319               $lp->do('print ++$count, "\\n"') for 1..10;
320
321       Lexical declarations are preserved across do() invocations, such as
322       with $count in the surrounding examples.  This behavior is part of
323       prepare(), which do() uses via compile().
324
325       The previous example may be rewritten in terms of compile() and call()
326       to avoid recompiling code every iteration.  Lexical declarations are
327       preserved between do() and compile() as well:
328
329               use Lexical::Persistence;
330
331               my $lp = Lexical::Persistence->new();
332               $lp->do('my $count = 0');
333               my $coderef = $lp->compile('print ++$count, "\\n"');
334               $lp->call($coderef) for 1..10;
335
336       do() inherits some limitations from PadWalker's peek_sub().  For
337       instance, it cannot alias lexicals within sub() definitions in the
338       supplied CODE string.  However, Lexical::Persistence can do this with
339       careful use of eval() and some custom CODE preparation.
340
341   parse_variable VARIABLE_NAME
342       This method determines whether VARIABLE_NAME should be persistent.  If
343       it should, parse_variable() will return three values: the variable's
344       sigil ('$', '@' or '%'), the context name in which the variable
345       persists (see set_context()), and the name of the member within that
346       context where the value is stored.  parse_variable() returns nothing if
347       VARIABLE_NAME should not be persistent.
348
349       parse_variable() also determines whether the member name includes its
350       sigil.  By default, the "arg" context is the only one with members that
351       have no sigils.  This is done to support the unadorned argument names
352       used by call().
353
354       This method implements a default behavior.  It's intended to be
355       overridden or extended by subclasses.
356
357   get_member_ref SIGIL, CONTEXT, MEMBER
358       This method fetches a reference to the named MEMBER of a particular
359       named CONTEXT.  The returned value type will be governed by the given
360       SIGIL.
361
362       Scalar values are stored internally as scalars to be consistent with
363       how most people store scalars.
364
365       The persistent value is created if it doesn't exist.  The initial value
366       is undef or empty, depending on its type.
367
368       This method implements a default behavior.  It's intended to be
369       overridden or extended by subclasses.
370
371   push_arg_context ARGUMENT_LIST
372       Convert a named ARGUMENT_LIST into members of an argument context, and
373       call set_context() to declare that context.  This is how $arg_foo
374       variables are supported.  This method returns the previous context,
375       fetched by get_context() before the new context is set.
376
377       This method implements a default behavior.  It's intended to be
378       overridden or extended by subclasses.  For example, to redefine the
379       parameters as $param_foo.
380
381       See pop_arg_context() for the other side of this coin.
382
383   pop_arg_context OLD_ARG_CONTEXT
384       Restores OLD_ARG_CONTEXT after a target function has returned.  The
385       OLD_ARG_CONTEXT is the return value from the push_arg_context() call
386       just prior to the target function's call.
387
388       This method implements a default behavior.  It's intended to be
389       overridden or extended by subclasses.
390

SEE ALSO

392       POE::Stage, Devel::LexAlias, PadWalker, Catalyst::Controller::BindLex.
393
394   BUG TRACKER
395       https://rt.cpan.org/Dist/Display.html?Status=Active&Queue=Lexical-Persistence
396
397   REPOSITORY
398       http://github.com/rcaputo/lexical-persistence
399       http://gitorious.org/lexical-persistence
400
401   OTHER RESOURCES
402       http://search.cpan.org/dist/Lexical-Persistence/
403
405       Lexical::Persistence in copyright 2006-2013 by Rocco Caputo.  All
406       rights reserved.  Lexical::Persistence is free software.  It is
407       released under the same terms as Perl itself.
408

ACKNOWLEDGEMENTS

410       Thanks to Matt Trout and Yuval Kogman for lots of inspiration.  They
411       were the demon and the other demon sitting on my shoulders.
412
413       Nick Perez convinced me to make this a class rather than persist with
414       the original, functional design.  While Higher Order Perl is fun for
415       development, I have to say the move to OO was a good one.
416
417       Paul "LeoNerd" Evans contributed the compile() and eval() methods.
418
419       The South Florida Perl Mongers, especially Jeff Bisbee and Marlon
420       Bailey, for documentation feedback.
421
422       irc://irc.perl.org/poe for support and feedback.
423
424
425
426perl v5.34.0                      2021-07-22           Lexical::Persistence(3)
Impressum