---
name: "Parse::ePerl"
section: "3pm"
platform: "linux"
package: "eperl"
version: "2.2.15-1+deb13u1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Parse::ePerl"
---

# Parse::ePerl(3pm)

Perl interface to the ePerl parser

## 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)](/eperl/1.md) for more details about the stand-alone program). It directly uses the parser code from ePerl to translate a sprinkled 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)](/eperl/1.md) 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 sprinkled ePerl 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 sprinkled 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 sprinkled 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 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)](/eperl/1.md)

Web-References:

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