1EPERL(1) Ralf S. Engelschall EPERL(1)
2
6 ePerl - Embedded Perl 5 Language
7
9 @V@
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
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 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 #!/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 you can write it now as an ePerl script:
46 #!/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 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 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 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 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 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 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 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 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 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 <: cmd; ...; cmd; :>
121 But when the last semicolon is missing it is automatically added by
123 ePerl, i.e.
124 <: cmd; ...; cmd :>
126 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 <: if (...) { _:>
134 foo
135 <: } else { _:>
136 bar
137 <: } :>
138 where you want to spread a Perl directive over more ePerl blocks.
140 5. Shorthand for "print"-only blocks.
142 Because most of the time ePerl is used just to interpolate
143 variables, e.g.
144 <: print $VARIABLE; :>
146 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 <:=$VARIABLE:>
154 Notice that the semicolon was also removed here, because it gets
156 automatically added (see above).
157 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 foo
165 <: $x = 1; :>
166 quux
167 the result is
169 foo
171 quux
173 because ePerl always preserves code around ePerl blocks, even just
175 newlines. But when you write
176 foo
178 <: $x = 1; :>//
179 quux
180 the result is
182 foo
184 quux
185 because the ``"//"'' deleted all stuff to the end of the line,
187 including the newline.
188 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 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 So, whenever your end delimiter also occurs inside Perl constructs
217 you have to escape it in any way.
218 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 Runtime Modes
230 ePerl can operate in three different runtime modes:
231 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 $ eperl [options] - < inputfile > outputfile
238 $ eperl [options] inputfile > outputfile
239 $ eperl [options] -o outputfile - < inputfile
240 $ eperl [options] -o outputfile inputfile
241 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 #!/path/to/eperl [options]
250 foo
251 <: print "bar"; :>
252 quux
253 Second, you can use ePerl in conjunction with the Bourne-Shell Here
255 Document technique from within you shell scripts:
256 #!/bin/sh
258 ...
259 eperl [options] - <<EOS
260 foo
261 <: print "quux"; :>
262 quux
263 EOS
264 ...
265 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 #!/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 See Parse::ePerl(3) for more details.
290 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 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 <? $url = "..";
306 print "Location: $url\n";
307 print "URI: $url\n\n"; !>
308 <html>
309 ...
310 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 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 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 #!/path/to/eperl -mc
329 Then rename the script from file.html to file.cgi and set its
331 execution bit via
332 $ mv file.html file.cgi
334 $ chmod a+rx file.cgi
335 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 Options +ExecCGI
341 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 AddHandler cgi-script .cgi
348 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 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 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 and creating a copy of the eperl program in your CGI-directory:
367 $ cp -p /path/to/eperl /path/to/apache/cgi-bin/eperl
369 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 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 $ export QUERY_STRING="key1=value1&key2=value2"
380 $ eperl -mc file.phtml
381 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 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 #!/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 As you expect this can be also used with the implicit Server-Side
410 Scripting Language technique. Put
411 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 into your httpd.conf and run the command
417 $ cp -p /path/to/eperl /path/to/apache/cgi-bin/nph-eperl
419 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 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 $ 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 or
433 $ 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 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 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 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 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 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 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 "#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 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 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 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 "#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 "#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 ``#if expr'' -> ``BD if (expr) { _ ED//''
533 ``#elsif expr'' -> ``BD } elsif (expr) { _ ED//''
534 ``#else'' -> ``BD } else { _ ED//''
535 ``#endif'' -> ``BD } _ ED//''
536 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 "#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 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 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 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 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
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 eperl -d name=value ..
585 is actually equivalent to having
587 <? $name = value; !>
589 at the beginning of inputfile. This option can occur more than
591 once.
592 -D name=value
594 Sets a environment variable which can be referenced via
595 $ENV{'variable'} inside the Perl blocks. The command
596 eperl -D name=value ..
598 is actually equivalent to
600 export name=value; eperl ...
602 but the advantage of this option is that it doesn't manipulate the
604 callers environment. This option can occur more than once.
605 -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 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 The begin and end delimiters are searched case-insensitive.
626 -E end_delimiter
628 Sets the Perl block end delimiter string. See also option -B.
629 -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 -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 -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 -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 -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 -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 -P Manually enables the special ePerl Preprocessor (see above). This
663 option is enabled for all CGI modes automatically.
664 -C This enables the HTML entity conversion for ePerl blocks. This
666 option is automatically forced in CGI modes.
667 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 ``"<"''. 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 -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 -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 -w This enables Warnings where the Perl interpreter produces some
691 lovely diagnostics. See perldiag(1) for more details.
692 -c This runs a pure syntax check which is similar to ``"perl -c"''.
694 -r This prints the internal ePerl README file to the console.
696 -l This prints the internal ePerl LICENSE file to the console.
698 -v This prints ePerl version information to the console.
700 -V Same as option -v but additionally shows the Perl compilation
702 parameters.
703
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 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 "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 "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 "SCRIPT_SRC_URL"
728 The fully-qualified URL of the script. Use this when you need a URL
729 for self-reference.
730 "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 "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 "SCRIPT_SRC_SIZE"
743 The filesize of the script, in bytes.
744 "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 "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 "SCRIPT_SRC_MODIFIED_ISOTIME"
754 The last modification time of the script, in ISO format
755 (``DD-MM-YYYY HH:MM'').
756 "SCRIPT_SRC_OWNER"
758 The username of the script owner.
759 "VERSION_INTERPRETER"
761 The ePerl identification string.
762 "VERSION_LANGUAGE"
764 The identification string of the used Perl interpreter library.
765 Provided Built-In Images
767 The following built-in images can be accessed via URL
768 "/url/to/nph-eperl/"NAME".gif":
769 "logo.gif"
771 The standard ePerl logo. Please do not include this one on your
772 website.
773 "powered.gif"
775 The ``powered by ePerl 2.2'' logo. Feel free to use this on your
776 website.
777
779 Ralf S. Engelschall
780 rse@engelschall.com
781 www.engelschall.com
782
784 Parse::ePerl(3), Apache::ePerl(3).
785 Web-References:
787 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/
791EN 2020-07-28 EPERL(1)