1EPERL(1)                      Ralf S. Engelschall                     EPERL(1)
2
3
4

NAME

6       ePerl - Embedded Perl 5 Language
7

VERSION

9       @V@
10

SYNOPSIS

12       eperl [-d name=value] [-D name=value] [-B begin_delimiter] [-E
13       end_delimiter] [-i] [-m mode] [-o outputfile] [-k] [-I directory] [-P]
14       [-C] [-L] [-x] [-T] [-w] [-c] [inputfile]
15
16       eperl [-r] [-l] [-v] [-V]
17

DESCRIPTION

19   Abstract
20       ePerl interprets an ASCII file bristled with Perl 5 program statements
21       by evaluating the Perl 5 code while passing through the plain ASCII
22       data. It can operate in various ways: As a stand-alone Unix filter or
23       integrated Perl 5 module for general file generation tasks and as a
24       powerful Webserver scripting language for dynamic HTML page
25       programming.
26
27   Introduction
28       The eperl program is the Embedded Perl 5 Language interpreter. This
29       really is a full-featured Perl 5 interpreter, but with a different
30       calling environment and source file layout than the default Perl
31       interpreter (usually the executable perl or perl5 on most systems).  It
32       is designed for general ASCII file generation with the philosophy of
33       embedding the Perl 5 program code into the ASCII data instead of the
34       usual way where you embed the ASCII data into a Perl 5 program (usually
35       by quoting the data and using them via "print" statements).  So,
36       instead of writing a plain Perl script like
37
38         #!/path/to/perl
39         print "foo bar\n";
40         print "baz quux\n";
41         for ($i = 0; $i < 10; $i++) { print "foo #${i}\n"; }
42         print "foo bar\n";
43         print "baz quux\n";
44
45       you can write it now as an ePerl script:
46
47         #!/path/to/eperl
48         foo bar
49         baz quux
50         <: for ($i = 0; $i < 10; $i++) { print "foo #${i}\n"; } :>
51         foo bar
52         baz quux
53
54       Although the ePerl variant has a different source file layout, the
55       semantic is the same, i.e. both scripts create exactly the same
56       resulting data on "STDOUT".
57
58   Intention
59       ePerl is simply a glue code which combines the programming power of the
60       Perl 5 interpreter library with a tricky embedding technique.  The
61       embedding trick is this: it converts the source file into a valid Perl
62       script which then gets entirely evaluated by only one internal instance
63       of the Perl 5 interpreter.  To achieve this, ePerl translates all plain
64       code into (escaped) Perl 5 strings placed into print constructs while
65       passing through all embedded native Perl 5 code. As you can see, ePerl
66       itself does exactly the same internally, a silly programmer had to do
67       when writing a plain Perl generation script.
68
69       Due to the nature of such bristled code, ePerl is really the better
70       attempt when the generated ASCII data contains really more static as
71       dynamic data. Or in other words: Use ePerl if you want to keep the most
72       of the generated ASCII data in plain format while just programming some
73       bristled stuff. Do not use it when generating pure dynamic data. There
74       it brings no advantage to the ordinary program code of a plain Perl
75       script. So, the static part should be at least 60% or the advantage
76       becomes a disadvantage.
77
78       ePerl in its origin was actually designed for an extreme situation: as
79       a webserver scripting-language for on-the-fly HTML page generation.
80       Here you have the typical case that usually 90% of the data consists of
81       pure static HTML tags and plain ASCII while just the remaining 10% are
82       programming constructs which dynamically generate more markup code.
83       This is the reason why ePerl beside its standard Unix filtering
84       runtime-mode also supports the CGI/1.1 and NPH-CGI/1.1 interfaces.
85
86   Embedded Perl Syntax
87       Practically you can put any valid Perl constructs inside the ePerl
88       blocks the used Perl 5 interpreter library can evaluate. But there are
89       some important points you should always remember and never forget when
90       using ePerl:
91
92       1. Delimiters are always discarded.
93           Trivially to say, but should be mentioned at least once. The ePerl
94           block delimiters are always discarded and are only necessary for
95           ePerl to recognize the embedded Perl constructs. They are never
96           passed to the final output.
97
98       2. Generated content has to go to "STDOUT".
99           Although you can define subroutines, calculate some data, etc.
100           inside ePerl blocks only data which is explicitly written to the
101           "STDOUT" filehandle is expanded. In other words: When an ePerl
102           block does not generate content on "STDOUT", it is entirely
103           replaced by an empty string in the final output.  But when content
104           is generated it is put at the point of the ePerl block in the final
105           output. Usually contents is generated via pure "print" constructs
106           which implicitly use "STDOUT" when no filehandle is given.
107
108       3. Generated content on "STDERR" always leads to an error.
109           Whenever content is generated on the "STDERR" filehandle, ePerl
110           displays an error (including the STDERR content). Use this to exit
111           on errors while passing errors from ePerl blocks to the calling
112           environment.
113
114       4. Last semicolon.
115           Because of the following point 6 (see below) and the fact that most
116           of the users don't have the internal ePerl block translations in
117           mind, ePerl is smart about the last semicolon. Usually every ePerl
118           block has to end with the semicolon of the last command.
119
120              <: cmd; ...; cmd; :>
121
122           But when the last semicolon is missing it is automatically added by
123           ePerl, i.e.
124
125              <: cmd; ...; cmd :>
126
127           is also correct syntax.  But sometimes it is necessary to force
128           ePerl not to add the semicolon. Then you can add a ``"_"''
129           (underscore) as the last non-whitespace character in the block to
130           force ePerl to leave the final semicolon. Use this for constructs
131           like the following
132
133              <: if (...) { _:>
134              foo
135              <: } else { _:>
136              bar
137              <: } :>
138
139           where you want to spread a Perl directive over more ePerl blocks.
140
141       5. Shorthand for "print"-only blocks.
142           Because most of the time ePerl is used just to interpolate
143           variables, e.g.
144
145              <: print $VARIABLE; :>
146
147           it is useful to provide a shortcut for this kind of constructs.  So
148           ePerl provides a shortcut via the character '='. When it
149           immediately (no whitespaces allowed here) follows the begin
150           delimiter of an ePerl block a "print" statement is implicitly
151           generated, i.e. the above block is equivalent to
152
153              <:=$VARIABLE:>
154
155           Notice that the semicolon was also removed here, because it gets
156           automatically added (see above).
157
158       6. Special EndOfLine discard command for ePerl blocks.
159           ePerl provides a special discard command named ``"//"'' which
160           discards all data up-to and including the following newline
161           character when directly followed an end block delimiter. Usually
162           when you write
163
164             foo
165             <: $x = 1; :>
166             quux
167
168           the result is
169
170             foo
171
172             quux
173
174           because ePerl always preserves code around ePerl blocks, even just
175           newlines. But when you write
176
177             foo
178             <: $x = 1; :>//
179             quux
180
181           the result is
182
183             foo
184             quux
185
186           because the ``"//"'' deleted all stuff to the end of the line,
187           including the newline.
188
189       7. Restrictions in parsing.
190           Every program has its restrictions, ePerl too. Its handicap is that
191           Perl is not only a rich language, it is a horrible one according to
192           parsing its constructs. Perhaps you know the phrase ,,Only perl can
193           parse Perl''.  Think about it. The implication of this is that
194           ePerl never tries to parse the ePerl blocks itself. It entirely
195           relies on the Perl interpreter library, because it is the only
196           instance which can do this without errors.  But the problem is that
197           ePerl at least has to recognize the begin and end positions of
198           those ePerl blocks.
199
200           There are two ways: It can either look for the end delimiter while
201           parsing but at least recognize quoted strings (where the end
202           delimiter gets treated as pure data). Or it can just move forward
203           to the next end delimiter and say that it have not occur inside
204           Perl constructs. In ePerl 2.0 the second one was used, while in
205           ePerl 2.1 the first one was taken because a lot of users wanted it
206           this way while using bad end delimiters like ``">"''. But actually
207           the author has again revised its opinion and decided to finally use
208           the second approach which is used since ePerl 2.2 now. Because
209           while the first one allows more trivial delimiters (which itself is
210           not a really good idea), it fails when constructs like
211           ``"m|"[^"]+"|"'' etc.  are used inside ePerl blocks. And it is
212           easier to escape end delimiters inside Perl constructs (for
213           instance via backslashes in quoted strings) than rewrite complex
214           Perl constructs to use even number of quotes.
215
216           So, whenever your end delimiter also occurs inside Perl constructs
217           you have to escape it in any way.
218
219       8. HTML entity conversion.
220           Because one of ePerl's usage is as a server-side scripting-language
221           for HTML pages, there is a common problem in conjunction with HTML
222           editors.  They cannot know ePerl blocks, so when you enter those
223           blocks inside the editors they usually encode some characters with
224           the corresponding HTML entities. The problem is that this encoding
225           leads to invalid Perl code. ePerl provides the option -C for
226           decoding these entities which is automatically turned on in CGI
227           modes. See description below under option -C for more details.
228
229   Runtime Modes
230       ePerl can operate in three different runtime modes:
231
232       Stand-alone Unix filter mode
233           This is the default operation mode when used as a generation tool
234           from the Unix shell or as a batch-processing tool from within other
235           programs or scripts:
236
237             $ eperl [options] - < inputfile > outputfile
238             $ eperl [options] inputfile > outputfile
239             $ eperl [options] -o outputfile - < inputfile
240             $ eperl [options] -o outputfile inputfile
241
242           As you can see, ePerl can be used in any combination of STDIO and
243           external files. Additionally there are two interesting variants of
244           using this mode.  First you can use ePerl in conjunction with the
245           Unix Shebang magic technique to implicitly select it as the
246           interpreter for your script similar to the way you are used to with
247           the plain Perl interpreter:
248
249             #!/path/to/eperl [options]
250             foo
251             <: print "bar"; :>
252             quux
253
254           Second, you can use ePerl in conjunction with the Bourne-Shell Here
255           Document technique from within you shell scripts:
256
257             #!/bin/sh
258             ...
259             eperl [options] - <<EOS
260             foo
261             <: print "quux"; :>
262             quux
263             EOS
264             ...
265
266           And finally you can use ePerl directly from within Perl programs by
267           the use of the Parse::ePerl(3) package (assuming that you have
268           installed this also; see file INSTALL inside the ePerl distribution
269           for more details):
270
271             #!/path/to/perl
272             ...
273             use Parse::ePerl;
274             ...
275             $script = <<EOT;
276             foo
277             <: print "quux"; :>
278             quux
279             EOT
280             ...
281             $result = Parse::ePerl::Expand({
282                 Script => $script,
283                 Result => \$result,
284             });
285             ...
286             print $result;
287             ...
288
289           See Parse::ePerl(3) for more details.
290
291       CGI/1.1 compliant interface mode
292           This is the runtime mode where ePerl uses the CGI/1.1 interface of
293           a webserver when used as a Server-Side Scripting Language on the
294           Web. ePerl enters this mode automatically when the CGI/1.1
295           environment variable "PATH_TRANSLATED" is set and its or the
296           scripts filename does not begin with the NPH prefix ``nph-''.  In
297           this runtime mode it prefixes the resulting data with HTTP/1.0
298           (default) or HTTP/1.1 (if identified by the webserver) compliant
299           response header lines.
300
301           ePerl also recognizes HTTP header lines at the beginning of the
302           scripts generated data, i.e. for instance you can generate your own
303           HTTP headers like
304
305              <? $url = "..";
306                 print "Location: $url\n";
307                 print "URI: $url\n\n"; !>
308              <html>
309              ...
310
311           But notice that while you can output arbitrary headers, most
312           webservers restrict the headers which are accepted via the CGI/1.1
313           interface. Usually you can provide only a few specific HTTP headers
314           like "Location" or "Status".  If you need more control you have to
315           use the NPH-CGI/1.1 interface mode.
316
317           Additionally ePerl provides a useful feature in this mode: It can
318           switch its UID/GID to the owner of the script if it runs as a Unix
319           SetUID program (see below under Security and the option ``u+s'' of
320           chmod(1)).
321
322           There are two commonly known ways of using this CGI/1.1 interface
323           mode on the Web. First, you can use it to explicitly transform
324           plain HTML files into CGI/1.1 scripts via the Shebang technique
325           (see above). For an Apache webserver just put the following line as
326           the first line of the file:
327
328             #!/path/to/eperl -mc
329
330           Then rename the script from file.html to file.cgi and set its
331           execution bit via
332
333             $ mv file.html file.cgi
334             $ chmod a+rx file.cgi
335
336           Now make sure that Apache accepts file.cgi as a CGI program by
337           enabling CGI support for the directory where file.cgi resides. For
338           this add the line
339
340             Options +ExecCGI
341
342           to the .htaccess file in this directory. Finally make sure that
343           Apache really recognizes the extension .cgi. Perhaps you
344           additionally have to add the following line to your httpd.conf
345           file:
346
347             AddHandler cgi-script .cgi
348
349           Now you can use file.cgi instead of file.html and make advantage of
350           the achieved programming capability by bristling file.cgi with your
351           Perl blocks (or the transformation into a CGI script would be
352           useless).
353
354           Alternatively (or even additionally) a webmaster can enable ePerl
355           support in a more seamless way by configuring ePerl as a real
356           implicit server-side scripting language. This is done by assigning
357           a MIME-type to the various valid ePerl file extensions and forcing
358           all files with this MIME-type to be internally processed via the
359           ePerl interpreter. You can accomplish this for Apache by adding the
360           following to your httpd.conf file
361
362             AddType      application/x-httpd-eperl  .phtml .eperl .epl
363             Action       application/x-httpd-eperl  /internal/cgi/eperl
364             ScriptAlias  /internal/cgi              /path/to/apache/cgi-bin
365
366           and creating a copy of the eperl program in your CGI-directory:
367
368             $ cp -p /path/to/eperl /path/to/apache/cgi-bin/eperl
369
370           Now all files with the extensions .phtml, .eperl and .epl are
371           automatically processed by the ePerl interpreter. There is no need
372           for a Shebang line or any locally enabled CGI mode.
373
374           One final hint: When you want to test your scripts offline, just
375           run them with forced CGI/1.1 mode from your shell. But make sure
376           you prepare all environment variables your script depends on, e.g.
377           "QUERY_STRING" or "PATH_INFO".
378
379             $ export QUERY_STRING="key1=value1&key2=value2"
380             $ eperl -mc file.phtml
381
382       NPH-CGI/1.1 compliant interface mode
383           This runtime mode is a special variant of the CGI/1.1 interface
384           mode, because most webservers (e.g. Apache) provide it for special
385           purposes.   It is known as Non-Parsed-Header (NPH) CGI/1.1 mode and
386           is usually used by the webserver when the filename of the CGI
387           program is prefixed with ``"nph-"''.  In this mode the webserver
388           does no processing on the HTTP response headers and no buffering of
389           the resulting data, i.e. the CGI program actually has to provide a
390           complete HTTP response itself. The advantage is that the program
391           can generate arbitrary HTTP headers or MIME-encoded multi-block
392           messages.
393
394           So, above we have renamed the file to file.cgi which restricted us
395           a little bit. When we alternatively rename file.html to
396           nph-file.cgi and force the NPH-CGI/1.1 interface mode via option
397           -mn then this file becomes a NPH-CGI/1.1 compliant program under
398           Apache and other webservers. Now our script can provide its own
399           HTTP response (it need not, because when absent ePerl provides a
400           default one for it).
401
402             #!/path/to/bin/eperl -mn
403             <? print "HTTP/1.0 200 Ok\n";
404                print "X-MyHeader: Foo Bar Quux\n";
405                print "Content-type: text/html\n\n";
406             <html>
407             ...
408
409           As you expect this can be also used with the implicit Server-Side
410           Scripting Language technique. Put
411
412             AddType      application/x-httpd-eperl  .phtml .eperl .epl
413             Action       application/x-httpd-eperl  /internal/cgi/nph-eperl
414             ScriptAlias  /internal/cgi              /path/to/apache/cgi-bin
415
416           into your httpd.conf and run the command
417
418             $ cp -p /path/to/eperl /path/to/apache/cgi-bin/nph-eperl
419
420           from your shell. This is the preferred way of using ePerl as a
421           Server-Side Scripting Language, because it provides most
422           flexibility.
423
424   Security
425       When you are installing ePerl as a CGI/1.1 or NPH-CGI/1.1 compliant
426       program (see above for detailed description of these modes) via
427
428         $ cp -p /path/to/eperl /path/to/apache/cgi-bin/eperl
429         $ chown root /path/to/apache/cgi-bin/eperl
430         $ chmod u+s  /path/to/apache/cgi-bin/eperl
431
432       or
433
434         $ cp -p /path/to/eperl /path/to/apache/cgi-bin/nph-eperl
435         $ chown root /path/to/apache/cgi-bin/nph-eperl
436         $ chmod u+s  /path/to/apache/cgi-bin/nph-eperl
437
438       i.e. with SetUID bit enabled for the root user, ePerl can switch to the
439       UID/GID of the scripts owner. Although this is a very useful feature
440       for script programmers (because one no longer need to make auxiliary
441       files world-readable and temporary files world-writable!), it can be to
442       risky for you when you are paranoid about security of SetUID programs.
443       If so just don't install ePerl with enabled SetUID bit! This is the
444       reason why ePerl is per default only installed as a Stand-Alone Unix
445       filter which never needs this feature.
446
447       For those of us who decided that this feature is essential for them
448       ePerl tries really hard to make it secure. The following steps have to
449       be successfully passed before ePerl actually switches its UID/GID (in
450       this order):
451
452         1. The script has to match the following extensions:
453            .html, .phtml, .ephtml, .epl, .pl, .cgi
454         2. The UID of the calling process has to be a valid UID,
455            i.e. it has to be found in the systems password file
456         3. The UID of the calling process has to match the
457            following users: root, nobody
458         4. The UID of the script owner has to be a valid UID,
459            i.e. it has to be found in the systems password file
460         5. The GID of the script group has to be a valid GID,
461            i.e. it has to be found in the systems group file
462         6. The script has to stay below or in the owners homedir
463
464       IF ONLY ONE OF THOSE STEPS FAIL, NO UID/GID SWITCHING TAKES PLACE!.
465       Additionally (if "DO_ON_FAILED_STEP" was defined as "STOP_AND_ERROR" in
466       eperl_security.h - not per default defined this way!) ePerl can totally
467       stop processing and display its error page.  This is for the really
468       paranoid webmasters. Per default when any step failed the UID/GID
469       switching is just disabled, but ePerl goes on with processing.
470       Alternatively you can disable some steps at compile time. See
471       eperl_security.h.
472
473       Also remember that ePerl always eliminates the effective UID/GID,
474       independent of the runtime mode and independent if ePerl has switched
475       to the UID/GID of the owner. For security reasons, the effective
476       UID/GID is always destroyed before the script is executed.
477
478   ePerl Preprocessor
479       ePerl provides an own preprocessor similar to CPP in style which is
480       either enabled manually via option -P or automatically when ePerl runs
481       in (NPH-)CGI mode.  The following directives are supported:
482
483       "#include path"
484           This directive is an include directive which can be used to include
485           really any stuff, but was actually designed to be used to include
486           other ePerl source files. The path can be either a relative or
487           absolute path for the local filesystem or a fully qualified HTTP
488           URL.
489
490           In case of the absolute path the file is directly accessed on the
491           filesystem, while the relative path is first searched in the
492           current working directory and then in all directories specified via
493           option -I. In the third case (HTTP URL) the file is retrieves via a
494           HTTP/1.0 request on the network.  Here HTTP redirects (response
495           codes 301 and 302) are supported, too.
496
497           Notice: While ePerl strictly preserves the line numbers when
498           translating the bristled ePerl format to plain Perl format, the
499           ePerl preprocessor can't do this (because its a preprocessor which
500           expands) for this directive.  So, whenever you use "#include",
501           remember that line numbers in error messages are wrong.
502
503           Also notice one important security aspect: Because you can include
504           any stuff as it is provided with this directive, use it only for
505           stuff which is under your direct control. Don't use this directive
506           to include foreign data, at least not from external webservers. For
507           instance say you have a ePerl page with "#include
508           http://www.foreigner.com/nice-page.html" and at the next request of
509           this page your filesystem is lost! Why? Because the foreigner
510           recognizes that you include his page and are using ePerl and just
511           put a simple ``"<?  system("rm -rf /"); !>"'' in his page. Think
512           about it.  NEVER USE #INCLUDE FOR ANY DATA WHICH IS NOT UNDER YOUR
513           OWN CONTROL.  Instead always use "#sinclude" for such situations.
514
515       "#sinclude path"
516           This is the secure variant of "#include" where after reading the
517           data from path all ePerl begin and end delimiters are removed. So
518           risky ePerl blocks lost their meaning and are converted to plain
519           text. Always use this directive when you want to include data which
520           is not under your own control.
521
522       "#if expr", "#elsif expr", "#else", "#endif"
523           These implement a CPP-style "#if-[#else-]#endif" construct, but
524           with a Perl semantic. While the other directives are real
525           preprocessor commands which are evaluated at the preprocessing
526           step, this construct is actually just transformed into a low-level
527           ePerl construct, so it is not actually evaluated at the
528           preprocessing step. It is just a handy shortcut for the following
529           (where BD is the currently used begin delimiter and ED the end
530           delimiter):
531
532             ``#if expr''    ->  ``BD if (expr) { _ ED//''
533             ``#elsif expr'' ->  ``BD } elsif (expr) { _ ED//''
534             ``#else''       ->  ``BD } else { _ ED//''
535             ``#endif''      ->  ``BD } _ ED//''
536
537           The advantage of this unusual aproach is that the if-condition
538           really can be any valid Perl expression which provides maximum
539           flexibility. The disadvantage is that you cannot use the if-
540           construct to make real preprocessing decisions.  As you can see,
541           the design goal was just to provide a shorthand for the more
542           complicated Perl constructs.
543
544       "#c"
545           This is the comment directive which just discards all data up to
546           and including the newline character. Use this one to comment out
547           any stuff, even other preprocessor directives.
548
549   Provided Functionality
550       Up to know you've understand that ePerl provides a nice facility to
551       embed Perl code into any ASCII data. But now the typical question is:
552       Which Perl code can be put into these ePerl blocks and does ePerl
553       provide any special functionality inside these ePerl blocks?
554
555       The answers are: First, you can put really any Perl code into the ePerl
556       blocks which are valid to the Perl interpreter ePerl was linked with.
557       Second, ePerl does not provide any special functionality inside these
558       ePerl blocks, because Perl is already sophisticated enough ;-)
559
560       The implication of this is: Because you can use any valid Perl code you
561       can make use of all available Perl 5 modules, even those ones which use
562       shared objects (because ePerl is a Perl interpreter, including
563       DynaLoader support). So, browse to the Comprehensive Perl Archive
564       Network (CPAN) via http://www.perl.com/perl/CPAN and grab your favorite
565       packages which can make your life easier (both from within plain Perl
566       scripts and ePerl scripts) and just use the construct ``"use name;"''
567       in any ePerl block to use them from within ePerl.
568
569       When using ePerl as a Server-Side-Scripting-Language I really recommend
570       you to install at least the packages CGI.pm (currently vers.  2.36),
571       HTML-Stream (1.40), libnet (1.0505) and libwww-perl (5.08).  When you
572       want to generate on-the-fly images as well, I recommend you to
573       additionally install at least GD (1.14) and Image-Size (2.3). The ePerl
574       interpreter in conjunction with these really sophisticated Perl 5
575       modules will provide you with maximum flexibility and functionality. In
576       other words: Make use of maximum Software Leverage in the hackers world
577       of Perl as great as possible.
578

