1CGI::Compile(3pm) User Contributed Perl Documentation CGI::Compile(3pm)
2
3
4
6 CGI::Compile - Compile .cgi scripts to a code reference like
7 ModPerl::Registry
8
10 use CGI::Compile;
11 my $sub = CGI::Compile->compile("/path/to/script.cgi");
12
14 CGI::Compile is a utility to compile CGI scripts into a code reference
15 that can run many times on its own namespace, as long as the script is
16 ready to run on a persistent environment.
17
18 NOTE: for best results, load CGI::Compile before any modules used by
19 your CGIs.
20
22 Combined with CGI::Emulate::PSGI, your CGI script can be turned into a
23 persistent PSGI application like:
24
25 use CGI::Emulate::PSGI;
26 use CGI::Compile;
27
28 my $cgi_script = "/path/to/foo.cgi";
29 my $sub = CGI::Compile->compile($cgi_script);
30 my $app = CGI::Emulate::PSGI->handler($sub);
31
32 # $app is a PSGI application
33
35 If your CGI script has a subroutine that references the lexical scope
36 variable outside the subroutine, you'll see warnings such as:
37
38 Variable "$q" is not available at ...
39 Variable "$counter" will not stay shared at ...
40
41 This is due to the way this module compiles the whole script into a big
42 "sub". To solve this, you have to update your code to pass around the
43 lexical variables, or replace "my" with "our". See also
44 <http://perl.apache.org/docs/1.0/guide/porting.html#The_First_Mystery>
45 for more details.
46
48 new
49 Does not need to be called, you only need to call it if you want to set
50 your own "namespace_root" for the generated packages into which the
51 CGIs are compiled into.
52
53 Otherwise you can just call "compile" as a class method and the object
54 will be instantiated with a "namespace_root" of "CGI::Compile::ROOT".
55
56 You can also set "return_exit_val", see "RETURN CODE" for details.
57
58 Example:
59
60 my $compiler = CGI::Compile->new(namespace_root => 'My::CGIs');
61 my $cgi = $compiler->compile('/var/www/cgi-bin/my.cgi');
62
63 compile
64 Takes either a path to a perl CGI script or a source code and some
65 other optional parameters and wraps it into a coderef for execution.
66
67 Can be called as either a class or instance method, see "new" above.
68
69 Parameters:
70
71 · $cgi_script
72
73 Path to perl CGI script file or a scalar reference that contains
74 the source code of CGI script, required.
75
76 · $package
77
78 Optional, package to install the script into, defaults to the path
79 parts of the script joined with "_", and all special characters
80 converted to "_%2x", prepended with "CGI::Compile::ROOT::".
81
82 E.g.:
83
84 /var/www/cgi-bin/foo.cgi
85
86 becomes:
87
88 CGI::Compile::ROOT::var_www_cgi_2dbin_foo_2ecgi
89
90 Returns:
91
92 · $coderef
93
94 $cgi_script or $$code compiled to coderef.
95
97 ARGUMENTS
98 Things like the query string and form data should generally be in the
99 appropriate environment variables that things like CGI expect.
100
101 You can also pass arguments to the generated coderef, they will be
102 locally aliased to @_ and @ARGV.
103
104 "BEGIN" and "END" blocks
105 "BEGIN" blocks are called once when the script is compiled. "END"
106 blocks are called when the Perl interpreter is unloaded.
107
108 This may cause surprising effects. Suppose, for instance, a script that
109 runs in a forking web server and is loaded in the parent process. "END"
110 blocks will be called once for each worker process and another time for
111 the parent process while "BEGIN" blocks are called only by the parent
112 process.
113
114 %SIG
115 The %SIG hash is preserved meaning the script can change signal
116 handlers at will. The next invocation gets a pristine %SIG again.
117
118 "exit" and exceptions
119 Calls to "exit" are intercepted and converted into exceptions. When the
120 script calls "exit 19" and exception is thrown and $@ contains a
121 reference pointing to the array
122
123 ["EXIT\n", 19]
124
125 Naturally, "$^S" in perlvar (exceptions being caught) is always "true"
126 during script runtime.
127
128 If you really want to exit the process call "CORE::exit" or set
129 $CGI::Compile::USE_REAL_EXIT to true before calling exit:
130
131 $CGI::Compile::USE_REAL_EXIT = 1;
132 exit 19;
133
134 Other exceptions are propagated out of the generated coderef. The
135 coderef's caller is responsible to catch them or the process will exit.
136
137 Return Code
138 The generated coderef's exit value is either the parameter that was
139 passed to "exit" or the value of the last statement of the script. The
140 return code is converted into an integer.
141
142 On a 0 exit, the coderef will return 0.
143
144 On an explicit non-zero exit, by default an exception will be thrown of
145 the form:
146
147 exited nonzero: <n>
148
149 where "n" is the exit value.
150
151 This only happens for an actual call to "exit" in perfunc, not if the
152 last statement value is non-zero, which will just be returned from the
153 coderef.
154
155 If you would prefer that explicit non-zero exit values are returned,
156 rather than thrown, pass:
157
158 return_exit_val => 1
159
160 in your call to "new".
161
162 Alternately, you can change this behavior globally by setting:
163
164 $CGI::Compile::RETURN_EXIT_VAL = 1;
165
166 Current Working Directory
167 If "CGI::Compile->compile" was passed a script file, the script's
168 directory becomes the current working directory during the runtime of
169 the script.
170
171 NOTE: to be able to switch back to the original directory, the compiled
172 coderef must establish the current working directory. This operation
173 may cause an additional flush operation on file handles.
174
175 "STDIN" and "STDOUT"
176 These file handles are not touched by "CGI::Compile".
177
178 The "DATA" file handle
179 If the script reads from the "DATA" file handle, it reads the
180 "__DATA__" section provided by the script just as a normal script would
181 do. Note, however, that the file handle is a memory handle. So, "fileno
182 DATA" will return "-1".
183
184 CGI.pm integration
185 If the subroutine "CGI::initialize_globals" is defined at script
186 runtime, it is called first thing by the compiled coderef.
187
189 These methods define some of the internal functionality of CGI::Compile
190 and may be overloaded if you need to subclass this module.
191
192 _read_source
193 Reads the source of a CGI script.
194
195 Parameters:
196
197 · $file_path
198
199 Path to the file the contents of which is to be read.
200
201 Returns:
202
203 · $source
204
205 The contents of the file as a scalar string.
206
207 _build_package
208 Creates a package name into which the CGI coderef will be compiled
209 into, prepended with "$self-"{namespace_root}>.
210
211 Parameters:
212
213 · $file_path
214
215 The path to the CGI script file, the package name is generated
216 based on this path.
217
218 Returns:
219
220 · $package
221
222 The generated package name.
223
224 _eval
225 Takes the generated perl code, which is the contents of the CGI script
226 and some other things we add to make everything work smoother, and
227 returns the evaluated coderef.
228
229 Currently this is done by writing out the code to a temp file and
230 reading it in with "do" in perlfunc so that there are no issues with
231 lexical context or source filters.
232
233 Parameters:
234
235 · $code
236
237 The generated code that will make the coderef for the CGI.
238
239 Returns:
240
241 · $coderef
242
243 The coderef that is the resulting of evaluating the generated perl
244 code.
245
247 Tatsuhiko Miyagawa <miyagawa@bulknews.net>
248
250 Rafael Kitover <rkitover@cpan.org>
251
252 Hans Dieter Pearcey <hdp@cpan.org>
253
254 kocoureasy <igor.bujna@post.cz>
255
256 Torsten Foertsch <torsten.foertsch@gmx.net>
257
259 Copyright (c) 2009 Tatsuhiko Miyagawa <miyagawa@bulknews.net>
260
261 This library is free software; you can redistribute it and/or modify it
262 under the same terms as Perl itself.
263
265 ModPerl::RegistryCooker CGI::Emulate::PSGI
266
267
268
269perl v5.30.0 2019-07-26 CGI::Compile(3pm)