NAME

ePerl - Embedded Perl 5 Language

VERSION

@V@

SYNOPSIS

eperl [-m f|c|n] [-b begin_delimiter] [-e end_delimiter] [-D name=value] [-E name=value] [-o outputfile] [-k] [-x] [-c] [-r] [-l] [inputfile]

eperl [-v] [-V]

DESCRIPTION

Abstract

ePerl interprets an ASCII file bristled with Perl 5 program statements by evaluating the Perl 5 code while passing through the plain ASCII data. It can operate both as a standard Unix filter for file generation and as a Webserver scripting language for dynamic HTML page programming.

Introduction

The eperl program is the Embedded Perl 5 Language. This really is a full-featured Perl 5 interpreter, but with a different calling environment and source file format then the default Perl interpreter (the executable perl). It is designed for ASCII file generation with the philosophy of embedding the Perl 5 program code into the ASCII data instead of the usual way where you embed the ASCII data into a Perl 5 program.

Instead of writing a generation program with code like

print "foo bar\n";
print "baz quux\n";
for ($i = 0; $i < 10; $i++) { print "foo #${i}\n"; }
print "foo bar\n";
print "baz quux\n";

you now code it as

foo bar
baz quux
<: for ($i = 0; $i < 10; $i++) { print "foo #${i}\n"; } :>
foo bar
baz quux

Intention

ePerl is simply a glue code which combines the programming power of the Perl 5 interpreter with a tricky embedding technique. The embedding trick is: ePerl itself only converts the source file into a valid Perl script which then gets entirely evaluated by only one internal instance of the Perl 5 interpreter. To archieve this, ePerl translates all plain code into (escaped) Perl 5 print constructs while passing through all embedded native Perl 5 code.

Due to the nature of such bristled code, ePerl is really the better attempt when the generated ASCII data contains really more static as dynamic data. Or in other words: Use ePerl if you want to keep the most of the ASCII data in plain format while just programming some bristled stuff. Do not use it when generating pure dynamic data. There it brings no advantage to an ordinary program code.

ePerl was actually designed to be used as a webserver scripting-language for HTML pages. Here you have the typical case that 90% of the data consists of pure static HTML tags and plain ASCII while the remaining 10% are actually dynamically generated stuff.

Usage

The eperl program can be used in three different ways of calling:

Stand-Alone Unix compliant Filter

This is the basic operation when used as a generation tool from the Unix shell or from within other tools:

$ eperl [options] - < inputfile > outputfile
$ eperl [options] inputfile > outputfile
$ eperl [options] -o outputfile inputfile

Use this to take advantage of Perl's programming power for generating complicated data.

Shebang NPH-CGI/1.1 Script

Here ePerl is used in conjunction with the Unix shebang magic technique to directly transform a HTML file into a CGI/1.1 script. First just prefix the file with the following (shebang-)line:

#!@prefix@/bin/eperl [options]

Then rename it from file.html to file.cgi and set its execution bit via

$ mv file.html file.cgi
$ chmod a+rx file.cgi

Now when the script file.cgi is run by the webserver it actually displays its HTML data. Usually (because up to now the CGI script had no advantage over the plain HTML file) you bristle the file with Perl 5 blocks where you need dynamic content.

Notice that usually this does only run file.cgi as pure CGI/1.1 compliant program and not as Non-Parsed-Header (NPH) CGI/1.1 one.

NPH-CGI/1.1 compliant Server-Side Scripting Language

Modern webservers (like Apache) provide the ability to integrate server-side scripting languages in a really seemless manner. There you can force all files with a specific extension (or associated MIME-type) to be on-the-fly filtered by a script. Use this feature to use ePerl as a fully integrated server-side scripting language.

For Apache you can transform any HTML page into a ePerl source file by just renaming it from file.html to file.phtml while setting up the following directives in the httpd.conf file

AddType      application/x-httpd-eperl  .phtml .eperl .epl
Action       application/x-httpd-eperl  /internal/cgi/nph-eperl
ScriptAlias  /internal/cgi              /path/to/apache/cgi-bin

and creating a symlink to the eperl program:

$ ln -s @prefix@/bin/eperl /path/to/apache/cgi-bin/nph-eperl

OPTIONS

-m f|c|n

This forces ePerl to act in a specific runtime mode. Either as a stand-alone filter (-mf), where no HTTP response headers are printed and errors are displayed without surrounding HTML code. This mode is choosen per default when no CGI/1.1 variables are set in the environment.

Or as a CGI/1.1 (-mc) compliant program, where HTTP response headers are printed and errors are encapsulated in HTML code. In this mode only a few specific HTTP headers can be generated like Location. Because these headers are post-processed by the webserver. This mode is automatically choosen when CGI/1.1 variables exists in the environment and the script filename does not begin with the NPH prefix ``nph-''.