OPTIONS

580       -d name=value
581           Sets a Perl variable in the package "main" which can be referenced
582           via $name or more explicitly via $main::name. The command
583
584             eperl -d name=value ..
585
586           is actually equivalent to having
587
588             <? $name = value; !>
589
590           at the beginning of inputfile. This option can occur more than
591           once.
592
593       -D name=value
594           Sets a environment variable which can be referenced via
595           $ENV{'variable'} inside the Perl blocks. The command
596
597             eperl -D name=value ..
598
599           is actually equivalent to
600
601             export name=value; eperl ...
602
603           but the advantage of this option is that it doesn't manipulate the
604           callers environment. This option can occur more than once.
605
606       -B begin_delimiter
607           Sets the Perl block begin delimiter string. Use this in conjunction
608           with "-E" to set different delimiters when using ePerl as an
609           offline HTML creation-language while still using it as an online
610           HTML scripting-language.  Default delimiters are "<?" and "!>" for
611           CGI modes and "<:" and ":>" for stand-alone Unix filtering mode.
612
613           There are a lot of possible variations you could choose: ""<:"" and
614           "":>"" (the default ePerl stand-alone filtering mode delimiters),
615           ""<?"" and ""!>"" (the default ePerl CGI interface mode
616           delimiters), ""<script language='ePerl'>"" and ""</script>""
617           (standard HTML scripting language style), ""<script
618           type="text/eperl">"" and ""</script>"" (forthcoming HTML3.2+ aka
619           Cougar style), ""<eperl>"" and ""</eperl>"" (HTML-like style),
620           ""<!--#eperl code='"" and ""' -->"" (NeoScript and SSI style) or
621           even ""<?"" and "">"" (PHP/FI style; but this no longer recommended
622           because it can lead to parsing problems. Should be used only for
623           backward compatibility to old ePerl versions 1.x).
624
625           The begin and end delimiters are searched case-insensitive.
626
627       -E end_delimiter
628           Sets the Perl block end delimiter string. See also option -B.
629
630       -i  Forces the begin and end delimiters to be searched case-
631           insensitive.  Use this when you are using delimiters like
632           ``"<ePerl>"..."</ePerl>"'' or other more textual ones.
633
634       -m mode
635           This forces ePerl to act in a specific runtime mode.  See above for
636           a detailed description of the three possible modes: Stand-alone
637           filter (mode="f", i.e. option -mf), CGI/1.1 interface mode
638           (mode="c", i.e. option -mc) or the NPH-CGI/1.1 interface mode
639           (mode="n", i.e. option -mn).
640
641       -o outputfile
642           Forces the output to be written to outputfile instead of STDOUT.
643           Use this option when using ePerl as a filter. The outputfile ``-''
644           sets STDOUT as the output handle explicitly. Notice that this file
645           is relative to the source file directory when the runtime mode is
646           forced to CGI or NPH-CGI.
647
648       -k  Forces ePerl to keep the current working directory from where it
649           was started.  Per default ePerl will change to the directory where
650           the file to be executed stays. This option is useful if you use
651           ePerl as an offline filter on a temporary file.
652
653       -x  This sets debug mode where ePerl outputs the internally created
654           Perl script to the console (/dev/tty) before executing it. Only for
655           debugging problems with the inputfile conversion.
656
657       -I directory
658           Specify a directory which is both used for "#include" and
659           "#sinclude" directives of the ePerl preprocessor and added to @INC
660           under runtime.  This option can occur more than once.
661
662       -P  Manually enables the special ePerl Preprocessor (see above). This
663           option is enabled for all CGI modes automatically.
664
665       -C  This enables the HTML entity conversion for ePerl blocks. This
666           option is automatically forced in CGI modes.
667
668           The solved problem here is the following: When you use ePerl as a
669           Server-Side-Scripting-Language for HTML pages and you edit your
670           ePerl source files via a HTML editor, the chance is high that your
671           editor translates some entered characters to HTML entities, for
672           instance ``"<"'' to ``"&lt;"''.  This leads to invalid Perl code
673           inside ePerl blocks, because the HTML editor has no knowledge about
674           ePerl blocks. Using this option the ePerl parser automatically
675           converts all entities found inside ePerl blocks back to plain
676           characters, so the Perl interpreter again receives valid code
677           blocks.
678
679       -L  This enables the line continuation character ``"\"'' (backslash)
680           outside ePerl blocks. With this option you can spread oneline-data
681           over more lines.  But use with care: This option changes your data
682           (outside ePerl blocks).  Usually ePerl really pass through all
683           surrounding data as raw data. With this option the newlines become
684           new semantics.
685
686       -T  This enabled Perl's Tainting mode where the Perl interpreter takes
687           special precautions called taint checks to prevent both obvious and
688           subtle traps.  See perlsec(1) for more details.
689
690       -w  This enables Warnings where the Perl interpreter produces some
691           lovely diagnostics. See perldiag(1) for more details.
692
693       -c  This runs a pure syntax check which is similar to ``"perl -c"''.
694
695       -r  This prints the internal ePerl README file to the console.
696
697       -l  This prints the internal ePerl LICENSE file to the console.
698
699       -v  This prints ePerl version information to the console.
700
701       -V  Same as option -v but additionally shows the Perl compilation
702           parameters.
703

