Provided by: eperl_2.2.14-16build1_i386 bug

NAME

       ePerl - Embedded Perl 5 Language

VERSION

       @V@

SYNOPSIS

       eperl [-d name=value] [-D name=value] [-B begin_delimiter] [-E
       end_delimiter] [-i] [-m mode] [-o outputfile] [-k] [-I directory] [-P]
       [-C] [-L] [-x] [-T] [-w] [-c] [inputfile]

       eperl [-r] [-l] [-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 in various ways: As a stand-alone Unix filter or
       integrated Perl 5 module for general file generation tasks and as a
       powerful Webserver scripting language for dynamic HTML page
       programming.

   Introduction
       The eperl program is the Embedded Perl 5 Language interpreter. This
       really is a full-featured Perl 5 interpreter, but with a different
       calling environment and source file layout than the default Perl
       interpreter (usually the executable perl or perl5 on most systems).  It
       is designed for general 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 (usually
       by quoting the data and using them via "print" statements).  So,
       instead of writing a plain Perl script like

         #!/path/to/perl
         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 can write it now as an ePerl script:

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

       Although the ePerl variant has a different source file layout, the
       semantic is the same, i.e. both scripts create exactly the same
       resulting data on "STDOUT".

   Intention
       ePerl is simply a glue code which combines the programming power of the
       Perl 5 interpreter library with a tricky embedding technique.  The
       embedding trick is this: it 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 achieve this, ePerl translates all plain
       code into (escaped) Perl 5 strings placed into print constructs while
       passing through all embedded native Perl 5 code. As you can see, ePerl
       itself does exactly the same internally, a silly programmer had to do
       when writing a plain Perl generation script.

       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 generated 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 the ordinary program code of a plain Perl
       script. So, the static part should be at least 60% or the advantage
       becomes a disadvantage.

       ePerl in its origin was actually designed for an extreme situation: as
       a webserver scripting-language for on-the-fly HTML page generation.
       Here you have the typical case that usually 90% of the data consists of
       pure static HTML tags and plain ASCII while just the remaining 10% are
       programming constructs which dynamically generate more markup code.
       This is the reason why ePerl beside its standard Unix filtering
       runtime-mode also supports the CGI/1.1 and NPH-CGI/1.1 interfaces.

   Embedded Perl Syntax
       Practically you can put any valid Perl constructs inside the ePerl
       blocks the used Perl 5 interpreter library can evaluate. But there are
       some important points you should always remember and never forget when
       using ePerl:

       1. Delimiters are always discarded.
           Trivially to say, but should be mentioned at least once. The ePerl
           block delimiters are always discarded and are only necessary for
           ePerl to recognize the embedded Perl constructs. They are never
           passed to the final output.

       2. Generated content has to go to "STDOUT".
           Although you can define subroutines, calculate some data, etc.
           inside ePerl blocks only data which is explicitly written to the
           "STDOUT" filehandle is expanded. In other words: When an ePerl
           block does not generate content on "STDOUT", it is entirely
           replaced by an empty string in the final output.  But when content
           is generated it is put at the point of the ePerl block in the final
           output. Usually contents is generated via pure "print" constructs
           which implicitly use "STDOUT" when no filehandle is given.

       3. Generated content on "STDERR" always leads to an error.
           Whenever content is generated on the "STDERR" filehandle, ePerl
           displays an error (including the STDERR content). Use this to exit
           on errors while passing errors from ePerl blocks to the calling
           environment.

       4. Last semicolon.
           Because of the following point 6 (see below) and the fact that most
           of the users don't have the internal ePerl block translations in
           mind, ePerl is smart about the last semicolon. Usually every ePerl
           block has to end with the semicolon of the last command.

              <: cmd; ...; cmd; :>

           But when the last semicolon is missing it is automatically added by
           ePerl, i.e.

              <: cmd; ...; cmd :>

           is also correct syntax.  But sometimes it is necessary to force
           ePerl not to add the semicolon. Then you can add a ``"_"''
           (underscore) as the last non-whitespace character in the block to
           force ePerl to leave the final semicolon. Use this for constructs
           like the following

              <: if (...) { _:>
              foo
              <: } else { _:>
              bar
              <: } :>

           where you want to spread a Perl directive over more ePerl blocks.

       5. Shorthand for "print"-only blocks.
           Because most of the time ePerl is used just to interpolate
           variables, e.g.

              <: print $VARIABLE; :>

           it is useful to provide a shortcut for this kind of constructs.  So
           ePerl provides a shortcut via the character '='. When it
           immediately (no whitespaces allowed here) follows the begin
           delimiter of an ePerl block a "print" statement is implicitly
           generated, i.e. the above block is equivalent to

              <:=$VARIABLE:>

           Notice that the semicolon was also removed here, because it gets
           automatically added (see above).

       6. Special EndOfLine discard command for ePerl blocks.
           ePerl provides a special discard command named ``"//"'' which
           discards all data up-to and including the following newline
           character when directly followed an end block delimiter. Usually
           when you write

             foo
             <: $x = 1; :>
             quux

           the result is

             foo

             quux

           because ePerl always preserves code around ePerl blocks, even just
           newlines. But when you write

             foo
             <: $x = 1; :>//
             quux

           the result is

             foo
             quux

           because the ``"//"'' deleted all stuff to the end of the line,
           including the newline.

       7. Restrictions in parsing.
           Every program has its restrictions, ePerl too. Its handicap is that
           Perl is not only a rich language, it is a horrible one according to
           parsing its constructs. Perhaps you know the phrase ,,Only perl can
           parse Perl''.  Think about it. The implication of this is that
           ePerl never tries to parse the ePerl blocks itself. It entirely
           relies on the Perl interpreter library, because it is the only
           instance which can do this without errors.  But the problem is that
           ePerl at least has to recognize the begin and end positions of
           those ePerl blocks.

           There are two ways: It can either look for the end delimiter while
           parsing but at least recognize quoted strings (where the end
           delimiter gets treated as pure data). Or it can just move forward
           to the next end delimiter and say that it have not occur inside
           Perl constructs. In ePerl 2.0 the second one was used, while in
           ePerl 2.1 the first one was taken because a lot of users wanted it
           this way while using bad end delimiters like ``">"''. But actually
           the author has again revised its opinion and decided to finally use
           the second approach which is used since ePerl 2.2 now. Because
           while the first one allows more trivial delimiters (which itself is
           not a really good idea), it fails when constructs like
           ``"m|"[^"]+"|"'' etc.  are used inside ePerl blocks. And it is
           easier to escape end delimiters inside Perl constructs (for
           instance via backslashes in quoted strings) than rewrite complex
           Perl constructs to use even number of quotes.

           So, whenever your end delimiter also occurs inside Perl constructs
           you have to escape it in any way.

       8. HTML entity conversion.
           Because one of ePerl's usage is as a server-side scripting-language
           for HTML pages, there is a common problem in conjunction with HTML
           editors.  They cannot know ePerl blocks, so when you enter those
           blocks inside the editors they usually encode some characters with
           the corresponding HTML entities. The problem is that this encoding
           leads to invalid Perl code. ePerl provides the option -C for
           decoding these entities which is automatically turned on in CGI
           modes. See description below under option -C for more details.

   Runtime Modes
       ePerl can operate in three different runtime modes:

       Stand-alone Unix filter mode
           This is the default operation mode when used as a generation tool
           from the Unix shell or as a batch-processing tool from within other
           programs or scripts:

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

           As you can see, ePerl can be used in any combination of STDIO and
           external files. Additionally there are two interesting variants of
           using this mode.  First you can use ePerl in conjunction with the
           Unix Shebang magic technique to implicitly select it as the
           interpreter for your script similar to the way you are used to with
           the plain Perl interpreter:

             #!/path/to/eperl [options]
             foo
             <: print "bar"; :>
             quux

           Second, you can use ePerl in conjunction with the Bourne-Shell Here
           Document technique from within you shell scripts:

             #!/bin/sh
             ...
             eperl [options] - <<EOS
             foo
             <: print "quux"; :>
             quux
             EOS
             ...

           If you need to generate shell or other scripts with ePerl, i.e. you
           need a shebang line in the output of eperl, you have to add a
           shebang line containing e.g. "#!/usr/bin/eperl" first, because
           eperl will strip the first line from the input if it is a shebang
           line. Example:

             #!/usr/bin/eperl
             #!/bin/sh
             echo <: print "quux"; :>

           will result in the following output:

             #!/bin/sh
             echo quux

           Alternatively you can add a preprocessor comment in the first line,
           e.g. like this:

             #c This is a comment to preserve the shebang line in the following line
             #!/bin/sh
             echo <: print "quux"; :>

           And finally you can use ePerl directly from within Perl programs by
           the use of the Parse::ePerl(3) package (assuming that you have
           installed this also; see file INSTALL inside the ePerl distribution
           for more details):

             #!/path/to/perl
             ...
             use Parse::ePerl;
             ...
             $script = <<EOT;
             foo
             <: print "quux"; :>
             quux
             EOT
             ...
             $result = Parse::ePerl::Expand({
                 Script => $script,
                 Result => \$result,
             });
             ...
             print $result;
             ...

           See Parse::ePerl(3) for more details.

       CGI/1.1 compliant interface mode
           This is the runtime mode where ePerl uses the CGI/1.1 interface of
           a webserver when used as a Server-Side Scripting Language on the
           Web. ePerl enters this mode automatically when the CGI/1.1
           environment variable "PATH_TRANSLATED" is set and its or the
           scripts filename does not begin with the NPH prefix ``nph-''.  In
           this runtime mode it prefixes the resulting data with HTTP/1.0
           (default) or HTTP/1.1 (if identified by the webserver) compliant
           response header lines.

           ePerl also recognizes HTTP header lines at the beginning of the
           scripts generated data, i.e. for instance you can generate your own
           HTTP headers like

              <? $url = "..";
                 print "Location: $url\n";
                 print "URI: $url\n\n"; !>
              <html>
              ...

           But notice that while you can output arbitrary headers, most
           webservers restrict the headers which are accepted via the CGI/1.1
           interface. Usually you can provide only a few specific HTTP headers
           like "Location" or "Status".  If you need more control you have to
           use the NPH-CGI/1.1 interface mode.

           Additionally ePerl provides a useful feature in this mode: It can
           switch its UID/GID to the owner of the script if it runs as a Unix
           SetUID program (see below under Security and the option ``u+s'' of
           chmod(1)).

           There are two commonly known ways of using this CGI/1.1 interface
           mode on the Web. First, you can use it to explicitly transform
           plain HTML files into CGI/1.1 scripts via the Shebang technique
           (see above). For an Apache webserver just put the following line as
           the first line of the file:

             #!/path/to/eperl -mc

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

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

           Now make sure that Apache accepts file.cgi as a CGI program by
           enabling CGI support for the directory where file.cgi resides. For
           this add the line

             Options +ExecCGI

           to the .htaccess file in this directory. Finally make sure that
           Apache really recognizes the extension .cgi. Perhaps you
           additionally have to add the following line to your httpd.conf
           file:

             AddHandler cgi-script .cgi

           Now you can use file.cgi instead of file.html and make advantage of
           the achieved programming capability by bristling file.cgi with your
           Perl blocks (or the transformation into a CGI script would be
           useless).

           Alternatively (or even additionally) a webmaster can enable ePerl
           support in a more seamless way by configuring ePerl as a real
           implicit server-side scripting language. This is done by assigning
           a MIME-type to the various valid ePerl file extensions and forcing
           all files with this MIME-type to be internally processed via the
           ePerl interpreter. You can accomplish this for Apache by adding the
           following to your httpd.conf file

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

           and creating a copy of the eperl program in your CGI-directory:

             $ cp -p /path/to/eperl /path/to/apache/cgi-bin/eperl

           Now all files with the extensions .phtml, .eperl and .epl are
           automatically processed by the ePerl interpreter. There is no need
           for a Shebang line or any locally enabled CGI mode.

           One final hint: When you want to test your scripts offline, just
           run them with forced CGI/1.1 mode from your shell. But make sure
           you prepare all environment variables your script depends on, e.g.
           "QUERY_STRING" or "PATH_INFO".

             $ export QUERY_STRING="key1=value1&key2=value2"
             $ eperl -mc file.phtml

       NPH-CGI/1.1 compliant interface mode
           This runtime mode is a special variant of the CGI/1.1 interface
           mode, because most webservers (e.g. Apache) provide it for special
           purposes.   It is known as Non-Parsed-Header (NPH) CGI/1.1 mode and
           is usually used by the webserver when the filename of the CGI
           program is prefixed with ``"nph-"''.  In this mode the webserver
           does no processing on the HTTP response headers and no buffering of
           the resulting data, i.e. the CGI program actually has to provide a
           complete HTTP response itself. The advantage is that the program
           can generate arbitrary HTTP headers or MIME-encoded multi-block
           messages.

           So, above we have renamed the file to file.cgi which restricted us
           a little bit. When we alternatively rename file.html to
           nph-file.cgi and force the NPH-CGI/1.1 interface mode via option
           -mn then this file becomes a NPH-CGI/1.1 compliant program under
           Apache and other webservers. Now our script can provide its own
           HTTP response (it need not, because when absent ePerl provides a
           default one for it).

             #!/path/to/bin/eperl -mn
             <? print "HTTP/1.0 200 Ok\n";
                print "X-MyHeader: Foo Bar Quux\n";
                print "Content-type: text/html\n\n";
             <html>
             ...

           As you expect this can be also used with the implicit Server-Side
           Scripting Language technique. Put

             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

           into your httpd.conf and run the command

             $ cp -p /path/to/eperl /path/to/apache/cgi-bin/nph-eperl

           from your shell. This is the preferred way of using ePerl as a
           Server-Side Scripting Language, because it provides most
           flexibility.

   Security
       When you are installing ePerl as a CGI/1.1 or NPH-CGI/1.1 compliant
       program (see above for detailed description of these modes) via

         $ cp -p /path/to/eperl /path/to/apache/cgi-bin/eperl
         $ chown root /path/to/apache/cgi-bin/eperl
         $ chmod u+s  /path/to/apache/cgi-bin/eperl

       or

         $ cp -p /path/to/eperl /path/to/apache/cgi-bin/nph-eperl
         $ chown root /path/to/apache/cgi-bin/nph-eperl
         $ chmod u+s  /path/to/apache/cgi-bin/nph-eperl

       i.e. with SetUID bit enabled for the root user, ePerl can switch to the
       UID/GID of the scripts owner. Although this is a very useful feature
       for script programmers (because one no longer need to make auxiliary
       files world-readable and temporary files world-writable!), 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 per default only installed as a Stand-Alone Unix
       filter which never needs this feature.

       For those of us who decided that this feature is essential for them
       ePerl tries really 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, .cgi
         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!.
       Additionally (if "DO_ON_FAILED_STEP" was defined as "STOP_AND_ERROR" in
       eperl_security.h - not per default defined this way!) ePerl can totally
       stop processing and display its error page.  This is for the really
       paranoid webmasters. Per default when any step failed the UID/GID
       switching is just disabled, but ePerl goes on with processing.
       Alternatively you can disable some steps at compile time. See
       eperl_security.h.

       Also remember that ePerl always eliminates the effective UID/GID,
       independent of the runtime mode and independent if ePerl has switched
       to the UID/GID of the owner. For security reasons, the effective
       UID/GID is always destroyed before the script is executed.

   ePerl Preprocessor
       ePerl provides an own preprocessor similar to CPP in style which is
       either enabled manually via option -P or automatically when ePerl runs
       in (NPH-)CGI mode.  The following directives are supported:

       "#include path"
           This directive is an include directive which can be used to include
           really any stuff, but was actually designed to be used to include
           other ePerl source files. The path can be either a relative or
           absolute path for the local filesystem or a fully qualified HTTP
           URL.

           In case of the absolute path the file is directly accessed on the
           filesystem, while the relative path is first searched in the
           current working directory and then in all directories specified via
           option -I. In the third case (HTTP URL) the file is retrieves via a
           HTTP/1.0 request on the network.  Here HTTP redirects (response
           codes 301 and 302) are supported, too.

           Notice: While ePerl strictly preserves the line numbers when
           translating the bristled ePerl format to plain Perl format, the
           ePerl preprocessor can't do this (because its a preprocessor which
           expands) for this directive.  So, whenever you use "#include",
           remember that line numbers in error messages are wrong.

           Also notice one important security aspect: Because you can include
           any stuff as it is provided with this directive, use it only for
           stuff which is under your direct control. Don't use this directive
           to include foreign data, at least not from external webservers. For
           instance say you have a ePerl page with "#include
           http://www.foreigner.com/nice-page.html" and at the next request of
           this page your filesystem is lost! Why? Because the foreigner
           recognizes that you include his page and are using ePerl and just
           put a simple ``"<?  system("rm -rf /"); !>"'' in his page. Think
           about it.  NEVER USE #INCLUDE FOR ANY DATA WHICH IS NOT UNDER YOUR
           OWN CONTROL.  Instead always use "#sinclude" for such situations.

       "#sinclude path"
           This is the secure variant of "#include" where after reading the
           data from path all ePerl begin and end delimiters are removed. So
           risky ePerl blocks lost their meaning and are converted to plain
           text. Always use this directive when you want to include data which
           is not under your own control.

       "#if expr", "#elsif expr", "#else", "#endif"
           These implement a CPP-style "#if-[#else-]#endif" construct, but
           with a Perl semantic. While the other directives are real
           preprocessor commands which are evaluated at the preprocessing
           step, this construct is actually just transformed into a low-level
           ePerl construct, so it is not actually evaluated at the
           preprocessing step. It is just a handy shortcut for the following
           (where BD is the currently used begin delimiter and ED the end
           delimiter):

             ``#if expr''    ->  ``BD if (expr) { _ ED//''
             ``#elsif expr'' ->  ``BD } elsif (expr) { _ ED//''
             ``#else''       ->  ``BD } else { _ ED//''
             ``#endif''      ->  ``BD } _ ED//''

           The advantage of this unusual aproach is that the if-condition
           really can be any valid Perl expression which provides maximum
           flexibility. The disadvantage is that you cannot use the if-
           construct to make real preprocessing decisions.  As you can see,
           the design goal was just to provide a shorthand for the more
           complicated Perl constructs.

       "#c"
           This is the comment directive which just discards all data up to
           and including the newline character. Use this one to comment out
           any stuff, even other preprocessor directives.

   Provided Functionality
       Up to know you've understand that ePerl provides a nice facility to
       embed Perl code into any ASCII data. But now the typical question is:
       Which Perl code can be put into these ePerl blocks and does ePerl
       provide any special functionality inside these ePerl blocks?

       The answers are: First, you can put really any Perl code into the ePerl
       blocks which are valid to the Perl interpreter ePerl was linked with.
       Second, ePerl does not provide any special functionality inside these
       ePerl blocks, because Perl is already sophisticated enough ;-)

       The implication of this is: Because you can use any valid Perl code you
       can make use of all available Perl 5 modules, even those ones which use
       shared objects (because ePerl is a Perl interpreter, including
       DynaLoader support). So, browse to the Comprehensive Perl Archive
       Network (CPAN) via http://www.perl.com/perl/CPAN and grab your favorite
       packages which can make your life easier (both from within plain Perl
       scripts and ePerl scripts) and just use the construct ``"use name;"''
       in any ePerl block to use them from within ePerl.

       When using ePerl as a Server-Side-Scripting-Language I really recommend
       you to install at least the packages CGI.pm (currently vers.  2.36),
       HTML-Stream (1.40), libnet (1.0505) and libwww-perl (5.08).  When you
       want to generate on-the-fly images as well, I recommend you to
       additionally install at least GD (1.14) and Image-Size (2.3). The ePerl
       interpreter in conjunction with these really sophisticated Perl 5
       modules will provide you with maximum flexibility and functionality. In
       other words: Make use of maximum Software Leverage in the hackers world
       of Perl as great as possible.

