Debian Codegraph @

README

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