CONTENTS

This module provides the capability to parse a string at runtime as Perl
source code, so that the resulting compiled code can be later executed.
This is part of the job of the string form of the eval operator,
but in this module it is separated out from the other jobs of eval.
Parsing of Perl code is generally influenced by its lexical context,
and this module provides some explicit control over this process, by
reifying lexical environments as Perl objects.

Perls built-in eval operator (in string form) actually performs four
distinct jobs: capture lexical environment, parse Perl source, execute
code, and catch exceptions. This module allows each of these four jobs
to be performed separately, so they can then be combined in ways that
eval doesnt permit. Capturing lexical environment is performed
using a special operator supplied by this module. Parsing Perl source
is performed by a function supplied by this module. Executing code is
adequately handled by Perls native mechanisms for calling functions
through references. Finally, exception catching is handled by the block
form of eval.

This operator generates a Parse::Perl::Environment object which
encapsulates the lexical environment at the site where the operator
is used. It evaluates to a reference to the environment object.
The environment object encapsulates the lexical variables that are
available at this site, the lexical warning status, and the effects of
all other lexical pragmata.

This operator captures all the lexical variables that are visible
at the point where it is used. This can result in surprisingly long
lifetimes for variables in enclosing scopes. This aspect of this operator
is unlike eval, which only captures those variables that are referenced
in the directly enclosing function, leading to Variable not available
warnings.

This operator should be used through bareword function call syntax, as if
it were a function. However, it cannot otherwise be called as a function
in the normal manner. Attempting to take a reference to it will result
in a code reference that does not have any of the behaviour described.

ENVIRONMENT must be a reference to a Parse::Perl::Environment
object, which encapsulates a lexical environment. SOURCE must be
a string. SOURCE is parsed as a block of Perl code (specifically,
as if it were the body of a function), in the lexical environment
represented by ENVIRONMENT. If there is any error in compilation,
a suitable exception is thrown. If there is no error, the compiled code
is returned, in the form of a reference to a Perl function. The code
represented by SOURCE can then be executed by calling the function.