OPTIONS

       -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. This option can occur more than
           once.

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

             eperl -D 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. This option can occur more than once.

       -B begin_delimiter
           Sets the Perl block begin delimiter string. Use this in conjunction
           with "-E" to set different delimiters when using ePerl as an
           offline HTML creation-language while still using it as an online
           HTML scripting-language.  Default delimiters are "<?" and "!>" for
           CGI modes and "<:" and ":>" for stand-alone Unix filtering mode.

           There are a lot of possible variations you could choose: ""<:"" and
           "":>"" (the default ePerl stand-alone filtering mode delimiters),
           ""<?"" and ""!>"" (the default ePerl CGI interface mode
           delimiters), ""<script language='ePerl'>"" and ""</script>""
           (standard HTML scripting language style), ""<script
           type="text/eperl">"" and ""</script>"" (forthcoming HTML3.2+ aka
           Cougar style), ""<eperl>"" and ""</eperl>"" (HTML-like style),
           ""<!--#eperl code='"" and ""' -->"" (NeoScript and SSI style) or
           even ""<?"" and "">"" (PHP/FI style; but this no longer recommended
           because it can lead to parsing problems. Should be used only for
           backward compatibility to old ePerl versions 1.x).

           The begin and end delimiters are searched case-insensitive.

       -E end_delimiter
           Sets the Perl block end delimiter string. See also option -B.

       -i  Forces the begin and end delimiters to be searched case-
           insensitive.  Use this when you are using delimiters like
           ``"<ePerl>"..."</ePerl>"'' or other more textual ones.

       -m mode
           This forces ePerl to act in a specific runtime mode.  See above for
           a detailed description of the three possible modes: Stand-alone
           filter (mode="f", i.e. option -mf), CGI/1.1 interface mode
           (mode="c", i.e. option -mc) or the NPH-CGI/1.1 interface mode
           (mode="n", i.e. option -mn).

       -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 an offline filter on a temporary file.

       -x  This sets debug mode where ePerl outputs the internally created
           Perl script to the console (/dev/tty) before executing it. Only for
           debugging problems with the inputfile conversion.

       -I directory
           Specify a directory which is both used for "#include" and
           "#sinclude" directives of the ePerl preprocessor and added to @INC
           under runtime.  This option can occur more than once.

       -P  Manually enables the special ePerl Preprocessor (see above). This
           option is enabled for all CGI modes automatically.

       -C  This enables the HTML entity conversion for ePerl blocks. This
           option is automatically forced in CGI modes.

           The solved problem here is the following: When you use ePerl as a
           Server-Side-Scripting-Language for HTML pages and you edit your
           ePerl source files via a HTML editor, the chance is high that your
           editor translates some entered characters to HTML entities, for
           instance ``"<"'' to ``"&lt;"''.  This leads to invalid Perl code
           inside ePerl blocks, because the HTML editor has no knowledge about
           ePerl blocks. Using this option the ePerl parser automatically
           converts all entities found inside ePerl blocks back to plain
           characters, so the Perl interpreter again receives valid code
           blocks.

       -L  This enables the line continuation character ``"\"'' (backslash)
           outside ePerl blocks. With this option you can spread oneline-data
           over more lines.  But use with care: This option changes your data
           (outside ePerl blocks).  Usually ePerl really pass through all
           surrounding data as raw data. With this option the newlines become
           new semantics.

       -T  This enabled Perl's Tainting mode where the Perl interpreter takes
           special precautions called taint checks to prevent both obvious and
           subtle traps.  See perlsec(1) for more details.

       -w  This enables Warnings where the Perl interpreter produces some
           lovely diagnostics. See perldiag(1) for more details.

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

       -r  This prints the internal ePerl README file to the console.

       -l  This prints the internal ePerl LICENSE file to the console.

       -v  This prints ePerl version information to the console.

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