Additionally -mn forces the NPH-CGI/1.1 mode which is similar to CGI but here No-Parseable-Header mode is also switched on, i.e. any HTTP response headers can be generated while ePerl fills the missing gaps. The result is a full HTTP response which is not further processed by the webserver. This mode is automatically choosen when CGI/1.1 variables exists in the environment and the script does begin with the NPH prefix ``nph-''.

-c

This forces ePerl to act as a NPH-CGI/1.1 compliant program, i.e. HTTP response headers are printed in front of the HTML code and errors are displayed as HTML error pages.

-b begin_delimiter

Sets the Perl block begin delimiter string. Use this in conjunction with -e to set different delimiters when using ePerl as a offline HTML creation-language while still using it as a online HTML scripting-language.

Default delimiters are <? and !> for CGI modes and <: and :> for standalone Unix filtering mode.

Here are some possible variations you could choose:

"<?" and "!>"
default ePerl CGI mode delimiters

"<:" and ":>"
default ePerl stand-alone filtering mode delimiters

"<script language='ePerl'>" and "</script>" 
standard HTML scripting language style

"<!--#eperl code='" and "' -->"
NeoScript style

"<?" and ">"
PHP/FI style (no longer recommended because can lead 
to parsing problems. Should be used only for backward 
compatibility to old ePerl versions 1.x)

-e end_delimiter

Sets the Perl block end delimiter string. See option -b

-D name=value

Sets a Perl variable in the package main which can be referenced via $name or more explicitly via $main::name. The command

eperl -D name=value ..

is actually equivalent to having

<? $name = value; !>

at the beginning of inputfile.

-E name=value

Sets a environment variable which can be referenced via $ENV{'variable'} inside the Perl blocks. The command

eperl -E name=value ..

is actually equivalent to

export name=value; eperl ...

but the advantage of this option is that it doesn't manipulate the callers environment.

-o outputfile

Forces the output to be written to outputfile instead of stdout. Use this option when using ePerl as a filter. The outputfile ``-'' sets stdout as the output handle explicitly. Notice that this file is relative to the source file directory when the runtime mode is forced to CGI or NPH-CGI.

-k

Forces ePerl to keep the current working directory from where it was started. Per default ePerl will change to the directory where the file to be executed stays. This option is useful if you use ePerl as a offline filter on a temporary file.

-x

This sets debug mode where ePerl outputs some interesting information to the console.

-c

This runs a pure syntax check which is similar to perl -c.

-v

This prints ePerl version information to the console.

-V

Same as option -v but additionally shows the Perl compilation parameters.

-r

This prints the internal ePerl README file to the console.

-l

This prints the internal ePerl LICENSE file to the console.

INTERNALS

It is simply a tricky glue code which only combines the programming power of Perl 5 with the markup power of HTML.

A pure standard HTML document will be bristled with native Perl 5 code to create a so-called HTML document with embedded Perl 5 code. This document is then on-the-fly piped through the NPH-CGI program nph-eperl when the webserver receives a request for this document from the client. At this preprocessing pass ePerl expands the mixed language (HTML and Perl) to pure HTML by evaluating all Perl statements and passing through (without changing) all HTML statements. The result is send back to the webbrowser.

The trick is: ePerl itself only converts the ePerl source file into a valid Perl program file which then gets entirely evaluated by only one internal instance of the Perl 5 interpreter. To archieve this, ePerl translates all HTML markup code into (escaped) Perl 5 print constructs while passing through all embedded native Perl 5 code.

SECURITY

When you are installing ePerl as a NPH-CGI/1.1 program (nph-eperl) with setuid bit enabled (chmod u+s!) then ePerl can switch to the uid/gid of the script owner. Although this is a very useful feature for script programmers it can be to risky for you when you are paranoid about security of setuid programs. If so just don't install ePerl with enabled setuid bit! This is the reason why ePerl is not installed per default as nph-eperl for your webserver. For those who decided that this feature is essential for them ePerl tries hard to make it secure. The following steps have to be successfully passed before ePerl actually switches its uid/gid (in this order):

1. The script has to match the following extensions:
   .html, .phtml, .ephtml, .epl, .pl
2. The UID of the calling process has to be a valid UID,
   i.e. it has to be found in the systems password file
3. The UID of the calling process has to match the 
   following users: root, nobody
4. The UID of the script owner has to be a valid UID,
   i.e. it has to be found in the systems password file
5. The GID of the script group has to be a valid GID,
   i.e. it has to be found in the systems group file
6. The script has to stay below or in the owners homedir

IF ONLY ONE OF THOSE STEPS FAIL, NO UID/GID SWITCHING TAKES PLACE! You can only disable some steps at compile time. See eperl_global.h.

ENVIRONMENT

PATH_TRANSLATED

This CGI/1.1 variable is used to determine the source file when ePerl operates as a NPH-CGI/1.1 program under the environment of a webserver.

AUTHOR

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

cpanm ePerl

perl -MCPAN -e shell
install ePerl