1EPERL(1) Ralf S. Engelschall EPERL(1)
2
6 ePerl - Embedded Perl 5 Language
7
9 2.2.14 (02-Aug-1998)
10
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 eperl [-r] [-l] [-v] [-V]
17
19 Abstract
20 ePerl interprets an ASCII file bristled with Perl 5 program statements
22 by evaluating the Perl 5 code while passing through the plain ASCII
23 data. It can operate in various ways: As a stand-alone Unix filter or
24 integrated Perl 5 module for general file generation tasks and as a
25 powerful Webserver scripting language for dynamic HTML page program‐
26 ming.
27 Introduction
29 The eperl program is the Embedded Perl 5 Language interpreter. This
31 really is a full-featured Perl 5 interpreter, but with a different
32 calling environment and source file layout than the default Perl inter‐
33 preter (usually the executable perl or perl5 on most systems). It is
34 designed for general ASCII file generation with the philosophy of
35 embedding the Perl 5 program code into the ASCII data instead of the
36 usual way where you embed the ASCII data into a Perl 5 program (usually
37 by quoting the data and using them via "print" statements). So,
38 instead of writing a plain Perl script like
39 #!/path/to/perl
41 print "foo bar\n";
42 print "baz quux\n";
43 for ($i = 0; $i < 10; $i++) { print "foo #${i}\n"; }
44 print "foo bar\n";
45 print "baz quux\n";
46 you can write it now as an ePerl script:
48 #!/path/to/eperl
50 foo bar
51 baz quux
52 <: for ($i = 0; $i < 10; $i++) { print "foo #${i}\n"; } :>
53 foo bar
54 baz quux
55 Although the ePerl variant has a different source file layout, the
57 semantic is the same, i.e. both scripts create exactly the same result‐
58 ing data on "STDOUT".
59 Intention
61 ePerl is simply a glue code which combines the programming power of the
63 Perl 5 interpreter library with a tricky embedding technique. The
64 embedding trick is this: it converts the source file into a valid Perl
65 script which then gets entirely evaluated by only one internal instance
66 of the Perl 5 interpreter. To achieve this, ePerl translates all plain
67 code into (escaped) Perl 5 strings placed into print constructs while
68 passing through all embedded native Perl 5 code. As you can see, ePerl
69 itself does exactly the same internally, a silly programmer had to do
70 when writing a plain Perl generation script.
71 Due to the nature of such bristled code, ePerl is really the better
73 attempt when the generated ASCII data contains really more static as
74 dynamic data. Or in other words: Use ePerl if you want to keep the most
75 of the generated ASCII data in plain format while just programming some
76 bristled stuff. Do not use it when generating pure dynamic data. There
77 it brings no advantage to the ordinary program code of a plain Perl
78 script. So, the static part should be at least 60% or the advantage
79 becomes a disadvantage.
80 ePerl in its origin was actually designed for an extreme situation: as
82 a webserver scripting-language for on-the-fly HTML page generation.
83 Here you have the typical case that usually 90% of the data consists of
84 pure static HTML tags and plain ASCII while just the remaining 10% are
85 programming constructs which dynamically generate more markup code.
86 This is the reason why ePerl beside its standard Unix filtering run‐
87 time-mode also supports the CGI/1.1 and NPH-CGI/1.1 interfaces.
88 Embedded Perl Syntax
90 Practically you can put any valid Perl constructs inside the ePerl
92 blocks the used Perl 5 interpreter library can evaluate. But there are
93 some important points you should always remember and never forget when
94 using ePerl:
95 1. Delimiters are always discarded.
97 Trivially to say, but should be mentioned at least once. The ePerl
98 block delimiters are always discarded and are only necessary for
99 ePerl to recognize the embedded Perl constructs. They are never
100 passed to the final output.
101 2. Generated content has to go to "STDOUT".
103 Although you can define subroutines, calculate some data, etc.
104 inside ePerl blocks only data which is explicitly written to the
105 "STDOUT" filehandle is expanded. In other words: When an ePerl
106 block does not generate content on "STDOUT", it is entirely
107 replaced by an empty string in the final output. But when content
108 is generated it is put at the point of the ePerl block in the final
109 output. Usually contents is generated via pure "print" constructs
110 which implicitly use "STDOUT" when no filehandle is given.
111 3. Generated content on "STDERR" always leads to an error.
113 Whenever content is generated on the "STDERR" filehandle, ePerl
114 displays an error (including the STDERR content). Use this to exit
115 on errors while passing errors from ePerl blocks to the calling
116 environment.
117 4. Last semicolon.
119 Because of the following point 6 (see below) and the fact that most
120 of the users don't have the internal ePerl block translations in
121 mind, ePerl is smart about the last semicolon. Usually every ePerl
122 block has to end with the semicolon of the last command.
123 <: cmd; ...; cmd; :>
125 But when the last semicolon is missing it is automatically added by
127 ePerl, i.e.
128 <: cmd; ...; cmd :>
130 is also correct syntax. But sometimes it is necessary to force
132 ePerl not to add the semicolon. Then you can add a ``"_"'' (under‐
133 score) as the last non-whitespace character in the block to force
134 ePerl to leave the final semicolon. Use this for constructs like
135 the following
136 <: if (...) { _:>
138 foo
139 <: } else { _:>
140 bar
141 <: } :>
142 where you want to spread a Perl directive over more ePerl blocks.
144 5. Shorthand for "print"-only blocks.
146 Because most of the time ePerl is used just to interpolate vari‐
147 ables, e.g.
148 <: print $VARIABLE; :>
150 it is useful to provide a shortcut for this kind of constructs. So
152 ePerl provides a shortcut via the character '='. When it immedi‐
153 ately (no whitespaces allowed here) follows the begin delimiter of
154 an ePerl block a "print" statement is implicitly generated, i.e.
155 the above block is equivalent to
156 <:=$VARIABLE:>
158 Notice that the semicolon was also removed here, because it gets
160 automatically added (see above).
161 6. Special EndOfLine discard command for ePerl blocks.
163 ePerl provides a special discard command named ``"//"'' which dis‐
164 cards all data up-to and including the following newline character
165 when directly followed an end block delimiter. Usually when you
166 write
167 foo
169 <: $x = 1; :>
170 quux
171 the result is
173 foo
175 quux
177 because ePerl always preserves code around ePerl blocks, even just
179 newlines. But when you write
180 foo
182 <: $x = 1; :>//
183 quux
184 the result is
186 foo
188 quux
189 because the ``"//"'' deleted all stuff to the end of the line,
191 including the newline.
192 7. Restrictions in parsing.
194 Every program has its restrictions, ePerl too. Its handicap is that
195 Perl is not only a rich language, it is a horrible one according to
196 parsing its constructs. Perhaps you know the phrase ,,Only perl can
197 parse Perl''. Think about it. The implication of this is that
198 ePerl never tries to parse the ePerl blocks itself. It entirely
199 relies on the Perl interpreter library, because it is the only
200 instance which can do this without errors. But the problem is that
201 ePerl at least has to recognize the begin and end positions of
202 those ePerl blocks.
203 There are two ways: It can either look for the end delimiter while
205 parsing but at least recognize quoted strings (where the end delim‐
206 iter gets treated as pure data). Or it can just move forward to the
207 next end delimiter and say that it have not occur inside Perl con‐
208 structs. In ePerl 2.0 the second one was used, while in ePerl 2.1
209 the first one was taken because a lot of users wanted it this way
210 while using bad end delimiters like ``">"''. But actually the
211 author has again revised its opinion and decided to finally use the
212 second approach which is used since ePerl 2.2 now. Because while
213 the first one allows more trivial delimiters (which itself is not a
214 really good idea), it fails when constructs like ``"m⎪"[^"]+"⎪"''
215 etc. are used inside ePerl blocks. And it is easier to escape end
216 delimiters inside Perl constructs (for instance via backslashes in
217 quoted strings) than rewrite complex Perl constructs to use even
218 number of quotes.
219 So, whenever your end delimiter also occurs inside Perl constructs
221 you have to escape it in any way.
222 8. HTML entity conversion.
224 Because one of ePerl's usage is as a server-side scripting-language
225 for HTML pages, there is a common problem in conjunction with HTML
226 editors. They cannot know ePerl blocks, so when you enter those
227 blocks inside the editors they usually encode some characters with
228 the corresponding HTML entities. The problem is that this encoding
229 leads to invalid Perl code. ePerl provides the option -C for decod‐
230 ing these entities which is automatically turned on in CGI modes.
231 See description below under option -C for more details.
232 Runtime Modes
234 ePerl can operate in three different runtime modes:
236 Stand-alone Unix filter mode
238 This is the default operation mode when used as a generation tool
239 from the Unix shell or as a batch-processing tool from within other
240 programs or scripts:
241 $ eperl [options] - < inputfile > outputfile
243 $ eperl [options] inputfile > outputfile
244 $ eperl [options] -o outputfile - < inputfile
245 $ eperl [options] -o outputfile inputfile
246 As you can see, ePerl can be used in any combination of STDIO and
248 external files. Additionally there are two interesting variants of
249 using this mode. First you can use ePerl in conjunction with the
250 Unix Shebang magic technique to implicitly select it as the inter‐
251 preter for your script similar to the way you are used to with the
252 plain Perl interpreter:
253 #!/path/to/eperl [options]
255 foo
256 <: print "bar"; :>
257 quux
258 Second, you can use ePerl in conjunction with the Bourne-Shell Here
260 Document technique from within you shell scripts:
261 #!/bin/sh
263 ...
264 eperl [options] - <<EOS
265 foo
266 <: print "quux"; :>
267 quux
268 EOS
269 ...
270 And finally you can use ePerl directly from within Perl programs by
272 the use of the Parse::ePerl(3) package (assuming that you have
273 installed this also; see file INSTALL inside the ePerl distribution
274 for more details):
275 #!/path/to/perl
277 ...
278 use Parse::ePerl;
279 ...
280 $script = <<EOT;
281 foo
282 <: print "quux"; :>
283 quux
284 EOT
285 ...
286 $result = Parse::ePerl::Expand({
287 Script => $script,
288 Result => \$result,
289 });
290 ...
291 print $result;
292 ...
293 See Parse::ePerl(3) for more details.
295 CGI/1.1 compliant interface mode
297 This is the runtime mode where ePerl uses the CGI/1.1 interface of
298 a webserver when used as a Server-Side Scripting Language on the
299 Web. ePerl enters this mode automatically when the CGI/1.1 environ‐
300 ment variable "PATH_TRANSLATED" is set and its or the scripts file‐
301 name does not begin with the NPH prefix ``nph-''. In this runtime
302 mode it prefixes the resulting data with HTTP/1.0 (default) or
303 HTTP/1.1 (if identified by the webserver) compliant response header
304 lines.
305 ePerl also recognizes HTTP header lines at the beginning of the
307 scripts generated data, i.e. for instance you can generate your own
308 HTTP headers like
309 <? $url = "..";
311 print "Location: $url\n";
312 print "URI: $url\n\n"; !>
313 <html>
314 ...
315 But notice that while you can output arbitrary headers, most web‐
317 servers restrict the headers which are accepted via the CGI/1.1
318 interface. Usually you can provide only a few specific HTTP headers
319 like "Location" or "Status". If you need more control you have to
320 use the NPH-CGI/1.1 interface mode.
321 Additionally ePerl provides a useful feature in this mode: It can
323 switch its UID/GID to the owner of the script if it runs as a Unix
324 SetUID program (see below under Security and the option ``u+s'' of
325 chmod(1)).
326 There are two commonly known ways of using this CGI/1.1 interface
328 mode on the Web. First, you can use it to explicitly transform
329 plain HTML files into CGI/1.1 scripts via the Shebang technique
330 (see above). For an Apache webserver just put the following line as
331 the first line of the file:
332 #!/path/to/eperl -mc
334 Then rename the script from file.html to file.cgi and set its exe‐
336 cution bit via
337 $ mv file.html file.cgi
339 $ chmod a+rx file.cgi
340 Now make sure that Apache accepts file.cgi as a CGI program by
342 enabling CGI support for the directory where file.cgi resides. For
343 this add the line
344 Options +ExecCGI
346 to the .htaccess file in this directory. Finally make sure that
348 Apache really recognizes the extension .cgi. Perhaps you addition‐
349 ally have to add the following line to your httpd.conf file:
350 AddHandler cgi-script .cgi
352 Now you can use file.cgi instead of file.html and make advantage of
354 the achieved programming capability by bristling file.cgi with your
355 Perl blocks (or the transformation into a CGI script would be use‐
356 less).
357 Alternatively (or even additionally) a webmaster can enable ePerl
359 support in a more seamless way by configuring ePerl as a real
360 implicit server-side scripting language. This is done by assigning
361 a MIME-type to the various valid ePerl file extensions and forcing
362 all files with this MIME-type to be internally processed via the
363 ePerl interpreter. You can accomplish this for Apache by adding the
364 following to your httpd.conf file
365 AddType application/x-httpd-eperl .phtml .eperl .epl
367 Action application/x-httpd-eperl /internal/cgi/eperl
368 ScriptAlias /internal/cgi /path/to/apache/cgi-bin
369 and creating a copy of the eperl program in your CGI-directory:
371 $ cp -p /path/to/eperl /path/to/apache/cgi-bin/eperl
373 Now all files with the extensions .phtml, .eperl and .epl are auto‐
375 matically processed by the ePerl interpreter. There is no need for
376 a Shebang line or any locally enabled CGI mode.
377 One final hint: When you want to test your scripts offline, just
379 run them with forced CGI/1.1 mode from your shell. But make sure
380 you prepare all environment variables your script depends on, e.g.
381 "QUERY_STRING" or "PATH_INFO".
382 $ export QUERY_STRING="key1=value1&key2=value2"
384 $ eperl -mc file.phtml
385 NPH-CGI/1.1 compliant interface mode
387 This runtime mode is a special variant of the CGI/1.1 interface
388 mode, because most webservers (e.g. Apache) provide it for special
389 purposes. It is known as Non-Parsed-Header (NPH) CGI/1.1 mode and
390 is usually used by the webserver when the filename of the CGI pro‐
391 gram is prefixed with ``"nph-"''. In this mode the webserver does
392 no processing on the HTTP response headers and no buffering of the
393 resulting data, i.e. the CGI program actually has to provide a com‐
394 plete HTTP response itself. The advantage is that the program can
395 generate arbitrary HTTP headers or MIME-encoded multi-block mes‐
396 sages.
397 So, above we have renamed the file to file.cgi which restricted us
399 a little bit. When we alternatively rename file.html to
400 nph-file.cgi and force the NPH-CGI/1.1 interface mode via option
401 -mn then this file becomes a NPH-CGI/1.1 compliant program under
402 Apache and other webservers. Now our script can provide its own
403 HTTP response (it need not, because when absent ePerl provides a
404 default one for it).
405 #!/path/to/bin/eperl -mn
407 <? print "HTTP/1.0 200 Ok\n";
408 print "X-MyHeader: Foo Bar Quux\n";
409 print "Content-type: text/html\n\n";
410 <html>
411 ...
412 As you expect this can be also used with the implicit Server-Side
414 Scripting Language technique. Put
415 AddType application/x-httpd-eperl .phtml .eperl .epl
417 Action application/x-httpd-eperl /internal/cgi/nph-eperl
418 ScriptAlias /internal/cgi /path/to/apache/cgi-bin
419 into your httpd.conf and run the command
421 $ cp -p /path/to/eperl /path/to/apache/cgi-bin/nph-eperl
423 from your shell. This is the preferred way of using ePerl as a
425 Server-Side Scripting Language, because it provides most flexibil‐
426 ity.
427 Security
429 When you are installing ePerl as a CGI/1.1 or NPH-CGI/1.1 compliant
431 program (see above for detailed description of these modes) via
432 $ cp -p /path/to/eperl /path/to/apache/cgi-bin/eperl
434 $ chown root /path/to/apache/cgi-bin/eperl
435 $ chmod u+s /path/to/apache/cgi-bin/eperl
436 or
438 $ cp -p /path/to/eperl /path/to/apache/cgi-bin/nph-eperl
440 $ chown root /path/to/apache/cgi-bin/nph-eperl
441 $ chmod u+s /path/to/apache/cgi-bin/nph-eperl
442 i.e. with SetUID bit enabled for the root user, ePerl can switch to the
444 UID/GID of the scripts owner. Although this is a very useful feature
445 for script programmers (because one no longer need to make auxiliary
446 files world-readable and temporary files world-writable!), it can be to
447 risky for you when you are paranoid about security of SetUID programs.
448 If so just don't install ePerl with enabled SetUID bit! This is the
449 reason why ePerl is per default only installed as a Stand-Alone Unix
450 filter which never needs this feature.
451 For those of us who decided that this feature is essential for them
453 ePerl tries really hard to make it secure. The following steps have to
454 be successfully passed before ePerl actually switches its UID/GID (in
455 this order):
456 1. The script has to match the following extensions:
458 .html, .phtml, .ephtml, .epl, .pl, .cgi
459 2. The UID of the calling process has to be a valid UID,
460 i.e. it has to be found in the systems password file
461 3. The UID of the calling process has to match the
462 following users: root, nobody
463 4. The UID of the script owner has to be a valid UID,
464 i.e. it has to be found in the systems password file
465 5. The GID of the script group has to be a valid GID,
466 i.e. it has to be found in the systems group file
467 6. The script has to stay below or in the owners homedir
468 IF ONLY ONE OF THOSE STEPS FAIL, NO UID/GID SWITCHING TAKES PLACE!.
470 Additionally (if "DO_ON_FAILED_STEP" was defined as "STOP_AND_ERROR" in
471 eperl_security.h - not per default defined this way!) ePerl can totally
472 stop processing and display its error page. This is for the really
473 paranoid webmasters. Per default when any step failed the UID/GID
474 switching is just disabled, but ePerl goes on with processing. Alterna‐
475 tively you can disable some steps at compile time. See eperl_secu‐
476 rity.h.
477 Also remember that ePerl always eliminates the effective UID/GID, inde‐
479 pendent of the runtime mode and independent if ePerl has switched to
480 the UID/GID of the owner. For security reasons, the effective UID/GID
481 is always destroyed before the script is executed.
482 ePerl Preprocessor
484 ePerl provides an own preprocessor similar to CPP in style which is
486 either enabled manually via option -P or automatically when ePerl runs
487 in (NPH-)CGI mode. The following directives are supported:
488 "#include path"
490 This directive is an include directive which can be used to include
491 really any stuff, but was actually designed to be used to include
492 other ePerl source files. The path can be either a relative or
493 absolute path for the local filesystem or a fully qualified HTTP
494 URL.
495 In case of the absolute path the file is directly accessed on the
497 filesystem, while the relative path is first searched in the cur‐
498 rent working directory and then in all directories specified via
499 option -I. In the third case (HTTP URL) the file is retrieves via a
500 HTTP/1.0 request on the network. Here HTTP redirects (response
501 codes 301 and 302) are supported, too.
502 Notice: While ePerl strictly preserves the line numbers when trans‐
504 lating the bristled ePerl format to plain Perl format, the ePerl
505 preprocessor can't do this (because its a preprocessor which
506 expands) for this directive. So, whenever you use "#include",
507 remember that line numbers in error messages are wrong.
508 Also notice one important security aspect: Because you can include
510 any stuff as it is provided with this directive, use it only for
511 stuff which is under your direct control. Don't use this directive
512 to include foreign data, at least not from external webservers. For
513 instance say you have a ePerl page with "#include http://www.for‐
514 eigner.com/nice-page.html" and at the next request of this page
515 your filesystem is lost! Why? Because the foreigner recognizes that
516 you include his page and are using ePerl and just put a simple
517 ``"<? system("rm -rf /"); !>"'' in his page. Think about it.
518 NEVER USE #INCLUDE FOR ANY DATA WHICH IS NOT UNDER YOUR OWN CON‐
519 TROL. Instead always use "#sinclude" for such situations.
520 "#sinclude path"
522 This is the secure variant of "#include" where after reading the
523 data from path all ePerl begin and end delimiters are removed. So
524 risky ePerl blocks lost their meaning and are converted to plain
525 text. Always use this directive when you want to include data which
526 is not under your own control.
527 "#if expr", "#elsif expr", "#else", "#endif"
529 These implement a CPP-style "#if-[#else-]#endif" construct, but
530 with a Perl semantic. While the other directives are real pre‐
531 processor commands which are evaluated at the preprocessing step,
532 this construct is actually just transformed into a low-level ePerl
533 construct, so it is not actually evaluated at the preprocessing
534 step. It is just a handy shortcut for the following (where BD is
535 the currently used begin delimiter and ED the end delimiter):
536 ``#if expr'' -> ``BD if (expr) { _ ED//''
538 ``#elsif expr'' -> ``BD } elsif (expr) { _ ED//''
539 ``#else'' -> ``BD } else { _ ED//''
540 ``#endif'' -> ``BD } _ ED//''
541 The advantage of this unusual aproach is that the if-condition
543 really can be any valid Perl expression which provides maximum
544 flexibility. The disadvantage is that you cannot use the if-con‐
545 struct to make real preprocessing decisions. As you can see, the
546 design goal was just to provide a shorthand for the more compli‐
547 cated Perl constructs.
548 "#c"
550 This is the comment directive which just discards all data up to
551 and including the newline character. Use this one to comment out
552 any stuff, even other preprocessor directives.
553 Provided Functionality
555 Up to know you've understand that ePerl provides a nice facility to
557 embed Perl code into any ASCII data. But now the typical question is:
558 Which Perl code can be put into these ePerl blocks and does ePerl pro‐
559 vide any special functionality inside these ePerl blocks?
560 The answers are: First, you can put really any Perl code into the ePerl
562 blocks which are valid to the Perl interpreter ePerl was linked with.
563 Second, ePerl does not provide any special functionality inside these
564 ePerl blocks, because Perl is already sophisticated enough ;-)
565 The implication of this is: Because you can use any valid Perl code you
567 can make use of all available Perl 5 modules, even those ones which use
568 shared objects (because ePerl is a Perl interpreter, including
569 DynaLoader support). So, browse to the Comprehensive Perl Archive Net‐
570 work (CPAN) via http://www.perl.com/perl/CPAN and grab your favorite
571 packages which can make your life easier (both from within plain Perl
572 scripts and ePerl scripts) and just use the construct ``"use name;"''
573 in any ePerl block to use them from within ePerl.
574 When using ePerl as a Server-Side-Scripting-Language I really recommend
576 you to install at least the packages CGI.pm (currently vers. 2.36),
577 HTML-Stream (1.40), libnet (1.0505) and libwww-perl (5.08). When you
578 want to generate on-the-fly images as well, I recommend you to addi‐
579 tionally install at least GD (1.14) and Image-Size (2.3). The ePerl
580 interpreter in conjunction with these really sophisticated Perl 5 mod‐
581 ules will provide you with maximum flexibility and functionality. In
582 other words: Make use of maximum Software Leverage in the hackers world
583 of Perl as great as possible.
584
586 -d name=value
587 Sets a Perl variable in the package "main" which can be referenced
588 via $name or more explicitly via $main::name. The command
589 eperl -d name=value ..
591 is actually equivalent to having
593 <? $name = value; !>
595 at the beginning of inputfile. This option can occur more than
597 once.
598 -D name=value
600 Sets a environment variable which can be referenced via $ENV{'vari‐
601 able'} inside the Perl blocks. The command
602 eperl -D name=value ..
604 is actually equivalent to
606 export name=value; eperl ...
608 but the advantage of this option is that it doesn't manipulate the
610 callers environment. This option can occur more than once.
611 -B begin_delimiter
613 Sets the Perl block begin delimiter string. Use this in conjunction
614 with "-E" to set different delimiters when using ePerl as an off‐
615 line HTML creation-language while still using it as an online HTML
616 scripting-language. Default delimiters are "<?" and "!>" for CGI
617 modes and "<:" and ":>" for stand-alone Unix filtering mode.
618 There are a lot of possible variations you could choose: ""<:"" and
620 "":>"" (the default ePerl stand-alone filtering mode delimiters),
621 ""<?"" and ""!>"" (the default ePerl CGI interface mode delim‐
622 iters), ""<script language='ePerl'>"" and ""</script>"" (standard
623 HTML scripting language style), ""<script type="text/eperl">"" and
624 ""</script>"" (forthcoming HTML3.2+ aka Cougar style), ""<eperl>""
625 and ""</eperl>"" (HTML-like style), ""<!--#eperl code='"" and ""'
626 -->"" (NeoScript and SSI style) or even ""<?"" and "">"" (PHP/FI
627 style; but this no longer recommended because it can lead to pars‐
628 ing problems. Should be used only for backward compatibility to old
629 ePerl versions 1.x).
630 The begin and end delimiters are searched case-insensitive.
632 -E end_delimiter
634 Sets the Perl block end delimiter string. See also option -B.
635 -i Forces the begin and end delimiters to be searched case-insensi‐
637 tive. Use this when you are using delimiters like
638 ``"<ePerl>"..."</ePerl>"'' or other more textual ones.
639 -m mode
641 This forces ePerl to act in a specific runtime mode. See above for
642 a detailed description of the three possible modes: Stand-alone
643 filter (mode="f", i.e. option -mf), CGI/1.1 interface mode
644 (mode="c", i.e. option -mc) or the NPH-CGI/1.1 interface mode
645 (mode="n", i.e. option -mn).
646 -o outputfile
648 Forces the output to be written to outputfile instead of STDOUT.
649 Use this option when using ePerl as a filter. The outputfile ``-''
650 sets STDOUT as the output handle explicitly. Notice that this file
651 is relative to the source file directory when the runtime mode is
652 forced to CGI or NPH-CGI.
653 -k Forces ePerl to keep the current working directory from where it
655 was started. Per default ePerl will change to the directory where
656 the file to be executed stays. This option is useful if you use
657 ePerl as an offline filter on a temporary file.
658 -x This sets debug mode where ePerl outputs the internally created
660 Perl script to the console (/dev/tty) before executing it. Only for
661 debugging problems with the inputfile conversion.
662 -I directory
664 Specify a directory which is both used for "#include" and "#sin‐
665 clude" directives of the ePerl preprocessor and added to @INC under
666 runtime. This option can occur more than once.
667 -P Manually enables the special ePerl Preprocessor (see above). This
669 option is enabled for all CGI modes automatically.
670 -C This enables the HTML entity conversion for ePerl blocks. This
672 option is automatically forced in CGI modes.
673 The solved problem here is the following: When you use ePerl as a
675 Server-Side-Scripting-Language for HTML pages and you edit your
676 ePerl source files via a HTML editor, the chance is high that your
677 editor translates some entered characters to HTML entities, for
678 instance ``"<"'' to ``"<"''. This leads to invalid Perl code
679 inside ePerl blocks, because the HTML editor has no knowledge about
680 ePerl blocks. Using this option the ePerl parser automatically con‐
681 verts all entities found inside ePerl blocks back to plain charac‐
682 ters, so the Perl interpreter again receives valid code blocks.
683 -L This enables the line continuation character ``"\"'' (backslash)
685 outside ePerl blocks. With this option you can spread oneline-data
686 over more lines. But use with care: This option changes your data
687 (outside ePerl blocks). Usually ePerl really pass through all sur‐
688 rounding data as raw data. With this option the newlines become new
689 semantics.
690 -T This enabled Perl's Tainting mode where the Perl interpreter takes
692 special precautions called taint checks to prevent both obvious and
693 subtle traps. See perlsec(1) for more details.
694 -w This enables Warnings where the Perl interpreter produces some
696 lovely diagnostics. See perldiag(1) for more details.
697 -c This runs a pure syntax check which is similar to ``"perl -c"''.
699 -r This prints the internal ePerl README file to the console.
701 -l This prints the internal ePerl LICENSE file to the console.
703 -v This prints ePerl version information to the console.
705 -V Same as option -v but additionally shows the Perl compilation
707 parameters.
708
710 Used Variables
711 "PATH_TRANSLATED"
713 This CGI/1.1 variable is used to determine the source file when
714 ePerl operates as a NPH-CGI/1.1 program under the environment of a
715 webserver.
716 Provided Variables
718 "SCRIPT_SRC_PATH"
720 The absolute pathname of the script. Use this when you want to
721 directly access the script from within itself, for instance to do
722 "stat()" and other calls.
723 "SCRIPT_SRC_PATH_DIR"
725 The directory part of "SCRIPT_SRC_PATH". Use this one when you want
726 to directly access other files residing in the same directory as
727 the script, for instance to read config files, etc.
728 "SCRIPT_SRC_PATH_FILE"
730 The filename part of "SCRIPT_SRC_PATH". Use this one when you need
731 the name of the script, for instance for relative self-references
732 through URLs.
733 "SCRIPT_SRC_URL"
735 The fully-qualified URL of the script. Use this when you need a URL
736 for self-reference.
737 "SCRIPT_SRC_URL_DIR"
739 The directory part of "SCRIPT_SRC_URL". Use this one when you want
740 to directly access other files residing in the same directory as
741 the script via the Web, for instance to reference images, etc.
742 "SCRIPT_SRC_URL_FILE"
744 The filename part of "SCRIPT_SRC_URL". Use this one when you need
745 the name of the script, for instance for relative self-references
746 through URLs. Actually the same as "SCRIPT_SRC_PATH_FILE", but
747 provided for consistency.
748 "SCRIPT_SRC_SIZE"
750 The filesize of the script, in bytes.
751 "SCRIPT_SRC_MODIFIED"
753 The last modification time of the script, in seconds since 0 hours,
754 0 minutes, 0 seconds, January 1, 1970, Coordinated Universal Time.
755 "SCRIPT_SRC_MODIFIED_CTIME"
757 The last modification time of the script, in ctime(3) format
758 (``WDAY MMM DD HH:MM:SS YYYY\n'').
759 "SCRIPT_SRC_MODIFIED_ISOTIME"
761 The last modification time of the script, in ISO format
762 (``DD-MM-YYYY HH:MM'').
763 "SCRIPT_SRC_OWNER"
765 The username of the script owner.
766 "VERSION_INTERPRETER"
768 The ePerl identification string.
769 "VERSION_LANGUAGE"
771 The identification string of the used Perl interpreter library.
772 Provided Built-In Images
774 The following built-in images can be accessed via URL
776 "/url/to/nph-eperl/"NAME".gif":
777 "logo.gif"
779 The standard ePerl logo. Please do not include this one on your
780 website.
781 "powered.gif"
783 The ``powered by ePerl 2.2'' logo. Feel free to use this on your
784 website.
785
787 Ralf S. Engelschall
788 rse@engelschall.com
789 www.engelschall.com
790
792 Parse::ePerl(3), Apache::ePerl(3).
793 Web-References:
795 Perl: perl(1), http://www.perl.com/
797 ePerl: eperl(1), http://www.ossp.org/pkg/tool/eperl/
798 Apache: httpd(8), http://www.apache.org/
799EN 2007-04-17 EPERL(1)