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

AUTHOR

194        Ralf S. Engelschall
195        rse@engelschall.com
196        www.engelschall.com
197

NAME

SYNOPSIS

DESCRIPTION

AUTHOR

SEE ALSO