Parse::ePerl - Perl interface to the ePerl parser

  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);

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 CW$p which provide the necessary parameters. The result is a return code CW$rc which indicates success (1) or failure (0). This is the ePerl preprocessor which expands CW#include directives. See eperl(1) for more details.

Possible parameters for CW$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 ``CW<:''.

EndDelimiter

Scalar specifying the end delimiter. Default is ``CW:>''.

INC

A reference to a list specifying include directories. Default is CW\@INC. This is the actual ePerl parser, i.e. this function converts a bristled ePerl-style script (provided in CW$p-{Script}> as a scalar) to a plain Perl script. The resulting script is stored into a buffer provided via a scalar reference in CW$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 CW$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 ``CW<:''.

EndDelimiter

Scalar specifying the end delimiter. Default is ``CW:>''.

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 CW$script to the following plain Perl format:

  print "foo\n";
  print "bar"; print "\n";
  print "quux\n";

Possible parameters for CW$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 CW&$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 CW$script to a code reference and stores the reference again in CW$script. The code later can be either directly used via CW&$script instead of CWeval($script) or passed to the Parse::ePerl::Evaluate(3) function. 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 CW$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 CW%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 CW$script to the following plain data:

  foo
  bar
  quux

 Ralf S. Engelschall
 rse@engelschall.com
 www.engelschall.com

eperl(1)

Web-References:

  Perl:  perl(1),  http://www.perl.com/
  ePerl: eperl(1), http://www.engelschall.com/sw/eperl/