Commit | Line | Data |
3fea05b9 |
1 | .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3 |
2 | .\" |
3 | .\" Standard preamble: |
4 | .\" ======================================================================== |
5 | .de Sh \" Subsection heading |
6 | .br |
7 | .if t .Sp |
8 | .ne 5 |
9 | .PP |
10 | \fB\\$1\fR |
11 | .PP |
12 | .. |
13 | .de Sp \" Vertical space (when we can't use .PP) |
14 | .if t .sp .5v |
15 | .if n .sp |
16 | .. |
17 | .de Vb \" Begin verbatim text |
18 | .ft CW |
19 | .nf |
20 | .ne \\$1 |
21 | .. |
22 | .de Ve \" End verbatim text |
23 | .ft R |
24 | .fi |
25 | .. |
26 | .\" Set up some character translations and predefined strings. \*(-- will |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. |
32 | .tr \(*W-|\(bv\*(Tr |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' |
34 | .ie n \{\ |
35 | . ds -- \(*W- |
36 | . ds PI pi |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch |
39 | . ds L" "" |
40 | . ds R" "" |
41 | . ds C` "" |
42 | . ds C' "" |
43 | 'br\} |
44 | .el\{\ |
45 | . ds -- \|\(em\| |
46 | . ds PI \(*p |
47 | . ds L" `` |
48 | . ds R" '' |
49 | 'br\} |
50 | .\" |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the |
54 | .\" output yourself in some meaningful fashion. |
55 | .if \nF \{\ |
56 | . de IX |
57 | . tm Index:\\$1\t\\n%\t"\\$2" |
58 | .. |
59 | . nr % 0 |
60 | . rr F |
61 | .\} |
62 | .\" |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
64 | .\" way too many mistakes in technical documents. |
65 | .hy 0 |
66 | .if n .na |
67 | .\" |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. |
70 | . \" fudge factors for nroff and troff |
71 | .if n \{\ |
72 | . ds #H 0 |
73 | . ds #V .8m |
74 | . ds #F .3m |
75 | . ds #[ \f1 |
76 | . ds #] \fP |
77 | .\} |
78 | .if t \{\ |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) |
80 | . ds #V .6m |
81 | . ds #F 0 |
82 | . ds #[ \& |
83 | . ds #] \& |
84 | .\} |
85 | . \" simple accents for nroff and troff |
86 | .if n \{\ |
87 | . ds ' \& |
88 | . ds ` \& |
89 | . ds ^ \& |
90 | . ds , \& |
91 | . ds ~ ~ |
92 | . ds / |
93 | .\} |
94 | .if t \{\ |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' |
101 | .\} |
102 | . \" troff and (daisy-wheel) nroff accents |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] |
110 | .ds ae a\h'-(\w'a'u*4/10)'e |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E |
112 | . \" corrections for vroff |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' |
115 | . \" for low resolution devices (crt and lpr) |
116 | .if \n(.H>23 .if \n(.V>19 \ |
117 | \{\ |
118 | . ds : e |
119 | . ds 8 ss |
120 | . ds o a |
121 | . ds d- d\h'-1'\(ga |
122 | . ds D- D\h'-1'\(hy |
123 | . ds th \o'bp' |
124 | . ds Th \o'LP' |
125 | . ds ae ae |
126 | . ds Ae AE |
127 | .\} |
128 | .rm #[ #] #H #V #F C |
129 | .\" ======================================================================== |
130 | .\" |
131 | .IX Title "CGI::Simple::Standard 3" |
132 | .TH CGI::Simple::Standard 3 "2009-05-31" "perl v5.8.7" "User Contributed Perl Documentation" |
133 | .SH "NAME" |
134 | CGI::Simple::Standard \- a wrapper module for CGI::Simple that provides a |
135 | function style interface |
136 | .SH "SYNOPSIS" |
137 | .IX Header "SYNOPSIS" |
138 | .Vb 3 |
139 | \& use CGI::Simple::Standard qw( \-autoload ); |
140 | \& use CGI::Simple::Standard qw( :core :cookie :header :misc ); |
141 | \& use CGI::Simple::Standard qw( param upload ); |
142 | .Ve |
143 | .PP |
144 | .Vb 2 |
145 | \& $CGI::Simple::Standard::POST_MAX = 1024; # max upload via post 1kB |
146 | \& $CGI::Simple::Standard::DISABLE_UPLOADS = 0; # enable uploads |
147 | .Ve |
148 | .PP |
149 | .Vb 3 |
150 | \& @params = param(); # return all param names as a list |
151 | \& $value = param('foo'); # return the first value supplied for 'foo' |
152 | \& @values = param('foo'); # return all values supplied for foo |
153 | .Ve |
154 | .PP |
155 | .Vb 3 |
156 | \& %fields = Vars(); # returns untied key value pair hash |
157 | \& $hash_ref = Vars(); # or as a hash ref |
158 | \& %fields = Vars("|"); # packs multiple values with "|" rather than "\e0"; |
159 | .Ve |
160 | .PP |
161 | .Vb 1 |
162 | \& @keywords = keywords(); # return all keywords as a list |
163 | .Ve |
164 | .PP |
165 | .Vb 3 |
166 | \& param( 'foo', 'some', 'new', 'values' ); # set new 'foo' values |
167 | \& param( \-name=>'foo', \-value=>'bar' ); |
168 | \& param( \-name=>'foo', \-value=>['bar','baz'] ); |
169 | .Ve |
170 | .PP |
171 | .Vb 2 |
172 | \& append( \-name=>'foo', \-value=>'bar' ); # append values to 'foo' |
173 | \& append( \-name=>'foo', \-value=>['some', 'new', 'values'] ); |
174 | .Ve |
175 | .PP |
176 | .Vb 2 |
177 | \& Delete('foo'); # delete param 'foo' and all its values |
178 | \& Delete_all(); # delete everything |
179 | .Ve |
180 | .PP |
181 | .Vb 1 |
182 | \& <INPUT TYPE="file" NAME="upload_file" SIZE="42"> |
183 | .Ve |
184 | .PP |
185 | .Vb 5 |
186 | \& $files = upload() # number of files uploaded |
187 | \& @files = upload(); # names of all uploaded files |
188 | \& $filename = param('upload_file') # filename of 'upload_file' field |
189 | \& $mime = upload_info($filename,'mime'); # MIME type of uploaded file |
190 | \& $size = upload_info($filename,'size'); # size of uploaded file |
191 | .Ve |
192 | .PP |
193 | .Vb 2 |
194 | \& my $fh = $q\->upload($filename); # open filehandle to read from |
195 | \& while ( read( $fh, $buffer, 1024 ) ) { ... } |
196 | .Ve |
197 | .PP |
198 | .Vb 3 |
199 | \& # short and sweet upload |
200 | \& $ok = upload( param('upload_file'), '/path/to/write/file.name' ); |
201 | \& print "Uploaded ".param('upload_file')." and wrote it OK!" if $ok; |
202 | .Ve |
203 | .PP |
204 | .Vb 4 |
205 | \& $decoded = url_decode($encoded); |
206 | \& $encoded = url_encode($unencoded); |
207 | \& $escaped = escapeHTML('<>"&'); |
208 | \& $unescaped = unescapeHTML('<>"&'); |
209 | .Ve |
210 | .PP |
211 | .Vb 1 |
212 | \& $qs = query_string(); # get all data in $q as a query string OK for GET |
213 | .Ve |
214 | .PP |
215 | .Vb 11 |
216 | \& no_cache(1); # set Pragma: no\-cache + expires |
217 | \& print header(); # print a simple header |
218 | \& # get a complex header |
219 | \& $header = header( \-type => 'image/gif' |
220 | \& \-nph => 1, |
221 | \& \-status => '402 Payment required', |
222 | \& \-expires =>'+24h', |
223 | \& \-cookie => $cookie, |
224 | \& \-charset => 'utf\-7', |
225 | \& \-attachment => 'foo.gif', |
226 | \& \-Cost => '$2.00'); |
227 | .Ve |
228 | .PP |
229 | .Vb 11 |
230 | \& @cookies = cookie(); # get names of all available cookies |
231 | \& $value = cookie('foo') # get first value of cookie 'foo' |
232 | \& @value = cookie('foo') # get all values of cookie 'foo' |
233 | \& # get a cookie formatted for header() method |
234 | \& $cookie = cookie( \-name => 'Password', |
235 | \& \-values => ['superuser','god','my dog woofie'], |
236 | \& \-expires => '+3d', |
237 | \& \-domain => '.nowhere.com', |
238 | \& \-path => '/cgi\-bin/database', |
239 | \& \-secure => 1 ); |
240 | \& print header( \-cookie=>$cookie ); # set cookie |
241 | .Ve |
242 | .PP |
243 | .Vb 1 |
244 | \& print redirect('http://go.away.now'); # print a redirect header |
245 | .Ve |
246 | .PP |
247 | .Vb 1 |
248 | \& dienice( cgi_error() ) if cgi_error(); |
249 | .Ve |
250 | .SH "DESCRIPTION" |
251 | .IX Header "DESCRIPTION" |
252 | This module is a wrapper for the completely object oriented CGI::Simple |
253 | module and provides a simple functional style interface. It provides two |
254 | different methods to import function names into your namespace. |
255 | .Sh "Autoloading" |
256 | .IX Subsection "Autoloading" |
257 | If you specify the '\-autoload' pragma like this: |
258 | .PP |
259 | .Vb 1 |
260 | \& use CGI::Simple::Standard qw( \-autoload ); |
261 | .Ve |
262 | .PP |
263 | Then it will use \s-1AUTOLOAD\s0 and a symbol table trick to export only those subs |
264 | you actually call into your namespace. When you specify the '\-autoload' pragma |
265 | this module exports a single \s-1AUTOLOAD\s0 subroutine into you namespace. This will |
266 | clash with any \s-1AUTOLOAD\s0 sub that exists in the calling namespace so if you are |
267 | using \s-1AUTOLOAD\s0 for something else don't use this pragma. |
268 | .PP |
269 | Anyway, when you call a subroutine that is not defined in your script this |
270 | \&\s-1AUTOLOAD\s0 sub will be called. The first time this happens it |
271 | will initialize a CGI::Simple object and then apply the requested method |
272 | (if it exists) to it. A fatal exception will be thrown if you try to use an |
273 | undefined method (function). |
274 | .Sh "Specified Export" |
275 | .IX Subsection "Specified Export" |
276 | Alternatively you can specify the functions you wish to import. You can do |
277 | this on a per function basis like this: |
278 | .PP |
279 | .Vb 1 |
280 | \& use CGI::Simple::Standard qw( param upload query_string Dump ); |
281 | .Ve |
282 | .PP |
283 | or utilize the \f(CW%EXPORT_TAGS\fR that group functions into related groups. |
284 | Here are the groupings: |
285 | .PP |
286 | .Vb 31 |
287 | \& %EXPORT_TAGS = ( |
288 | \& ':html' => [ qw(:misc) ], |
289 | \& ':standard' => [ qw(:core :access) ], |
290 | \& ':cgi' => [ qw(:core :access) ], |
291 | \& ':all' => [ qw(:core :misc :cookie :header :push :debug :cgi\-lib |
292 | \& :access :internal) ], |
293 | \& ':core' => [ qw(param add_param param_fetch url_param keywords |
294 | \& append Delete delete_all Delete_all upload |
295 | \& query_string parse_query_string parse_keywordlist |
296 | \& Vars save_parameters restore_parameters) ], |
297 | \& ':misc' => [ qw(url_decode url_encode escapeHTML unescapeHTML put) ], |
298 | \& ':cookie' => [ qw(cookie raw_cookie) ], |
299 | \& ':header' => [ qw(header cache no_cache redirect) ], |
300 | \& ':push' => [ qw(multipart_init multipart_start multipart_end |
301 | \& multipart_final) ], |
302 | \& ':debug' => [ qw(Dump as_string cgi_error _cgi_object) ], |
303 | \& ':cgi\-lib' => [ qw(ReadParse SplitParam MethGet MethPost MyBaseUrl MyURL |
304 | \& MyFullUrl PrintHeader HtmlTop HtmlBot PrintVariables |
305 | \& PrintEnv CgiDie CgiError Vars) ], |
306 | \& ':ssl' => [ qw(https) ], |
307 | \& ':access' => [ qw(version nph all_parameters charset crlf globals |
308 | \& auth_type content_length content_type document_root |
309 | \& gateway_interface path_translated referer remote_addr |
310 | \& remote_host remote_ident remote_user request_method |
311 | \& script_name server_name server_port server_protocol |
312 | \& server_software user_name user_agent virtual_host |
313 | \& path_info Accept http https protocol url self_url |
314 | \& state) ], |
315 | \& ':internal' => [ qw(_initialize_globals _use_cgi_pm_global_settings |
316 | \& _store_globals _reset_globals) ] |
317 | \& ); |
318 | .Ve |
319 | .PP |
320 | The familiar \s-1CGI\s0.pm tags are available but do not include the \s-1HTML\s0 |
321 | functionality. You specify the import of some function groups like this: |
322 | .PP |
323 | use CGI::Simple::Standard qw( :core :cookie :header ); |
324 | .PP |
325 | Note that the function groups all start with a : char. |
326 | .Sh "Mix and Match" |
327 | .IX Subsection "Mix and Match" |
328 | You can use the '\-autoload' pragma, specifically named function imports and |
329 | tag group imports together if you desire. |
330 | .ie n .SH "$POST_MAX and $DISABLE_UPLOADS" |
331 | .el .SH "$POST_MAX and \f(CW$DISABLE_UPLOADS\fP" |
332 | .IX Header "$POST_MAX and $DISABLE_UPLOADS" |
333 | If you wish to set \f(CW$POST_MAX\fR or \f(CW$DISABLE_UPLOADS\fR you must do this *after* the |
334 | use statement and *before* the first function call as shown in the synopsis. |
335 | .PP |
336 | Unlike \s-1CGI\s0.pm uploads are disabled by default and the maximum acceptable |
337 | data via post is capped at 102_400kB rather than infinity. This is specifically |
338 | to avoid denial of service attacks by default. To enable uploads and to |
339 | allow them to be of infinite size you simply: |
340 | .PP |
341 | .Vb 2 |
342 | \& $CGI::Simple::Standard::POST_MAX = \-1; # infinite size upload |
343 | \& $CGI::Simple::Standard::$DISABLE_UPLOADS = 0; # enable uploads |
344 | .Ve |
345 | .PP |
346 | Alternatively you can specify the \s-1CGI\s0.pm default values as shown above by |
347 | specifying the '\-default' pragma in your use statement. |
348 | .PP |
349 | .Vb 1 |
350 | \& use CGI::Simple::Standard qw( \-default ..... ); |
351 | .Ve |
352 | .SH "EXPORT" |
353 | .IX Header "EXPORT" |
354 | Nothing by default. |
355 | .PP |
356 | Under the '\-autoload' pragma the \s-1AUTOLOAD\s0 subroutine is |
357 | exported into the calling namespace. Additional subroutines are only imported |
358 | into this namespace if you physically call them. They are installed in the |
359 | symbol table the first time you use them to save repeated calls to \s-1AUTOLOAD\s0. |
360 | .PP |
361 | If you specifically request a function or group of functions via an \s-1EXPORT_TAG\s0 |
362 | then stubs of these functions are exported into the calling namespace. These |
363 | stub functions will be replaced with the real functions only if you actually |
364 | call them saving wasted compilation effort. |
365 | .SH "FUNCTION DETAILS" |
366 | .IX Header "FUNCTION DETAILS" |
367 | This is a wrapper module for CGI::Simple. Virtually all the methods available |
368 | in the \s-1OO\s0 interface are available via the functional interface. Several |
369 | method names are aliased to prevent namespace conflicts: |
370 | .PP |
371 | .Vb 4 |
372 | \& $q\->delete('foo') => Delete('foo') |
373 | \& $q\->delete_all => Delete_all() or delete_all() |
374 | \& $q\->save(\e*FH) => save_parameters(\e*FH) |
375 | \& $q\->accept() => Accept() |
376 | .Ve |
377 | .PP |
378 | Although you could use the \fInew()\fR function to genrate new \s-1OO\s0 CGI::Simple |
379 | objects the \fIrestore_parameters()\fR function is a better choice as it operates |
380 | like new but on the correct underlying CGI::Simple object for the functional |
381 | interface. |
382 | .PP |
383 | \&\fIrestore_parameters()\fR can be used exactly as you might use \fInew()\fR in that |
384 | you can supply arguments to it such as query strings, hashes and file handles |
385 | to re-initialize your underlying object. |
386 | .PP |
387 | .Vb 4 |
388 | \& $q\->new CGI::Simple() => restore_parameters() |
389 | \& $q\->new CGI::Simple({foo=>'bar'}) => restore_parameters({foo=>'bar'}) |
390 | \& $q\->new CGI::Simple($query_string) => restore_parameters($query_string) |
391 | \& $q\->new CGI::Simple(\e*FH) => restore_parameters(\e*FH) |
392 | .Ve |
393 | .PP |
394 | For full details of the available functions see the CGI::Simple docs. Just |
395 | remove the \f(CW$q\fR\-> part and use the method name directly. |
396 | .SH "BUGS" |
397 | .IX Header "BUGS" |
398 | As this is 0.01 there are almost bound to be some. |
399 | .SH "AUTHOR" |
400 | .IX Header "AUTHOR" |
401 | Dr James Freeman <jfreeman@tassie.net.au> |
402 | This release by Andy Armstrong <andy@hexten.net> |
403 | .PP |
404 | This package is free software and is provided \*(L"as is\*(R" without express or |
405 | implied warranty. It may be used, redistributed and/or modified under the terms |
406 | of the Perl Artistic License (see http://www.perl.com/perl/misc/Artistic.html) |
407 | .PP |
408 | Address bug reports and comments to: andy@hexten.net |
409 | .SH "CREDITS" |
410 | .IX Header "CREDITS" |
411 | The interface and key sections of the CGI::Simple code come from |
412 | \&\s-1CGI\s0.pm by Lincoln Stein. |
413 | .SH "SEE ALSO" |
414 | .IX Header "SEE ALSO" |
415 | \&\*(L"CGI::Simple which is the back end for this module\*(R", |
416 | \&\fB\s-1CGI\s0.pm by Lincoln Stein\fR |