Parse::ePerl(3pm)

1ePerl(3)              User Contributed Perl Documentation             ePerl(3)
2
3
4

NAME

6       Parse::ePerl - Perl interface to the ePerl parser
7

SYNOPSIS

9         use Parse::ePerl;
10
11         $rc = Parse::ePerl::Preprocess($p);
12         $rc = Parse::ePerl::Translate($p);
13         $rc = Parse::ePerl::Precompile($p);
14         $rc = Parse::ePerl::Evaluate($p);
15         $rc = Parse::ePerl::Expand($p);
16

DESCRIPTION

18       Parse::ePerl is the Perl 5 interface package to the functionality of
19       the ePerl parser (see eperl(1) for more details about the stand-alone
20       program). It directly uses the parser code from ePerl to translate a
21       bristled script into a plain Perl script and additionally provides
22       functions to precompile such scripts into P-code and evaluate those
23       scripts to a buffer.
24
25       All functions are parameterized via a hash reference $p which provide
26       the necessary parameters. The result is a return code $rc which indi‐
27       cates success (1) or failure (0).
28
29       PREPROCESSOR: $rc = Parse::ePerl::Preprocess($p)
30
31       This is the ePerl preprocessor which expands "#include" directives.
32       See eperl(1) for more details.
33
34       Possible parameters for $p:
35
36       Script
37           Scalar holding the input script in source format.
38
39       Result
40           Reference to scalar receiving the resulting script in bristled Perl
41           format.
42
43       BeginDelimiter
44           Scalar specifying the begin delimiter.  Default is ``"<:"''.
45
46       EndDelimiter
47           Scalar specifying the end delimiter.  Default is ``":>"''.
48
49       INC A reference to a list specifying include directories. Default is
50           "\@INC".
51
52       TRANSLATION: $rc = Parse::ePerl::Translate($p)
53
54       This is the actual ePerl parser, i.e. this function converts a bristled
55       ePerl-style script (provided in "$p-"{Script}> as a scalar) to a plain
56       Perl script. The resulting script is stored into a buffer provided via
57       a scalar reference in "$p-"{Result}>. The translation is directly done
58       by the original C function Bristled2Plain() from ePerl, so the result‐
59       ing script is exactly the same as with the stand-alone program eperl.
60
61       Possible parameters for $p:
62
63       Script
64           Scalar holding the input script in bristled format.
65
66       Result
67           Reference to scalar receiving the resulting script in plain Perl
68           format.
69
70       BeginDelimiter
71           Scalar specifying the begin delimiter.  Default is ``"<:"''.
72
73       EndDelimiter
74           Scalar specifying the end delimiter.  Default is ``":>"''.
75
76       CaseDelimiters
77           Boolean flag indicating if the delimiters are case-sensitive
78           (1=default) or case-insensitive (0).
79
80       Example: The following code
81
82         $script = <<'EOT';
83         foo
84         <: print "bar"; :>
85         quux
86         EOT
87
88         Parse::ePerl::Translate({
89             Script => $script,
90             Result => \$script,
91         });
92
93       translates the script in $script to the following plain Perl format:
94
95         print "foo\n";
96         print "bar"; print "\n";
97         print "quux\n";
98
99       COMPILATION: $rc = Parse::ePerl::Precompile($p);
100
101       This is an optional step between translation and evaluation where the
102       plain Perl script is compiled from ASCII representation to P-code (the
103       internal Perl bytecode). This step is used in rare cases only, for
104       instance from within Apache::ePerl(3) for caching purposes.
105
106       Possible parameters for $p:
107
108       Script
109           Scalar holding the input script in plain Perl format, usually the
110           result from a previous Parse::ePerl::Translate(3) call.
111
112       Result
113           Reference to scalar receiving the resulting code reference. This
114           code can be later directly used via the &$var construct or given to
115           the Parse::ePerl::Evaluate(3) function.
116
117       Error
118           Reference to scalar receiving possible error messages from the com‐
119           pilation (e.g.  syntax errors).
120
121       Cwd Directory to switch to while precompiling the script.
122
123       Name
124           Name of the script for informal references inside error messages.
125
126       Example: The following code
127
128         Parse::ePerl::Precompile({
129             Script => $script,
130             Result => \$script,
131         });
132
133       translates the plain Perl code (see above) in $script to a code refer‐
134       ence and stores the reference again in $script. The code later can be
135       either directly used via &$script instead of "eval($script)" or passed
136       to the Parse::ePerl::Evaluate(3) function.
137
138       EVALUATION: $rc = Parse::ePerl::Evaluate($p);
139
140       Beside Parse::ePerl::Translate(3) this is the second main function of
141       this package. It is intended to evaluate the result of
142       Parse::ePerl::Translate(3) in a ePerl-like environment, i.e. this func‐
143       tion tries to emulate the runtime environment and behavior of the pro‐
144       gram eperl. This actually means that it changes the current working
145       directory and evaluates the script while capturing data generated on
146       STDOUT/STDERR.
147
148       Possible parameters for $p:
149
150       Script
151           Scalar (standard case) or reference to scalar (compiled case) hold‐
152           ing the input script in plain Perl format or P-code, usually the
153           result from a previous Parse::ePerl::Translate(3) or
154           Parse::ePerl::Precompile(3) call.
155
156       Result
157           Reference to scalar receiving the resulting code reference.
158
159       Error
160           Reference to scalar receiving possible error messages from the
161           evaluation (e.g. runtime errors).
162
163       ENV Hash containing the environment for %ENV which should be used while
164           evaluating the script.
165
166       Cwd Directory to switch to while evaluating the script.
167
168       Name
169           Name of the script for informal references inside error messages.
170
171       Example: The following code
172
173         $script = <<'EOT';
174         print "foo\n";
175         print "bar"; print "\n";
176         print "quux\n";
177         EOT
178
179         Parse::ePerl::Evaluate({
180             Script => $script,
181             Result => \$script,
182         });
183
184       translates the script in $script to the following plain data:
185
186         foo
187         bar
188         quux
189
190       ONE-STEP EXPANSION: $rc = Parse::ePerl::Expand($p);
191
192       This function just combines, Parse::ePerl::Translate(3) and
193       Parse::ePerl::Evaluate(3) into one step. The parameters in $p are the
194       union of the possible parameters for both functions. This is intended
195       as a high-level interface for Parse::ePerl.
196

AUTHOR

198        Ralf S. Engelschall
199        rse@engelschall.com
200        www.engelschall.com
201

NAME

SYNOPSIS

DESCRIPTION

AUTHOR

SEE ALSO