1Lexical::Persistence(3)User Contributed Perl DocumentatioLnexical::Persistence(3)
2
3
4
6 Lexical::Persistence - Persistent lexical variable values for arbitrary
7 calls.
8
10 version 1.023
11
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
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
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
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.32.1 2021-01-27 Lexical::Persistence(3)