NAME¶
Parse::ePerl - Perl interface to the ePerl parser
SYNOPSIS¶
use Parse::ePerl;
$rc = Parse::ePerl::Preprocess($p);
$rc = Parse::ePerl::Translate($p);
$rc = Parse::ePerl::Precompile($p);
$rc = Parse::ePerl::Evaluate($p);
$rc = Parse::ePerl::Expand($p);
DESCRIPTION¶
Parse::ePerl is the Perl 5 interface package to the functionality of the ePerl
parser (see
eperl(1) for more details about the stand-alone program).
It directly uses the parser code from ePerl to translate a bristled script
into a plain Perl script and additionally provides functions to precompile
such scripts into P-code and evaluate those scripts to a buffer.
All functions are parameterized via a hash reference $p which provide the
necessary parameters. The result is a return code $rc which indicates success
(1) or failure (0).
PREPROCESSOR: $rc = Parse::ePerl::Preprocess($p)¶
This is the ePerl preprocessor which expands "#include" directives.
See
eperl(1) for more details.
Possible parameters for $p:
- Script
- Scalar holding the input script in source format.
- Result
- Reference to scalar receiving the resulting script in bristled Perl
format.
- BeginDelimiter
- Scalar specifying the begin delimiter. Default is
``"<:"''.
- EndDelimiter
- Scalar specifying the end delimiter. Default is
``":>"''.
- INC
- A reference to a list specifying include directories. Default is
"\@INC".
TRANSLATION: $rc = Parse::ePerl::Translate($p)¶
This is the actual ePerl parser, i.e. this function converts a bristled
ePerl-style script (provided in "$p-"{Script}> as a scalar) to a
plain Perl script. The resulting script is stored into a buffer provided via a
scalar reference in "$p-"{Result}>. The translation is directly
done by the original C function
Bristled2Plain() from ePerl, so the
resulting script is exactly the same as with the stand-alone program
eperl.
Possible parameters for $p:
- Script
- Scalar holding the input script in bristled format.
- Result
- Reference to scalar receiving the resulting script in plain Perl
format.
- BeginDelimiter
- Scalar specifying the begin delimiter. Default is
``"<:"''.
- EndDelimiter
- Scalar specifying the end delimiter. Default is
``":>"''.
- CaseDelimiters
- Boolean flag indicating if the delimiters are case-sensitive (1=default)
or case-insensitive (0).
Example: The following code
$script = <<'EOT';
foo
<: print "bar"; :>
quux
EOT
Parse::ePerl::Translate({
Script => $script,
Result => \$script,
});
translates the script in $script to the following plain Perl format:
print "foo\n";
print "bar"; print "\n";
print "quux\n";
COMPILATION: $rc = Parse::ePerl::Precompile($p);¶
This is an optional step between translation and evaluation where the plain Perl
script is compiled from ASCII representation to P-code (the internal Perl
bytecode). This step is used in rare cases only, for instance from within
Apache::ePerl(3) for caching purposes.
Possible parameters for $p:
- Script
- Scalar holding the input script in plain Perl format, usually the result
from a previous Parse::ePerl::Translate(3) call.
- Result
- Reference to scalar receiving the resulting code reference. This code can
be later directly used via the &$var construct or given to the
Parse::ePerl::Evaluate(3) function.
- Error
- Reference to scalar receiving possible error messages from the compilation
(e.g. syntax errors).
- Cwd
- Directory to switch to while precompiling the script.
- Name
- Name of the script for informal references inside error messages.
Example: The following code
Parse::ePerl::Precompile({
Script => $script,
Result => \$script,
});
translates the plain Perl code (see above) in $script to a code reference and
stores the reference again in $script. The code later can be either directly
used via &$script instead of "eval($script)" or passed to the
Parse::ePerl::Evaluate(3) function.
EVALUATION: $rc = Parse::ePerl::Evaluate($p);¶
Beside Parse::ePerl::
Translate(3) this is the second main function of
this package. It is intended to evaluate the result of
Parse::ePerl::
Translate(3) in a ePerl-like environment, i.e. this
function tries to emulate the runtime environment and behavior of the program
eperl. This actually means that it changes the current working
directory and evaluates the script while capturing data generated on
STDOUT/STDERR.
Possible parameters for $p:
- Script
- Scalar (standard case) or reference to scalar (compiled case) holding the
input script in plain Perl format or P-code, usually the result from a
previous Parse::ePerl::Translate(3) or
Parse::ePerl::Precompile(3) call.
- Result
- Reference to scalar receiving the resulting code reference.
- Error
- Reference to scalar receiving possible error messages from the evaluation
(e.g. runtime errors).
- ENV
- Hash containing the environment for %ENV which should be used while
evaluating the script.
- Cwd
- Directory to switch to while evaluating the script.
- Name
- Name of the script for informal references inside error messages.
Example: The following code
$script = <<'EOT';
print "foo\n";
print "bar"; print "\n";
print "quux\n";
EOT
Parse::ePerl::Evaluate({
Script => $script,
Result => \$script,
});
translates the script in $script to the following plain data:
foo
bar
quux
ONE-STEP EXPANSION: $rc = Parse::ePerl::Expand($p);¶
This function just combines, Parse::ePerl::
Translate(3) and
Parse::ePerl::Evaluate(3) into one step. The parameters in $p are the
union of the possible parameters for both functions. This is intended as a
high-level interface for Parse::ePerl.
AUTHOR¶
Ralf S. Engelschall
rse@engelschall.com
www.engelschall.com
SEE ALSO¶
eperl(1)
Web-References:
Perl: perl(1), http://www.perl.com/
ePerl: eperl(1), http://www.engelschall.com/sw/eperl/