ePerl(3pm)

📦
version 2.2.16 · 6 versions
, in debian trixie, ubuntu resolute

💖 ePerl 💖

okay bestie, gather round, because we're about to get into ePerl(3pm) — that's the User Contributed Perl Documentation version, and no, this is not the stand-alone program, this is the Perl module that does the thing. sit down, hydrate, let's go 🫶

✨ NAME ✨

Parse::ePerl</purl> — the Perl interface to the ePerl parser. that's it, that's the name, and honestly? iconic. 💅

🌸 SYNOPSIS 🌸

like, here's the whole vibe in one block. copy it, don't overthink it:

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

five functions, five little besties, each one doing a very specific job. slay. ✨

💜 DESCRIPTION 💜

so Parse::ePerl is the Perl 5 interface package to the functionality of the ePerl parser — and if you want the whole lore about the stand-alone program itself, go read eperl(1), it's right there. 📖

the way this works is: it directly uses the parser code from ePerl to translate a sprinkled script into a plain Perl script. and then, because it's generous, it also provides functions to precompile such scripts into P-code and evaluate those scripts to a buffer. multi-talented. main character energy fr fr. 👑

every single function is parameterized via a hash reference $p, which provides the necessary parameters. and you get back a return code $rc that indicates success (1) or failure (0). no in-between, no maybe, it's giving binary. 💀

🧚 PREPROCESSOR: $rc = Parse::ePerl::Preprocess($p)

this is the ePerl preprocessor, and its whole personality is expanding "#include" directives. that's the job. see eperl(1) for more details, bestie. 🌸

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)

okay THIS one is the actual ePerl parser. like, the real deal. this function converts a sprinkled ePerl-style script (which you hand over in "$p-"{Script}> as a scalar) into a plain Perl script. the resulting script gets stored into a buffer provided via a scalar reference in "$p-"{Result}>. and here's the part that's lowkey wild: 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. no drift, no divergence, no cap. 🔥

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

look at that glow-up. from sprinkled to plain. 💅✨

🎀 COMPILATION: $rc = Parse::ePerl::Precompile($p);

this is an optional step between translation and evaluation, where the plain Perl script gets compiled from ASCII representation to P-code (that's the internal Perl bytecode, iykyk). this step is used in rare cases only, for instance from within for caching purposes. so like, niche but powerful. 🧚

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. and what does that actually mean? it means it changes the current working directory and evaluates the script while capturing data generated on STDOUT/STDERR. so heads up bestie, the cwd is moving. 😭

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

ate. no crumbs. 🍓

⭐ ONE-STEP EXPANSION: $rc = Parse::ePerl::Expand($p);

this function just combines, Parse::ePerl::Translate(3) and Parse::ePerl::Evaluate(3) into one step. yes, it literally just smashes them together and honestly? we love efficiency. 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 👑

this masterpiece was brought to you by:

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

absolute legend behavior. 💜

🔥 SEE ALSO 🔥

Web-References:

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

go read the links bestie, they're right there. 🦋

and that's the whole page!! 🎀 this was perl v5.40.1, dated 2025-09-09, and you're officially done reading ePerl(3pm). go forth and sprinkle some scripts, you've got this. periodt. 💖✨

📦 where this page comes from