ePerl(3) User Contributed Perl Documentation ePerl(3)NAMEParse::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);
DESCRIPTIONParse::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 ALSOeperl(1)
Web-References:
Perl: perl(1), http://www.perl.com/
ePerl: eperl(1), http://www.engelschall.com/sw/eperl/
perl v5.14.0 2011-06-17 ePerl(3)
