view release on metacpan or  search on metacpan

README.mkdn  view on Meta::CPAN

## wrap CODEREF

Wrap a function or anonymous CODEREF so that it's transparently called
via call().  Returns a coderef which can be called directly.  Named
arguments to the call will automatically become available as $arg\_name
lexicals within the called CODEREF.

See call() and push\_arg\_context() for more details.

## prepare CODE

Wrap a CODE 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 eval().  From there, a program may $lp->call() the code or
$lp->wrap() it.

Also see ["compile()"](#compile()), which is a convenient wrapper for prepare()
and Perl's built-in eval().

Also see ["do()"](#do()), which is a convenient way to prepare(), eval() and
call() in one step.

## compile CODE

compile() is a convenience method to prepare() a CODE string, eval()
it, and then return the resulting coderef.  If it fails, it returns
false, and $@ will explain why.

## do CODE

do() is a convenience method to compile() a CODE string and execute
it.  It returns the result of CODE's execution, or it throws an
exception on failure.

This example prints the numbers 1 through 10.  Note, however, that
do() compiles the same code each time.

	use Lexical::Persistence;

	my $lp = Lexical::Persistence->new();
	$lp->do('my $count = 0');
	$lp->do('print ++$count, "\\n"') for 1..10;

Lexical declarations are preserved across do() invocations, such as
with $count in the surrounding examples.  This behavior is part of
prepare(), which do() uses via compile().

The previous example may be rewritten in terms of compile() and call()
to avoid recompiling code every iteration.  Lexical declarations are
preserved between do() and compile() as well:

	use Lexical::Persistence;

	my $lp = Lexical::Persistence->new();
	$lp->do('my $count = 0');
	my $coderef = $lp->compile('print ++$count, "\\n"');
	$lp->call($coderef) for 1..10;

do() inherits some limitations from PadWalker's peek\_sub().  For
instance, it cannot alias lexicals within sub() definitions in the
supplied CODE string.  However, Lexical::Persistence can do this with
careful use of eval() and some custom CODE preparation.

## parse\_variable VARIABLE\_NAME

This method determines whether VARIABLE\_NAME should be persistent.  If
it should, parse\_variable() will return three values: the variable's
sigil ('$', '@' or '%'), the context name in which the variable
persists (see set\_context()), and the name of the member within that
context where the value is stored.  parse\_variable() returns nothing
if VARIABLE\_NAME should not be persistent.

parse\_variable() also determines whether the member name includes its
sigil.  By default, the "arg" context is the only one with members
that have no sigils.  This is done to support the unadorned argument
names used by call().

This method implements a default behavior.  It's intended to be
overridden or extended by subclasses.

## get\_member\_ref SIGIL, CONTEXT, MEMBER

This method fetches a reference to the named MEMBER of a particular
named CONTEXT.  The returned value type will be governed by the given
SIGIL.

Scalar values are stored internally as scalars to be consistent with
how most people store scalars.

The persistent value is created if it doesn't exist.  The initial
value is undef or empty, depending on its type.

This method implements a default behavior.  It's intended to be
overridden or extended by subclasses.

## push\_arg\_context ARGUMENT\_LIST

Convert a named ARGUMENT\_LIST into members of an argument context, and
call set\_context() to declare that context.  This is how $arg\_foo
variables are supported.  This method returns the previous context,
fetched by get\_context() before the new context is set.

This method implements a default behavior.  It's intended to be
overridden or extended by subclasses.  For example, to redefine the
parameters as $param\_foo.

See pop\_arg\_context() for the other side of this coin.

## pop\_arg\_context OLD\_ARG\_CONTEXT

Restores OLD\_ARG\_CONTEXT after a target function has returned.  The
OLD\_ARG\_CONTEXT is the return value from the push\_arg\_context() call
just prior to the target function's call.

This method implements a default behavior.  It's intended to be
overridden or extended by subclasses.

# SEE ALSO

[POE::Stage](http://search.cpan.org/perldoc?POE::Stage), [Devel::LexAlias](http://search.cpan.org/perldoc?Devel::LexAlias), [PadWalker](http://search.cpan.org/perldoc?PadWalker),
[Catalyst::Controller::BindLex](http://search.cpan.org/perldoc?Catalyst::Controller::BindLex).

## BUG TRACKER

https://rt.cpan.org/Dist/Display.html?Status=Active&Queue=Lexical-Persistence

## REPOSITORY

http://github.com/rcaputo/lexical-persistence
http://gitorious.org/lexical-persistence

## OTHER RESOURCES

http://search.cpan.org/dist/Lexical-Persistence/

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

# ACKNOWLEDGEMENTS

Thanks to Matt Trout and Yuval Kogman for lots of inspiration.  They
were the demon and the other demon sitting on my shoulders.

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 OO was a good one.

Paul "LeoNerd" Evans contributed the compile() and eval() methods.

The South Florida Perl Mongers, especially Jeff Bisbee and Marlon
Bailey, for documentation feedback.

irc://irc.perl.org/poe for support and feedback.