ENVIRONMENT

705   Used Variables
706       "PATH_TRANSLATED"
707           This CGI/1.1 variable is used to determine the source file when
708           ePerl operates as a NPH-CGI/1.1 program under the environment of a
709           webserver.
710
711   Provided Variables
712       "SCRIPT_SRC_PATH"
713           The absolute pathname of the script. Use this when you want to
714           directly access the script from within itself, for instance to do
715           "stat()" and other calls.
716
717       "SCRIPT_SRC_PATH_DIR"
718           The directory part of "SCRIPT_SRC_PATH". Use this one when you want
719           to directly access other files residing in the same directory as
720           the script, for instance to read config files, etc.
721
722       "SCRIPT_SRC_PATH_FILE"
723           The filename part of "SCRIPT_SRC_PATH". Use this one when you need
724           the name of the script, for instance for relative self-references
725           through URLs.
726
727       "SCRIPT_SRC_URL"
728           The fully-qualified URL of the script. Use this when you need a URL
729           for self-reference.
730
731       "SCRIPT_SRC_URL_DIR"
732           The directory part of "SCRIPT_SRC_URL". Use this one when you want
733           to directly access other files residing in the same directory as
734           the script via the Web, for instance to reference images, etc.
735
736       "SCRIPT_SRC_URL_FILE"
737           The filename part of "SCRIPT_SRC_URL". Use this one when you need
738           the name of the script, for instance for relative self-references
739           through URLs.  Actually the same as "SCRIPT_SRC_PATH_FILE", but
740           provided for consistency.
741
742       "SCRIPT_SRC_SIZE"
743           The filesize of the script, in bytes.
744
745       "SCRIPT_SRC_MODIFIED"
746           The last modification time of the script, in seconds since 0 hours,
747           0 minutes, 0 seconds, January 1, 1970, Coordinated Universal Time.
748
749       "SCRIPT_SRC_MODIFIED_CTIME"
750           The last modification time of the script, in ctime(3) format
751           (``WDAY MMM DD HH:MM:SS YYYY\n'').
752
753       "SCRIPT_SRC_MODIFIED_ISOTIME"
754           The last modification time of the script, in ISO format
755           (``DD-MM-YYYY HH:MM'').
756
757       "SCRIPT_SRC_OWNER"
758           The username of the script owner.
759
760       "VERSION_INTERPRETER"
761           The ePerl identification string.
762
763       "VERSION_LANGUAGE"
764           The identification string of the used Perl interpreter library.
765
766   Provided Built-In Images
767       The following built-in images can be accessed via URL
768       "/url/to/nph-eperl/"NAME".gif":
769
770       "logo.gif"
771           The standard ePerl logo. Please do not include this one on your
772           website.
773
774       "powered.gif"
775           The ``powered by ePerl 2.2'' logo. Feel free to use this on your
776           website.
777

AUTHOR

779         Ralf S. Engelschall
780         rse@engelschall.com
781         www.engelschall.com
782

SEEALSO

784       Parse::ePerl(3), Apache::ePerl(3).
785
786       Web-References:
787
788         Perl:   perl(1),  http://www.perl.com/
789         ePerl:  eperl(1), http://www.ossp.org/pkg/tool/eperl/
790         Apache: httpd(8), http://www.apache.org/
791
792
793
794EN                                2019-07-26                          EPERL(1)
Impressum