.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Lexical::Persistence 3pm"
.TH Lexical::Persistence 3pm "2013-08-12" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Lexical::Persistence \- Persistent lexical variable values for arbitrary calls.
.SH "VERSION"
.IX Header "VERSION"
version 1.022
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&        #!/usr/bin/perl
\&
\&        use Lexical::Persistence;
\&
\&        my $persistence = Lexical::Persistence\->new();
\&        foreach my $number (qw(one two three four five)) {
\&                $persistence\->call(\e&target, number => $number);
\&        }
\&
\&        exit;
\&
\&        sub target {
\&                my $arg_number;   # Argument.
\&                my $narf_x++;     # Persistent.
\&                my $_i++;         # Dynamic.
\&                my $j++;          # Persistent.
\&
\&                print "arg_number = $arg_number\en";
\&                print "\etnarf_x = $narf_x\en";
\&                print "\et_i = $_i\en";
\&                print "\etj = $j\en";
\&        }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Lexical::Persistence does a few things, all related.  Note that all
the behaviors listed here are the defaults.  Subclasses can override
nearly every aspect of Lexical::Persistence's behavior.
.PP
Lexical::Persistence lets your code access persistent data through
lexical variables.  This example prints \*(L"some value\*(R" because the value
of \f(CW$x\fR persists in the \f(CW$lp\fR object between \fIsetter()\fR and \fIgetter()\fR.
.PP
.Vb 1
\&        use Lexical::Persistence;
\&
\&        my $lp = Lexical::Persistence\->new();
\&        $lp\->call(\e&setter);
\&        $lp\->call(\e&getter);
\&
\&        sub setter { my $x = "some value" }
\&        sub getter { print my $x, "\en" }
.Ve
.PP
Lexicals with leading underscores are not persistent.
.PP
By default, Lexical::Persistence supports accessing data from multiple
sources through the use of variable prefixes.  The \fIset_context()\fR
member sets each data source.  It takes a prefix name and a hash of
key/value pairs.  By default, the keys must have sigils representing
their variable types.
.PP
.Vb 1
\&        use Lexical::Persistence;
\&
\&        my $lp = Lexical::Persistence\->new();
\&        $lp\->set_context( pi => { \*(Aq$member\*(Aq => 3.141 } );
\&        $lp\->set_context( e => { \*(Aq@member\*(Aq => [ 2, \*(Aq.\*(Aq, 7, 1, 8 ] } );
\&        $lp\->set_context(
\&                animal => {
\&                        \*(Aq%member\*(Aq => { cat => "meow", dog => "woof" }
\&                }
\&        );
\&
\&        $lp\->call(\e&display);
\&
\&        sub display {
\&                my ($pi_member, @e_member, %animal_member);
\&
\&                print "pi = $pi_member\en";
\&                print "e = @e_member\en";
\&                while (my ($animal, $sound) = each %animal_member) {
\&                        print "The $animal goes... $sound!\en";
\&                }
\&        }
.Ve
.PP
And the corresponding output:
.PP
.Vb 4
\&        pi = 3.141
\&        e = 2 . 7 1 8
\&        The cat goes... meow!
\&        The dog goes... woof!
.Ve
.PP
By default, \fIcall()\fR takes a single subroutine reference and an optional
list of named arguments.  The arguments will be passed directly to the
called subroutine, but Lexical::Persistence also makes the values
available from the \*(L"arg\*(R" prefix.
.PP
.Vb 1
\&        use Lexical::Persistence;
\&
\&        my %animals = (
\&                snake => "hiss",
\&                plane => "I\*(Aqm Cartesian",
\&        );
\&
\&        my $lp = Lexical::Persistence\->new();
\&        while (my ($animal, $sound) = each %animals) {
\&                $lp\->call(\e&display, animal => $animal, sound => $sound);
\&        }
\&
\&        sub display {
\&                my ($arg_animal, $arg_sound);
\&                print "The $arg_animal goes... $arg_sound!\en";
\&        }
.Ve
.PP
And the corresponding output:
.PP
.Vb 2
\&        The plane goes... I\*(Aqm Cartesian!
\&        The snake goes... hiss!
.Ve
.PP
Sometimes you want to call functions normally.  The \fIwrap()\fR method will
wrap your function in a small thunk that does the \fIcall()\fR for you,
returning a coderef.
.PP
.Vb 1
\&        use Lexical::Persistence;
\&
\&        my $lp = Lexical::Persistence\->new();
\&        my $thunk = $lp\->wrap(\e&display);
\&
\&        $thunk\->(animal => "squirrel", sound => "nuts");
\&
\&        sub display {
\&                my ($arg_animal, $arg_sound);
\&                print "The $arg_animal goes... $arg_sound!\en";
\&        }
.Ve
.PP
And the corresponding output:
.PP
.Vb 1
\&        The squirrel goes... nuts!
.Ve
.PP
Prefixes are the characters leading up to the first underscore in a
lexical variable's name.  However, there's also a default context
named underscore.  It's literally \*(L"_\*(R" because the underscore is not
legal in a context name by default.  Variables without prefixes, or
with prefixes that have not been previously defined by \fIset_context()\fR,
are stored in that context.
.PP
The \fIget_context()\fR member returns a hash for a named context.  This
allows your code to manipulate the values within a persistent context.
.PP
.Vb 1
\&        use Lexical::Persistence;
\&
\&        my $lp = Lexical::Persistence\->new();
\&        $lp\->set_context(
\&                _ => {
\&                        \*(Aq@mind\*(Aq => [qw(My mind is going. I can feel it.)]
\&                }
\&        );
\&
\&        while (1) {
\&                $lp\->call(\e&display);
\&                my $mind = $lp\->get_context("_")\->{\*(Aq@mind\*(Aq};
\&                splice @$mind, rand(@$mind), 1;
\&                last unless @$mind;
\&        }
\&
\&        sub display {
\&                my @mind;
\&                print "@mind\en";
\&        }
.Ve
.PP
Displays something like:
.PP
.Vb 8
\&        My mind is going. I can feel it.
\&        My is going. I can feel it.
\&        My is going. I feel it.
\&        My going. I feel it.
\&        My going. I feel
\&        My I feel
\&        My I
\&        My
.Ve
.PP
It's possible to create multiple Lexical::Persistence objects, each
with a unique state.
.PP
.Vb 1
\&        use Lexical::Persistence;
\&
\&        my $lp_1 = Lexical::Persistence\->new();
\&        $lp_1\->set_context( _ => { \*(Aq$foo\*(Aq => "context 1\*(Aqs foo" } );
\&
\&        my $lp_2 = Lexical::Persistence\->new();
\&        $lp_2\->set_context( _ => { \*(Aq$foo\*(Aq => "the foo in context 2" } );
\&
\&        $lp_1\->call(\e&display);
\&        $lp_2\->call(\e&display);
\&
\&        sub display {
\&                print my $foo, "\en";
\&        }
.Ve
.PP
Gets you this output:
.PP
.Vb 2
\&        context 1\*(Aqs foo
\&        the foo in context 2
.Ve
.PP
You can also compile and execute perl code contained in plain strings in a
a lexical environment that already contains the persisted variables.
.PP
.Vb 1
\&        use Lexical::Persistence;
\&
\&        my $lp = Lexical::Persistence\->new();
\&
\&        $lp\->do( \*(Aqmy $message = "Hello, world" );
\&
\&        $lp\->do( \*(Aqprint "$message\en"\*(Aq );
.Ve
.PP
Which gives the output:
.PP
.Vb 1
\&        Hello, world
.Ve
.PP
If you come up with other fun uses, let us know.
.SS "new"
.IX Subsection "new"
Create a new lexical persistence object.  This object will store one
or more persistent contexts.  When called by this object, lexical
variables will take on the values kept in this object.
.SS "initialize_contexts"
.IX Subsection "initialize_contexts"
This method is called by \fInew()\fR to declare the initial contexts for a
new Lexical::Persistence object.  The default implementation declares
the default \*(L"_\*(R" context.
.PP
Override or extend it to create others as needed.
.SS "set_context \s-1NAME\s0, \s-1HASH\s0"
.IX Subsection "set_context NAME, HASH"
Store a context \s-1HASH\s0 within the persistence object, keyed on a \s-1NAME\s0.
Members of the context \s-1HASH\s0 are unprefixed versions of the lexicals
they'll persist, including the sigil.  For example, this \fIset_context()\fR
call declares a \*(L"request\*(R" context with predefined values for three
variables: \f(CW$request_foo\fR, \f(CW@request_foo\fR, and \f(CW%request_foo:\fR
.PP
.Vb 7
\&        $lp\->set_context(
\&                request => {
\&                        \*(Aq$foo\*(Aq => \*(Aqvalue of $request_foo\*(Aq,
\&                        \*(Aq@foo\*(Aq => [qw( value of @request_foo )],
\&                        \*(Aq%foo\*(Aq => { key => \*(Aqvalue of $request_foo{key}\*(Aq }
\&                }
\&        );
.Ve
.PP
See \fIparse_variable()\fR for information about how Lexical::Persistence
decides which context a lexical belongs to and how you can change
that.
.SS "get_context \s-1NAME\s0"
.IX Subsection "get_context NAME"
Returns a context hash associated with a particular context name.
Autovivifies the context if it doesn't already exist, so be careful
there.
.SS "call \s-1CODEREF\s0, \s-1ARGUMENT_LIST\s0"
.IX Subsection "call CODEREF, ARGUMENT_LIST"
Call \s-1CODEREF\s0 with lexical persistence and an optional \s-1ARGUMENT_LIST\s0,
consisting of name => value pairs.  Unlike with \fIset_context()\fR,
however, argument names do not need sigils.  This may change in the
future, however, as it's easy to access an argument with the wrong
variable type.
.PP
The \s-1ARGUMENT_LIST\s0 is passed to the called \s-1CODEREF\s0 through \f(CW@_\fR in the
usual way.  They're also available as \f(CW$arg_name\fR variables for
convenience.
.PP
See \fIpush_arg_context()\fR for information about how \f(CW$arg_name\fR works, and
what you can do to change that behavior.
.SS "invoke \s-1OBJECT\s0, \s-1METHOD\s0, \s-1ARGUMENT_LIST\s0"
.IX Subsection "invoke OBJECT, METHOD, ARGUMENT_LIST"
Invoke \s-1OBJECT\-\s0>\s-1METHOD\s0(\s-1ARGUMENT_LIST\s0) while maintaining state for the
\&\s-1METHOD\s0's lexical variables.  Written in terms of \fIcall()\fR, except that
it takes \s-1OBJECT\s0 and \s-1METHOD\s0 rather than \s-1CODEREF\s0.  See \fIcall()\fR for more
details.
.PP
May have issues with methods invoked via \s-1AUTOLOAD\s0, as \fIinvoke()\fR uses
\&\fIcan()\fR to find the method's \s-1CODEREF\s0 for \fIcall()\fR.
.SS "wrap \s-1CODEREF\s0"
.IX Subsection "wrap CODEREF"
Wrap a function or anonymous \s-1CODEREF\s0 so that it's transparently called
via \fIcall()\fR.  Returns a coderef which can be called directly.  Named
arguments to the call will automatically become available as \f(CW$arg_name\fR
lexicals within the called \s-1CODEREF\s0.
.PP
See \fIcall()\fR and \fIpush_arg_context()\fR for more details.
.SS "prepare \s-1CODE\s0"
.IX Subsection "prepare CODE"
Wrap a \s-1CODE\s0 string in a subroutine definition, and prepend
declarations for all the variables stored in the Lexical::Persistence
default context.  This avoids having to declare variables explicitly
in the code using 'my'.  Returns a new code string ready for Perl's
built-in \fIeval()\fR.  From there, a program may \f(CW$lp\fR\->\fIcall()\fR the code or
\&\f(CW$lp\fR\->\fIwrap()\fR it.
.PP
Also see \*(L"\fIcompile()\fR\*(R", which is a convenient wrapper for \fIprepare()\fR
and Perl's built-in \fIeval()\fR.
.PP
Also see \*(L"\fIdo()\fR\*(R", which is a convenient way to \fIprepare()\fR, \fIeval()\fR and
\&\fIcall()\fR in one step.
.SS "compile \s-1CODE\s0"
.IX Subsection "compile CODE"
\&\fIcompile()\fR is a convenience method to \fIprepare()\fR a \s-1CODE\s0 string, \fIeval()\fR
it, and then return the resulting coderef.  If it fails, it returns
false, and $@ will explain why.
.SS "do \s-1CODE\s0"
.IX Subsection "do CODE"
\&\fIdo()\fR is a convenience method to \fIcompile()\fR a \s-1CODE\s0 string and execute
it.  It returns the result of \s-1CODE\s0's execution, or it throws an
exception on failure.
.PP
This example prints the numbers 1 through 10.  Note, however, that
\&\fIdo()\fR compiles the same code each time.
.PP
.Vb 1
\&        use Lexical::Persistence;
\&
\&        my $lp = Lexical::Persistence\->new();
\&        $lp\->do(\*(Aqmy $count = 0\*(Aq);
\&        $lp\->do(\*(Aqprint ++$count, "\e\en"\*(Aq) for 1..10;
.Ve
.PP
Lexical declarations are preserved across \fIdo()\fR invocations, such as
with \f(CW$count\fR in the surrounding examples.  This behavior is part of
\&\fIprepare()\fR, which \fIdo()\fR uses via \fIcompile()\fR.
.PP
The previous example may be rewritten in terms of \fIcompile()\fR and \fIcall()\fR
to avoid recompiling code every iteration.  Lexical declarations are
preserved between \fIdo()\fR and \fIcompile()\fR as well:
.PP
.Vb 1
\&        use Lexical::Persistence;
\&
\&        my $lp = Lexical::Persistence\->new();
\&        $lp\->do(\*(Aqmy $count = 0\*(Aq);
\&        my $coderef = $lp\->compile(\*(Aqprint ++$count, "\e\en"\*(Aq);
\&        $lp\->call($coderef) for 1..10;
.Ve
.PP
\&\fIdo()\fR inherits some limitations from PadWalker's \fIpeek_sub()\fR.  For
instance, it cannot alias lexicals within \fIsub()\fR definitions in the
supplied \s-1CODE\s0 string.  However, Lexical::Persistence can do this with
careful use of \fIeval()\fR and some custom \s-1CODE\s0 preparation.
.SS "parse_variable \s-1VARIABLE_NAME\s0"
.IX Subsection "parse_variable VARIABLE_NAME"
This method determines whether \s-1VARIABLE_NAME\s0 should be persistent.  If
it should, \fIparse_variable()\fR will return three values: the variable's
sigil ('$', '@' or '%'), the context name in which the variable
persists (see \fIset_context()\fR), and the name of the member within that
context where the value is stored.  \fIparse_variable()\fR returns nothing
if \s-1VARIABLE_NAME\s0 should not be persistent.
.PP
\&\fIparse_variable()\fR also determines whether the member name includes its
sigil.  By default, the \*(L"arg\*(R" context is the only one with members
that have no sigils.  This is done to support the unadorned argument
names used by \fIcall()\fR.
.PP
This method implements a default behavior.  It's intended to be
overridden or extended by subclasses.
.SS "get_member_ref \s-1SIGIL\s0, \s-1CONTEXT\s0, \s-1MEMBER\s0"
.IX Subsection "get_member_ref SIGIL, CONTEXT, MEMBER"
This method fetches a reference to the named \s-1MEMBER\s0 of a particular
named \s-1CONTEXT\s0.  The returned value type will be governed by the given
\&\s-1SIGIL\s0.
.PP
Scalar values are stored internally as scalars to be consistent with
how most people store scalars.
.PP
The persistent value is created if it doesn't exist.  The initial
value is undef or empty, depending on its type.
.PP
This method implements a default behavior.  It's intended to be
overridden or extended by subclasses.
.SS "push_arg_context \s-1ARGUMENT_LIST\s0"
.IX Subsection "push_arg_context ARGUMENT_LIST"
Convert a named \s-1ARGUMENT_LIST\s0 into members of an argument context, and
call \fIset_context()\fR to declare that context.  This is how \f(CW$arg_foo\fR
variables are supported.  This method returns the previous context,
fetched by \fIget_context()\fR before the new context is set.
.PP
This method implements a default behavior.  It's intended to be
overridden or extended by subclasses.  For example, to redefine the
parameters as \f(CW$param_foo\fR.
.PP
See \fIpop_arg_context()\fR for the other side of this coin.
.SS "pop_arg_context \s-1OLD_ARG_CONTEXT\s0"
.IX Subsection "pop_arg_context OLD_ARG_CONTEXT"
Restores \s-1OLD_ARG_CONTEXT\s0 after a target function has returned.  The
\&\s-1OLD_ARG_CONTEXT\s0 is the return value from the \fIpush_arg_context()\fR call
just prior to the target function's call.
.PP
This method implements a default behavior.  It's intended to be
overridden or extended by subclasses.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
POE::Stage, Devel::LexAlias, PadWalker,
Catalyst::Controller::BindLex.
.SS "\s-1BUG\s0 \s-1TRACKER\s0"
.IX Subsection "BUG TRACKER"
https://rt.cpan.org/Dist/Display.html?Status=Active&Queue=Lexical\-Persistence
.SS "\s-1REPOSITORY\s0"
.IX Subsection "REPOSITORY"
http://github.com/rcaputo/lexical\-persistence
http://gitorious.org/lexical\-persistence
.SS "\s-1OTHER\s0 \s-1RESOURCES\s0"
.IX Subsection "OTHER RESOURCES"
http://search.cpan.org/dist/Lexical\-Persistence/
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Lexical::Persistence in copyright 2006\-2013 by Rocco Caputo.  All
rights reserved.  Lexical::Persistence is free software.  It is
released under the same terms as Perl itself.
.SH "ACKNOWLEDGEMENTS"
.IX Header "ACKNOWLEDGEMENTS"
Thanks to Matt Trout and Yuval Kogman for lots of inspiration.  They
were the demon and the other demon sitting on my shoulders.
.PP
Nick Perez convinced me to make this a class rather than persist with
the original, functional design.  While Higher Order Perl is fun for
development, I have to say the move to \s-1OO\s0 was a good one.
.PP
Paul \*(L"LeoNerd\*(R" Evans contributed the \fIcompile()\fR and \fIeval()\fR methods.
.PP
The South Florida Perl Mongers, especially Jeff Bisbee and Marlon
Bailey, for documentation feedback.
.PP
irc://irc.perl.org/poe for support and feedback.