1Lexical::Persistence(3)User Contributed Perl DocumentatioLnexical::Persistence(3)
2
6 Lexical::Persistence - Persistent lexical variable values for arbitrary
7 calls.
8
10 version 1.023
11
13 #!/usr/bin/perl
14 use Lexical::Persistence;
16 my $persistence = Lexical::Persistence->new();
18 foreach my $number (qw(one two three four five)) {
19 $persistence->call(\&target, number => $number);
20 }
21 exit;
23 sub target {
25 my $arg_number; # Argument.
26 my $narf_x++; # Persistent.
27 my $_i++; # Dynamic.
28 my $j++; # Persistent.
29 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 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 use Lexical::Persistence;
46 my $lp = Lexical::Persistence->new();
48 $lp->call(\&setter);
49 $lp->call(\&getter);
50 sub setter { my $x = "some value" }
52 sub getter { print my $x, "\n" }
53 Lexicals with leading underscores are not persistent.
55 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 use Lexical::Persistence;
63 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 $lp->call(\&display);
74 sub display {
76 my ($pi_member, @e_member, %animal_member);
77 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 And the corresponding output:
86 pi = 3.141
88 e = 2 . 7 1 8
89 The cat goes... meow!
90 The dog goes... woof!
91 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 use Lexical::Persistence;
98 my %animals = (
100 snake => "hiss",
101 plane => "I'm Cartesian",
102 );
103 my $lp = Lexical::Persistence->new();
105 while (my ($animal, $sound) = each %animals) {
106 $lp->call(\&display, animal => $animal, sound => $sound);
107 }
108 sub display {
110 my ($arg_animal, $arg_sound);
111 print "The $arg_animal goes... $arg_sound!\n";
112 }
113 And the corresponding output:
115 The plane goes... I'm Cartesian!
117 The snake goes... hiss!
118 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 use Lexical::Persistence;
124 my $lp = Lexical::Persistence->new();
126 my $thunk = $lp->wrap(\&display);
127 $thunk->(animal => "squirrel", sound => "nuts");
129 sub display {
131 my ($arg_animal, $arg_sound);
132 print "The $arg_animal goes... $arg_sound!\n";
133 }
134 And the corresponding output:
136 The squirrel goes... nuts!
138 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 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 use Lexical::Persistence;
150 my $lp = Lexical::Persistence->new();
152 $lp->set_context(
153 _ => {
154 '@mind' => [qw(My mind is going. I can feel it.)]
155 }
156 );
157 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 sub display {
166 my @mind;
167 print "@mind\n";
168 }
169 Displays something like:
171 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 It's possible to create multiple Lexical::Persistence objects, each
182 with a unique state.
183 use Lexical::Persistence;
185 my $lp_1 = Lexical::Persistence->new();
187 $lp_1->set_context( _ => { '$foo' => "context 1's foo" } );
188 my $lp_2 = Lexical::Persistence->new();
190 $lp_2->set_context( _ => { '$foo' => "the foo in context 2" } );
191 $lp_1->call(\&display);
193 $lp_2->call(\&display);
194 sub display {
196 print my $foo, "\n";
197 }
198 Gets you this output:
200 context 1's foo
202 the foo in context 2
203 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 use Lexical::Persistence;
209 my $lp = Lexical::Persistence->new();
211 $lp->do( 'my $message = "Hello, world" );
213 $lp->do( 'print "$message\n"' );
215 Which gives the output:
217 Hello, world
219 If you come up with other fun uses, let us know.
221 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 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 Override or extend it to create others as needed.
233 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 $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 See parse_variable() for information about how Lexical::Persistence
250 decides which context a lexical belongs to and how you can change that.
251 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 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 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 See push_arg_context() for information about how $arg_name works, and
269 what you can do to change that behavior.
270 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 May have issues with methods invoked via AUTOLOAD, as invoke() uses
278 can() to find the method's CODEREF for call().
279 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 See call() and push_arg_context() for more details.
287 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 Also see "compile()", which is a convenient wrapper for prepare() and
297 Perl's built-in eval().
298 Also see "do()", which is a convenient way to prepare(), eval() and
300 call() in one step.
301 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 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 This example prints the numbers 1 through 10. Note, however, that do()
313 compiles the same code each time.
314 use Lexical::Persistence;
316 my $lp = Lexical::Persistence->new();
318 $lp->do('my $count = 0');
319 $lp->do('print ++$count, "\\n"') for 1..10;
320 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 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 use Lexical::Persistence;
330 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 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 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 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 This method implements a default behavior. It's intended to be
355 overridden or extended by subclasses.
356 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 Scalar values are stored internally as scalars to be consistent with
363 how most people store scalars.
364 The persistent value is created if it doesn't exist. The initial value
366 is undef or empty, depending on its type.
367 This method implements a default behavior. It's intended to be
369 overridden or extended by subclasses.
370 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 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 See pop_arg_context() for the other side of this coin.
382 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 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 BUG TRACKER
395 https://rt.cpan.org/Dist/Display.html?Status=Active&Queue=Lexical-Persistence
396 REPOSITORY
398 http://github.com/rcaputo/lexical-persistence
399 http://gitorious.org/lexical-persistence
400 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 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 Paul "LeoNerd" Evans contributed the compile() and eval() methods.
418 The South Florida Perl Mongers, especially Jeff Bisbee and Marlon
420 Bailey, for documentation feedback.
421 irc://irc.perl.org/poe for support and feedback.
423perl v5.36.0 2022-07-22 Lexical::Persistence(3)