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/