| 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 |
|