.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" 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" ''
.    ds C`
.    ds C'
'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 >0, 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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "ePerl 3pm"
.TH ePerl 3pm "2020-11-08" "perl v5.32.0" "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"
Parse::ePerl \- Perl interface to the ePerl parser
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Parse::ePerl is the Perl 5 interface package to the functionality of the ePerl
parser (see \fBeperl\fR\|(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.
.PP
All functions are parameterized via a hash reference \f(CW$p\fR which provide the
necessary parameters. The result is a return code \f(CW$rc\fR which indicates
success (1) or failure (0).
.SS "\fB\s-1PREPROCESSOR:\s0 \fP\f(CB$rc\fP\fB = Parse::ePerl::Preprocess($p)\fP"
.IX Subsection "PREPROCESSOR: $rc = Parse::ePerl::Preprocess($p)"
This is the ePerl preprocessor which expands \f(CW\*(C`#include\*(C'\fR directives.
See \fBeperl\fR\|(1) for more details.
.PP
Possible parameters for \f(CW$p\fR:
.IP "\fIScript\fR" 4
.IX Item "Script"
Scalar holding the input script in source format.
.IP "\fIResult\fR" 4
.IX Item "Result"
Reference to scalar receiving the resulting script in bristled Perl format.
.IP "\fIBeginDelimiter\fR" 4
.IX Item "BeginDelimiter"
Scalar specifying the begin delimiter.  Default is ``\f(CW\*(C`<:\*(C'\fR''.
.IP "\fIEndDelimiter\fR" 4
.IX Item "EndDelimiter"
Scalar specifying the end delimiter.  Default is ``\f(CW\*(C`:>\*(C'\fR''.
.IP "\fI\s-1INC\s0\fR" 4
.IX Item "INC"
A reference to a list specifying include directories. Default is \f(CW\*(C`\e@INC\*(C'\fR.
.SS "\fB\s-1TRANSLATION:\s0 \fP\f(CB$rc\fP\fB = Parse::ePerl::Translate($p)\fP"
.IX Subsection "TRANSLATION: $rc = Parse::ePerl::Translate($p)"
This is the actual ePerl parser, i.e. this function converts a bristled
ePerl-style script (provided in \f(CW\*(C`$p\-\*(C'\fR{Script}> as a scalar) to a plain Perl
script. The resulting script is stored into a buffer provided via a scalar
reference in \f(CW\*(C`$p\-\*(C'\fR{Result}>. The translation is directly done by the original
C function \fBBristled2Plain()\fR from ePerl, so the resulting script is exactly the
same as with the stand-alone program \fIeperl\fR.
.PP
Possible parameters for \f(CW$p\fR:
.IP "\fIScript\fR" 4
.IX Item "Script"
Scalar holding the input script in bristled format.
.IP "\fIResult\fR" 4
.IX Item "Result"
Reference to scalar receiving the resulting script in plain Perl format.
.IP "\fIBeginDelimiter\fR" 4
.IX Item "BeginDelimiter"
Scalar specifying the begin delimiter.  Default is ``\f(CW\*(C`<:\*(C'\fR''.
.IP "\fIEndDelimiter\fR" 4
.IX Item "EndDelimiter"
Scalar specifying the end delimiter.  Default is ``\f(CW\*(C`:>\*(C'\fR''.
.IP "\fICaseDelimiters\fR" 4
.IX Item "CaseDelimiters"
Boolean flag indicating if the delimiters are case-sensitive (1=default) or
case-insensitive (0).
.PP
Example: The following code
.PP
.Vb 5
\&  $script = <<\*(AqEOT\*(Aq;
\&  foo
\&  <: print "bar"; :>
\&  quux
\&  EOT
\&  
\&  Parse::ePerl::Translate({
\&      Script => $script,
\&      Result => \e$script,
\&  });
.Ve
.PP
translates the script in \f(CW$script\fR to the following plain Perl format:
.PP
.Vb 3
\&  print "foo\en";
\&  print "bar"; print "\en";
\&  print "quux\en";
.Ve
.SS "\fB\s-1COMPILATION:\s0 \fP\f(CB$rc\fP\fB = Parse::ePerl::Precompile($p);\fP"
.IX Subsection "COMPILATION: $rc = Parse::ePerl::Precompile($p);"
This is an optional step between translation and evaluation where the plain
Perl script is compiled from \s-1ASCII\s0 representation to P\-code (the internal Perl
bytecode). This step is used in rare cases only, for instance from within
\&\fBApache::ePerl\fR\|(3) for caching purposes.
.PP
Possible parameters for \f(CW$p\fR:
.IP "\fIScript\fR" 4
.IX Item "Script"
Scalar holding the input script in plain Perl format, usually the result from
a previous \fBParse::ePerl::Translate\fR\|(3) call.
.IP "\fIResult\fR" 4
.IX Item "Result"
Reference to scalar receiving the resulting code reference. This code can be
later directly used via the \f(CW&$var\fR construct or given to the
\&\fBParse::ePerl::Evaluate\fR\|(3) function.
.IP "\fIError\fR" 4
.IX Item "Error"
Reference to scalar receiving possible error messages from the compilation
(e.g.  syntax errors).
.IP "\fICwd\fR" 4
.IX Item "Cwd"
Directory to switch to while precompiling the script.
.IP "\fIName\fR" 4
.IX Item "Name"
Name of the script for informal references inside error messages.
.PP
Example: The following code
.PP
.Vb 4
\&  Parse::ePerl::Precompile({
\&      Script => $script,
\&      Result => \e$script,
\&  });
.Ve
.PP
translates the plain Perl code (see above) in \f(CW$script\fR to a code reference
and stores the reference again in \f(CW$script\fR. The code later can be either
directly used via \f(CW&$script\fR instead of \f(CW\*(C`eval($script)\*(C'\fR or passed to the
\&\fBParse::ePerl::Evaluate\fR\|(3) function.
.SS "\fB\s-1EVALUATION:\s0 \fP\f(CB$rc\fP\fB = Parse::ePerl::Evaluate($p);\fP"
.IX Subsection "EVALUATION: $rc = Parse::ePerl::Evaluate($p);"
Beside \fBParse::ePerl::Translate\fR\|(3) this is the second main function of this
package. It is intended to evaluate the result of \fBParse::ePerl::Translate\fR\|(3)
in a ePerl-like environment, i.e. this function tries to emulate the runtime
environment and behavior of the program \fIeperl\fR. This actually means that it
changes the current working directory and evaluates the script while capturing
data generated on \s-1STDOUT/STDERR.\s0
.PP
Possible parameters for \f(CW$p\fR:
.IP "\fIScript\fR" 4
.IX Item "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 \fBParse::ePerl::Translate\fR\|(3) or \fBParse::ePerl::Precompile\fR\|(3) call.
.IP "\fIResult\fR" 4
.IX Item "Result"
Reference to scalar receiving the resulting code reference.
.IP "\fIError\fR" 4
.IX Item "Error"
Reference to scalar receiving possible error messages from the evaluation
(e.g. runtime errors).
.IP "\fI\s-1ENV\s0\fR" 4
.IX Item "ENV"
Hash containing the environment for \f(CW%ENV\fR which should be used while
evaluating the script.
.IP "\fICwd\fR" 4
.IX Item "Cwd"
Directory to switch to while evaluating the script.
.IP "\fIName\fR" 4
.IX Item "Name"
Name of the script for informal references inside error messages.
.PP
Example: The following code
.PP
.Vb 5
\&  $script = <<\*(AqEOT\*(Aq;
\&  print "foo\en";
\&  print "bar"; print "\en";
\&  print "quux\en";
\&  EOT
\&
\&  Parse::ePerl::Evaluate({
\&      Script => $script,
\&      Result => \e$script,
\&  });
.Ve
.PP
translates the script in \f(CW$script\fR to the following plain data:
.PP
.Vb 3
\&  foo
\&  bar
\&  quux
.Ve
.SS "\fBONE-STEP \s-1EXPANSION:\s0 \fP\f(CB$rc\fP\fB = Parse::ePerl::Expand($p);\fP"
.IX Subsection "ONE-STEP EXPANSION: $rc = Parse::ePerl::Expand($p);"
This function just combines, \fBParse::ePerl::Translate\fR\|(3) and
\&\fBParse::ePerl::Evaluate\fR\|(3) into one step. The parameters in \f(CW$p\fR are the union
of the possible parameters for both functions. This is intended as a
high-level interface for Parse::ePerl.
.SH "AUTHOR"
.IX Header "AUTHOR"
.Vb 3
\& Ralf S. Engelschall
\& rse@engelschall.com
\& www.engelschall.com
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBeperl\fR\|(1)
.PP
Web-References:
.PP
.Vb 2
\&  Perl:  perl(1),  http://www.perl.com/
\&  ePerl: eperl(1), http://www.engelschall.com/sw/eperl/
.Ve