What is it?

This tool allows you to expand perl statements inside of text files. It was originally written in C by Ralf S. Engelschall. I rewrote in Perl in a fraction of the space. The actual filter program is something like 80 lines, but adding compatibility and documentation puffed it up to 1400 or so - all in one script.

See the Quick Reference for a plethora of simple examples.

For a real example, the home index for MarginalHacks is actually generated from eperl source


This software is essentially free, but please read my payment spiel
Please read the full license


ePerl reads a text file and expands any perl code it sees between some simple delimiters (<: and :> by default). Here is a simple example - see the docs for more information.
      Here is the start of a text file

      <: for($i=0; $i<5; $i++) { :>//

        I can count to <:=$i:>

      <: } :>//

      Here is the end.
The output will be:
      Here is the start of a text file
        I can count to 0
        I can count to 1
        I can count to 2
        I can count to 3
        I can count to 4
      Here is the end.
Not that exciting in this simple case. Here are some important points:
  1. The perl blocks can be split up with text (such as the begin and end of the above example)
  2. The perl blocks can contain any valid perl, such as use of perl modules, reading of files, system calls, ...

Why a Rewrite?

The original ePerl program had the perl interpreter built in. This required a huge download, installation and executable. This also meant that ePerl might use a different version of perl (and perl libraries) than you had locally installed.

I wanted to make some changes to ePerl, and since ePerl mostly did text munging, I realized it should be written in Perl itself.

While it is slower, it's much easier to deal with and modify/play with. Furthermore, development on the original ePerl ceased back in 1998, and is only tested up to Perl 5.004, whereas the Marginal Hacks version of ePerl should continue to work with future versions of perl.

It also helps in specific situations where the original is problematic, such as this guy:

I found your ePerl implementation very useful. Thanks for it. I'm developing a Finite Element Code (PETSc-FEM) and I use ePerl as the basic preprocessor of the user input data file. But previously I had to tell the users to install the ePerl packages, whereas now I can include your scripts in the distribution.
Your eperl implementation resolved another problem to me, since before I couldn't compile the eperl package, and the eperl binaries are sometimes not synchronized with the Perl installation, so that the eperl binary can't load some packages (like POSIX for instance).
- Mario Alberto Storti


There are two versions available, full and minimal.

The full version tries to remain as compatible to the C version of ePerl as possible. The minimal version is much smaller and more efficient, so if efficiency is more important than options, than go for the minimal version. (Amongst other things, the minimal version does *not* support CGI mode).


There are a few forms of documentation:


This perl version of ePerl has a few incompatibilities with the C version. Here is the list as of version 1.14, see the top of the perl script for up-to-date information:


  1. Can't do shebang (#!eperl) with some shells (such as tcsh) To fix this you just need a wrapper to eperl in C:
          main(int argc, char **argv) { execv("/path/to/",argv); }
  2. Also, no SETUID, though a setuid wrapper can fix this as well.
  3. exit codes ($?) in perl are 8 bits, real exit codes are 16 bits, so all exit codes are mod 255. Worst of all, this means exit(256*int) will seem like no error returned, and exit(-1) looks like exit(255);
  4. Doesn't have embedded gifs due to size/copyright (/url/to/nph-eperl/logo.gif and powered.gif)
  5. No module ( support at all yet.
Slight differences when not using --strict flag:
  1. In the normal case (plain filtered mode) we don't read in all of STDERR and STDOUT because this is inefficient. See --watch_stderr
  2. Environment variables are only set in CGI mode
Bugs fixed over the original ePerl:
  1. The original eperl ignores -o in CGI modes. This eperl doesn't.
  2. #sinclude is truly safe
  4. You can use #include of relative paths in stdin scripts ('eperl -P -')
Added features:
  1. You can specify multiple files to parse
  2. New options (see usage)


  1. Perl, which kicks ass


It's just a perl script. No install required.

Revision History:



David Ljung Madison,
Wrote this version (the 'perl' ePerl)
Ralf S. Engelschall,
For writing the software in the first place (the 'C' ePerl)


You bet.