ENVIRONMENT

   Used Variables
       "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.

   Provided Variables
       "SCRIPT_SRC_PATH"
           The absolute pathname of the script. Use this when you want to
           directly access the script from within itself, for instance to do
           "stat()" and other calls.

       "SCRIPT_SRC_PATH_DIR"
           The directory part of "SCRIPT_SRC_PATH". Use this one when you want
           to directly access other files residing in the same directory as
           the script, for instance to read config files, etc.

       "SCRIPT_SRC_PATH_FILE"
           The filename part of "SCRIPT_SRC_PATH". Use this one when you need
           the name of the script, for instance for relative self-references
           through URLs.

       "SCRIPT_SRC_URL"
           The fully-qualified URL of the script. Use this when you need a URL
           for self-reference.

       "SCRIPT_SRC_URL_DIR"
           The directory part of "SCRIPT_SRC_URL". Use this one when you want
           to directly access other files residing in the same directory as
           the script via the Web, for instance to reference images, etc.

       "SCRIPT_SRC_URL_FILE"
           The filename part of "SCRIPT_SRC_URL". Use this one when you need
           the name of the script, for instance for relative self-references
           through URLs.  Actually the same as "SCRIPT_SRC_PATH_FILE", but
           provided for consistency.

       "SCRIPT_SRC_SIZE"
           The filesize of the script, in bytes.

       "SCRIPT_SRC_MODIFIED"
           The last modification time of the script, in seconds since 0 hours,
           0 minutes, 0 seconds, January 1, 1970, Coordinated Universal Time.

       "SCRIPT_SRC_MODIFIED_CTIME"
           The last modification time of the script, in ctime(3) format
           (``WDAY MMM DD HH:MM:SS YYYY\n'').

       "SCRIPT_SRC_MODIFIED_ISOTIME"
           The last modification time of the script, in ISO format
           (``DD-MM-YYYY HH:MM'').

       "SCRIPT_SRC_OWNER"
           The username of the script owner.

       "VERSION_INTERPRETER"
           The ePerl identification string.

       "VERSION_LANGUAGE"
           The identification string of the used Perl interpreter library.

   Provided Built-In Images
       The following built-in images can be accessed via URL
       "/url/to/nph-eperl/"NAME".gif":

       "logo.gif"
           The standard ePerl logo. Please do not include this one on your
           website.

       "powered.gif"
           The ``powered by ePerl 2.2'' logo. Feel free to use this on your
           website.

AUTHOR

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

SEEALSO

       Parse::ePerl(3), Apache::ePerl(3).

       Web-References:

         Perl:   perl(1),  http://www.perl.com/
         ePerl:  eperl(1), http://www.ossp.org/pkg/tool/eperl/
         Apache: httpd(8), http://www.apache.org/