1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
4 .\" ========================================================================
5 .de Sh \" Subsection heading
13 .de Sp \" Vertical space (when we can't use .PP)
17 .de Vb \" Begin verbatim text
22 .de Ve \" End verbatim text
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<>.
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
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
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.
57 . tm Index:\\$1\t\\n%\t"\\$2"
63 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
64 .\" way too many mistakes in technical documents.
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
79 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
85 . \" simple accents for nroff and troff
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'
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 \
129 .\" ========================================================================
131 .IX Title "CGI::Simple 3"
132 .TH CGI::Simple 3 "2009-05-31" "perl v5.8.7" "User Contributed Perl Documentation"
134 CGI::Simple \- A Simple totally OO CGI interface that is CGI.pm compliant
137 This document describes CGI::Simple version 1.112.
139 .IX Header "SYNOPSIS"
142 \& $CGI::Simple::POST_MAX = 1024; # max upload via post default 100kB
143 \& $CGI::Simple::DISABLE_UPLOADS = 0; # enable uploads
147 \& $q = new CGI::Simple;
148 \& $q = new CGI::Simple( { 'foo'=>'1', 'bar'=>[2,3,4] } );
149 \& $q = new CGI::Simple( 'foo=1&bar=2&bar=3&bar=4' );
150 \& $q = new CGI::Simple( \e*FILEHANDLE );
154 \& $q\->save( \e*FILEHANDLE ); # save current object to a file as used by new
158 \& @params = $q\->param; # return all param names as a list
159 \& $value = $q\->param('foo'); # return the first value supplied for 'foo'
160 \& @values = $q\->param('foo'); # return all values supplied for foo
164 \& %fields = $q\->Vars; # returns untied key value pair hash
165 \& $hash_ref = $q\->Vars; # or as a hash ref
166 \& %fields = $q\->Vars("|"); # packs multiple values with "|" rather than "\e0";
170 \& @keywords = $q\->keywords; # return all keywords as a list
174 \& $q\->param( 'foo', 'some', 'new', 'values' ); # set new 'foo' values
175 \& $q\->param( \-name=>'foo', \-value=>'bar' );
176 \& $q\->param( \-name=>'foo', \-value=>['bar','baz'] );
180 \& $q\->param( 'foo', 'some', 'new', 'values' ); # append values to 'foo'
181 \& $q\->append( \-name=>'foo', \-value=>'bar' );
182 \& $q\->append( \-name=>'foo', \-value=>['some', 'new', 'values'] );
186 \& $q\->delete('foo'); # delete param 'foo' and all its values
187 \& $q\->delete_all; # delete everything
191 \& <INPUT TYPE="file" NAME="upload_file" SIZE="42">
195 \& $files = $q\->upload() # number of files uploaded
196 \& @files = $q\->upload(); # names of all uploaded files
197 \& $filename = $q\->param('upload_file') # filename of uploaded file
198 \& $mime = $q\->upload_info($filename,'mime'); # MIME type of uploaded file
199 \& $size = $q\->upload_info($filename,'size'); # size of uploaded file
203 \& my $fh = $q\->upload($filename); # get filehandle to read from
204 \& while ( read( $fh, $buffer, 1024 ) ) { ... }
208 \& # short and sweet upload
209 \& $ok = $q\->upload( $q\->param('upload_file'), '/path/to/write/file.name' );
210 \& print "Uploaded ".$q\->param('upload_file')." and wrote it OK!" if $ok;
214 \& $decoded = $q\->url_decode($encoded);
215 \& $encoded = $q\->url_encode($unencoded);
216 \& $escaped = $q\->escapeHTML('<>"&');
217 \& $unescaped = $q\->unescapeHTML('<>"&');
221 \& $qs = $q\->query_string; # get all data in $q as a query string OK for GET
225 \& $q\->no_cache(1); # set Pragma: no\-cache + expires
226 \& print $q\->header(); # print a simple header
227 \& # get a complex header
228 \& $header = $q\->header( \-type => 'image/gif'
230 \& \-status => '402 Payment required',
231 \& \-expires =>'+24h',
232 \& \-cookie => $cookie,
233 \& \-charset => 'utf\-7',
234 \& \-attachment => 'foo.gif',
237 \& # a p3p header (OK for redirect use as well)
238 \& $header = $q\->header( \-p3p => 'policyref="http://somesite.com/P3P/PolicyReferences.xml' );
242 \& @cookies = $q\->cookie(); # get names of all available cookies
243 \& $value = $q\->cookie('foo') # get first value of cookie 'foo'
244 \& @value = $q\->cookie('foo') # get all values of cookie 'foo'
245 \& # get a cookie formatted for header() method
246 \& $cookie = $q\->cookie( \-name => 'Password',
247 \& \-values => ['superuser','god','my dog woofie'],
248 \& \-expires => '+3d',
249 \& \-domain => '.nowhere.com',
250 \& \-path => '/cgi\-bin/database',
253 \& print $q\->header( \-cookie=>$cookie ); # set cookie
257 \& print $q\->redirect('http://go.away.now'); # print a redirect header
261 \& dienice( $q\->cgi_error ) if $q\->cgi_error;
264 .IX Header "DESCRIPTION"
265 CGI::Simple provides a relatively lightweight drop in replacement for \s-1CGI\s0.pm.
266 It shares an identical \s-1OO\s0 interface to \s-1CGI\s0.pm for parameter parsing, file
267 upload, cookie handling and header generation. This module is entirely object
268 oriented, however a complete functional interface is available by using the
269 CGI::Simple::Standard module.
271 Essentially everything in \s-1CGI\s0.pm that relates to the \s-1CGI\s0 (not \s-1HTML\s0) side of
272 things is available. There are even a few new methods and additions to old
273 ones! If you are interested in what has gone on under the hood see the
274 Compatibility with \s-1CGI\s0.pm section at the end.
276 In practical testing this module loads and runs about twice as fast as \s-1CGI\s0.pm
277 depending on the precise task.
278 .SH "CALLING CGI::Simple ROUTINES USING THE OBJECT INTERFACE"
279 .IX Header "CALLING CGI::Simple ROUTINES USING THE OBJECT INTERFACE"
280 Here is a very brief rundown on how you use the interface. Full details
282 .Sh "First you need to initialize an object"
283 .IX Subsection "First you need to initialize an object"
284 Before you can call a CGI::Simple method you must create a CGI::Simple object.
285 You do that by using the module and then calling the \fInew()\fR constructor:
289 \& my $q = new CGI::Simple;
292 It is traditional to call your object \f(CW$q\fR for query or perhaps \f(CW$cgi\fR.
293 .Sh "Next you call methods on that object"
294 .IX Subsection "Next you call methods on that object"
295 Once you have your object you can call methods on it using the \-> arrow
296 syntax For example to get the names of all the parameters passed to your
297 script you would just write:
300 \& @names = $q\->param();
303 Many methods are sensitive to the context in which you call them. In the
304 example above the \fB\f(BIparam()\fB\fR method returns a list of all the parameter names
305 when called without any arguments.
307 When you call \fBparam('arg')\fR with a single argument it assumes you want
308 to get the value(s) associated with that argument (parameter). If you ask
309 for an array it gives you an array of all the values associated with it's
313 \& @values = $q\->param('foo'); # get all the values for 'foo'
316 whereas if you ask for a scalar like this:
319 \& $value = $q\->param('foo'); # get only the first value for 'foo'
322 then it returns only the first value (if more than one value for
325 Most CGI::Simple routines accept several arguments, sometimes as many as
326 10 optional ones! To simplify this interface, all routines use a named
327 argument calling style that looks like this:
330 \& print $q\->header( \-type=>'image/gif', \-expires=>'+3d' );
333 Each argument name is preceded by a dash. Neither case nor order
334 matters in the argument list. \-type, \-Type, and \-TYPE are all
337 Several routines are commonly called with just one argument. In the
338 case of these routines you can provide the single argument without an
339 argument name. \fB\f(BIheader()\fB\fR happens to be one of these routines. In this
340 case, the single argument is the document type.
343 \& print $q\->header('text/html');
346 Sometimes methods expect a scalar, sometimes a reference to an
347 array, and sometimes a reference to a hash. Often, you can pass any
348 type of argument and the routine will do whatever is most appropriate.
349 For example, the \fB\f(BIparam()\fB\fR method can be used to set a \s-1CGI\s0 parameter to a
350 single or a multi-valued value. The two cases are shown below:
353 \& $q\->param(\-name=>'veggie',\-value=>'tomato');
354 \& $q\->param(\-name=>'veggie',\-value=>['tomato','tomahto','potato','potahto']);
356 .SH "CALLING CGI::Simple ROUTINES USING THE FUNCTION INTERFACE"
357 .IX Header "CALLING CGI::Simple ROUTINES USING THE FUNCTION INTERFACE"
358 For convenience a functional interface is provided by the
359 CGI::Simple::Standard module. This hides the \s-1OO\s0 details from you and allows
360 you to simply call methods. You may either use \s-1AUTOLOADING\s0 of methods or
361 import specific method sets into you namespace. Here are the first few
362 examples again using the function interface.
365 \& use CGI::Simple::Standard qw(\-autoload);
367 \& @values = param('foo');
368 \& $value = param('foo');
369 \& print header(\-type=>'image/gif',\-expires=>'+3d');
370 \& print header('text/html');
373 Yes that's it. Not a \f(CW$q\fR\-> in sight. You just use the module and select
374 how/which methods to load. You then just call the methods you want exactly
375 as before but without the \f(CW$q\fR\-> notation.
377 When (if) you read the following docs and are using the functional interface
378 just pretend the \f(CW$q\fR\-> is not there.
379 .Sh "Selecting which methods to load"
380 .IX Subsection "Selecting which methods to load"
381 When you use the functional interface Perl needs to be able to find the
382 functions you call. The simplest way of doing this is to use autoloading as
383 shown above. When you use CGI::Simple::Standard with the '\-autoload' pragma
384 it exports a single \s-1AUTOLOAD\s0 sub into you namespace. Every time you call a
385 non existent function \s-1AUTOLOAD\s0 is called and will load the required
386 function and install it in your namespace. Thus only the \s-1AUTOLOAD\s0 sub and
387 those functions you specifically call will be imported.
389 Alternatively CGI::Simple::Standard provides a range of function sets you can
390 import or you can just select exactly what you want. You do this using the
394 \& use CGI::Simple::Standard qw( :func_set some_func);
397 notation. This will import the ':func_set' function set and the specific
398 function 'some_func'.
399 .Sh "To Autoload or not to Autoload, that is the question."
400 .IX Subsection "To Autoload or not to Autoload, that is the question."
401 If you do not have a \s-1AUTOLOAD\s0 sub in you script it is generally best to use
402 the '\-autoload' option. Under autoload you can use any method you want but
403 only import and compile those functions you actually use.
405 If you do not use autoload you must specify what functions to import. You can
406 only use functions that you have imported. For comvenience functions are
407 grouped into related sets. If you choose to import one or more ':func_set'
408 you may have potential namespace collisions so check out the docs to see
409 what gets imported. Using the ':all' tag is pretty slack but it is there
410 if you want. Full details of the function sets are provided in the
411 CGI::Simple::Standard docs
413 If you just want say the param and header methods just load these two.
416 \& use CGI::Simple::Standard qw(param header);
418 .Sh "Setting globals using the functional interface"
419 .IX Subsection "Setting globals using the functional interface"
420 Where you see global variables being set using the syntax:
423 \& $CGI::Simple::DEBUG = 1;
426 You use exactly the same syntax when using CGI::Simple::Standard.
427 .SH "THE CORE METHODS"
428 .IX Header "THE CORE METHODS"
429 .Sh "\fInew()\fP Creating a new query object"
430 .IX Subsection "new() Creating a new query object"
431 The first step in using CGI::Simple is to create a new query object using
432 the \fB\f(BInew()\fB\fR constructor:
435 \& $q = new CGI::Simple;
438 This will parse the input (from both \s-1POST\s0 and \s-1GET\s0 methods) and store
439 it into an object called \f(CW$q\fR.
441 If you provide a file handle to the \fB\f(BInew()\fB\fR method, it will read
442 parameters from the file (or \s-1STDIN\s0, or whatever).
445 \& open FH, "test.in" or die $!;
446 \& $q = new CGI::Simple(\e*FH);
450 \& open $fh, "test.in" or die $!;
451 \& $q = new CGI::Simple($fh);
454 The file should be a series of newline delimited TAG=VALUE pairs.
455 Conveniently, this type of file is created by the \fB\f(BIsave()\fB\fR method
456 (see below). Multiple records can be saved and restored.
457 IO::File objects work fine.
459 If you are using the function-oriented interface provided by
460 CGI::Simple::Standard and want to initialize from a file handle,
461 the way to do this is with \fB\f(BIrestore_parameters()\fB\fR. This will (re)initialize
462 the default CGI::Simple object from the indicated file handle.
465 \& restore_parameters(\e*FH);
468 In fact for all intents and purposes \fB\f(BIrestore_parameters()\fB\fR is identical
469 to \fB\f(BInew()\fB\fR Note that \fB\f(BIrestore_parameters()\fB\fR does not exist in
470 CGI::Simple itself so you can't use it.
472 You can also initialize the query object from an associative array
476 \& $q = new CGI::Simple( { 'dinosaur' => 'barney',
477 \& 'song' => 'I love you',
478 \& 'friends' => [qw/Jessica George Nancy/] }
482 or from a properly formatted, URL-escaped query string:
485 \& $q = new CGI::Simple( 'dinosaur=barney&color=purple' );
488 or from a previously existing CGI::Simple object (this generates an identical clone
489 including all global variable settings, etc that are stored in the object):
492 \& $old_query = new CGI::Simple;
493 \& $new_query = new CGI::Simple($old_query);
496 To create an empty query, initialize it from an empty string or hash:
499 \& $empty_query = new CGI::Simple("");
507 \& $empty_query = new CGI::Simple({});
509 .Sh "\fIkeywords()\fP Fetching a list of keywords from a query"
510 .IX Subsection "keywords() Fetching a list of keywords from a query"
512 \& @keywords = $q\->keywords;
515 If the script was invoked as the result of an <\s-1ISINDEX\s0> search, the
516 parsed keywords can be obtained as an array using the \fB\f(BIkeywords()\fB\fR method.
517 .Sh "\fIparam()\fP Fetching the names of all parameters passed to your script"
518 .IX Subsection "param() Fetching the names of all parameters passed to your script"
520 \& @names = $q\->param;
523 If the script was invoked with a parameter list
524 (e.g. \*(L"name1=value1&name2=value2&name3=value3\*(R"), the \fB\f(BIparam()\fB\fR method
525 will return the parameter names as a list. If the script was invoked
526 as an <\s-1ISINDEX\s0> script and contains a string without ampersands
527 (e.g. \*(L"value1+value2+value3\*(R") , there will be a single parameter named
528 \&\*(L"keywords\*(R" containing the \*(L"+\*(R"\-delimited keywords.
530 \&\s-1NOTE:\s0 The array of parameter names returned will
531 be in the same order as they were submitted by the browser.
532 Usually this order is the same as the order in which the
533 parameters are defined in the form (however, this isn't part
534 of the spec, and so isn't guaranteed).
535 .Sh "\fIparam()\fP Fetching the value or values of a simple named parameter"
536 .IX Subsection "param() Fetching the value or values of a simple named parameter"
538 \& @values = $q\->param('foo');
546 \& $value = $q\->param('foo');
549 Pass the \fB\f(BIparam()\fB\fR method a single argument to fetch the value of the
550 named parameter. If the parameter is multi-valued (e.g. from multiple
551 selections in a scrolling list), you can ask to receive an array. Otherwise
552 the method will return a single value.
554 If a value is not given in the query string, as in the queries
555 \&\*(L"name1=&name2=\*(R" or \*(L"name1&name2\*(R", it will be returned by default
556 as an empty string. If you set the global variable:
559 \& $CGI::Simple::NO_UNDEF_PARAMS = 1;
562 Then value-less parameters will be ignored, and will not exist in the
563 query object. If you try to access them via param you will get an undef
565 .Sh "\fIparam()\fP Setting the values of a named parameter"
566 .IX Subsection "param() Setting the values of a named parameter"
568 \& $q\->param('foo','an','array','of','values');
571 This sets the value for the named parameter 'foo' to an array of
572 values. This is one way to change the value of a field.
574 \&\fB\f(BIparam()\fB\fR also recognizes a named parameter style of calling described
575 in more detail later:
578 \& $q\->param(\-name=>'foo',\-values=>['an','array','of','values']);
586 \& $q\->param(\-name=>'foo',\-value=>'the value');
588 .Sh "\fIparam()\fP Retrieving non\-application/x\-www\-form\-urlencoded data"
589 .IX Subsection "param() Retrieving non-application/x-www-form-urlencoded data"
590 If POSTed or PUTed data is not of type application/x\-www\-form\-urlencoded or multipart/form\-data,
591 then the data will not be processed, but instead be returned as-is in a parameter named \s-1POSTDATA\s0
592 or \s-1PUTDATA\s0. To retrieve it, use code like this:
595 \& my $data = $q\->param( 'POSTDATA' );
603 \& my $data = $q\->param( 'PUTDATA' );
606 (If you don't know what the preceding means, don't worry about it. It only affects people trying
607 to use CGI::Simple for \s-1REST\s0 webservices)
608 .Sh "\fIadd_param()\fP Setting the values of a named parameter"
609 .IX Subsection "add_param() Setting the values of a named parameter"
610 You nay also use the new method \fBadd_param\fR to add parameters. This is an
611 alias to the \fI_add_param()\fR internal method that actually does all the work.
612 You can call it like this:
615 \& $q\->add_param('foo', 'new');
616 \& $q\->add_param('foo', [1,2,3,4,5]);
617 \& $q\->add_param( 'foo', 'bar', 'overwrite' );
620 The first argument is the parameter, the second the value or an array ref
621 of values and the optional third argument sets overwrite mode. If the third
622 argument is absent of false the values will be appended. If true the values
623 will overwrite any existing ones
624 .Sh "\fIappend()\fP Appending values to a named parameter"
625 .IX Subsection "append() Appending values to a named parameter"
627 \& $q\->append(\-name=>'foo',\-values=>['yet','more','values']);
630 This adds a value or list of values to the named parameter. The
631 values are appended to the end of the parameter if it already exists.
632 Otherwise the parameter is created. Note that this method only
633 recognizes the named argument calling syntax.
634 .Sh "\fIimport_names()\fP Importing all parameters into a namespace."
635 .IX Subsection "import_names() Importing all parameters into a namespace."
636 This method was silly, non \s-1OO\s0 and has been deleted. You can get all the params
637 as a hash using \fBVars\fR or via all the other accessors.
638 .Sh "\fIdelete()\fP Deleting a parameter completely"
639 .IX Subsection "delete() Deleting a parameter completely"
641 \& $q\->delete('foo');
644 This completely clears a parameter. If you are using the function call
645 interface, use \fB\f(BIDelete()\fB\fR instead to avoid conflicts with Perl's
646 built-in delete operator.
648 If you are using the function call interface, use \fB\f(BIDelete()\fB\fR instead to
649 avoid conflicts with Perl's built-in delete operator.
650 .Sh "\fIdelete_all()\fP Deleting all parameters"
651 .IX Subsection "delete_all() Deleting all parameters"
653 \& $q\->delete_all();
656 This clears the CGI::Simple object completely. For \s-1CGI\s0.pm compatibility
657 \&\fB\f(BIDelete_all()\fB\fR is provided however there is no reason to use this in the
658 function call interface other than symmetry.
660 For \s-1CGI\s0.pm compatibility \fB\f(BIDelete_all()\fB\fR is provided as an alias for
661 \&\fBdelete_all\fR however there is no reason to use this, even in the
662 function call interface.
663 .Sh "\fIparam_fetch()\fP Direct access to the parameter list"
664 .IX Subsection "param_fetch() Direct access to the parameter list"
665 This method is provided for \s-1CGI\s0.pm compatibility only. It returns an
666 array ref to the values associated with a named param. It is deprecated.
667 .Sh "\fIVars()\fP Fetching the entire parameter list as a hash"
668 .IX Subsection "Vars() Fetching the entire parameter list as a hash"
670 \& $params = $q\->Vars; # as a tied hash ref
671 \& print $params\->{'address'};
672 \& @foo = split "\e0", $params\->{'foo'};
676 \& %params = $q\->Vars; # as a plain hash
677 \& print $params{'address'};
678 \& @foo = split "\e0", $params{'foo'};
682 \& %params = $q\->Vars(','); # specifying a different separator than "\e0"
683 \& @foo = split ',', $params{'foo'};
686 Many people want to fetch the entire parameter list as a hash in which
687 the keys are the names of the \s-1CGI\s0 parameters, and the values are the
688 parameters' values. The \fB\f(BIVars()\fB\fR method does this.
690 Called in a scalar context, it returns the parameter list as a tied
691 hash reference. Because this hash ref is tied changing a key/value
692 changes the underlying CGI::Simple object.
694 Called in a list context, it returns the parameter list as an ordinary hash.
695 Changing this hash will not change the underlying CGI::Simple object
697 When using \fB\f(BIVars()\fB\fR, the thing you must watch out for are multi-valued \s-1CGI\s0
698 parameters. Because a hash cannot distinguish between scalar and
699 list context, multi-valued parameters will be returned as a packed
700 string, separated by the \*(L"\e0\*(R" (null) character. You must split this
701 packed string in order to get at the individual values. This is the
702 convention introduced long ago by Steve Brenner in his cgi\-lib.pl
703 module for Perl version 4.
705 You can change the character used to do the multiple value packing by passing
706 it to \fB\f(BIVars()\fB\fR as an argument as shown.
707 .Sh "\fIurl_param()\fP Access the \s-1QUERY_STRING\s0 regardless of '\s-1GET\s0' or '\s-1POST\s0'"
708 .IX Subsection "url_param() Access the QUERY_STRING regardless of 'GET' or 'POST'"
709 The \fB\f(BIurl_param()\fB\fR method makes the \s-1QUERY_STRING\s0 data available regardless
710 of whether the \s-1REQUEST_METHOD\s0 was '\s-1GET\s0' or '\s-1POST\s0'. You can do anything
711 with \fBurl_param\fR that you can do with \fB\f(BIparam()\fB\fR, however the data set
712 is completely independent.
714 Technically what happens if you use this method is that the \s-1QUERY_STRING\s0 data
715 is parsed into a new CGI::Simple object which is stored within the current
716 object. \fBurl_param\fR then just calls \fB\f(BIparam()\fB\fR on this new object.
717 .Sh "\fIparse_query_string()\fP Add \s-1QUERY_STRING\s0 data to '\s-1POST\s0' requests"
718 .IX Subsection "parse_query_string() Add QUERY_STRING data to 'POST' requests"
719 When the \s-1REQUEST_METHOD\s0 is '\s-1POST\s0' the default behavior is to ignore
720 name/value pairs or keywords in the \f(CW$ENV\fR{'\s-1QUERY_STRING\s0'}. You can override
721 this by calling \fB\f(BIparse_query_string()\fB\fR which will add the \s-1QUERY_STRING\s0 data to
722 the data already in our CGI::Simple object if the \s-1REQUEST_METHOD\s0 was '\s-1POST\s0'
725 \& $q = new CGI::Simple;
726 \& $q\->parse_query_string; # add $ENV{'QUERY_STRING'} data to our $q object
729 If the \s-1REQUEST_METHOD\s0 was '\s-1GET\s0' then the \s-1QUERY_STRING\s0 will already be
730 stored in our object so \fBparse_query_string\fR will be ignored.
732 This is a new method in CGI::Simple that is not available in \s-1CGI\s0.pm
733 .Sh "\fIsave()\fP Saving the state of an object to file"
734 .IX Subsection "save() Saving the state of an object to file"
736 \& $q\->save(\e*FILEHANDLE)
739 This will write the current state of the form to the provided
740 filehandle. You can read it back in by providing a filehandle
741 to the \fB\f(BInew()\fB\fR method.
743 The format of the saved file is:
753 Both name and value are \s-1URL\s0 escaped. Multi-valued \s-1CGI\s0 parameters are
754 represented as repeated names. A session record is delimited by a
755 single = symbol. You can write out multiple records and read them
756 back in with several calls to \fB\f(BInew()\fB\fR.
759 \& open FH, "test.in" or die $!;
760 \& $q1 = new CGI::Simple(\e*FH); # get the first record
761 \& $q2 = new CGI::Simple(\e*FH); # get the next record
764 Note: If you wish to use this method from the function-oriented (non\-OO)
765 interface, the exported name for this method is \fB\f(BIsave_parameters()\fB\fR.
766 Also if you want to initialize from a file handle, the way to do this is
767 with \fB\f(BIrestore_parameters()\fB\fR. This will (re)initialize
768 the default CGI::Simple object from the indicated file handle.
771 \& restore_parameters(\e*FH);
774 .IX Header "FILE UPLOADS"
775 File uploads are easy with CGI::Simple. You use the \fB\f(BIupload()\fB\fR method.
776 Assuming you have the following in your \s-1HTML:\s0
781 \& ACTION="http://somewhere.com/cgi\-bin/script.cgi"
782 \& ENCTYPE="multipart/form\-data">
783 \& <INPUT TYPE="file" NAME="upload_file1" SIZE="42">
784 \& <INPUT TYPE="file" NAME="upload_file2" SIZE="42">
788 Note that the \s-1ENCTYPE\s0 is \*(L"multipart/form\-data\*(R". You must specify this or the
789 browser will default to \*(L"application/x\-www\-form\-urlencoded\*(R" which will result
790 in no files being uploaded although on the surface things will appear \s-1OK\s0.
792 When the user submits this form any supplied files will be spooled onto disk
793 and saved in temporary files. These files will be deleted when your script.cgi
794 exits so if you want to keep them you will need to proceed as follows.
795 .Sh "\fIupload()\fP The key file upload method"
796 .IX Subsection "upload() The key file upload method"
797 The \fB\f(BIupload()\fB\fR method is quite versatile. If you call \fB\f(BIupload()\fB\fR without
798 any arguments it will return a list of uploaded files in list context and
799 the number of uploaded files in scalar context.
802 \& $number_of_files = $q\->upload;
803 \& @list_of_files = $q\->upload;
806 Having established that you have uploaded files available you can get the
807 browser supplied filename using \fB\f(BIparam()\fB\fR like this:
810 \& $filename1 = $q\->param('upload_file1');
813 You can then get a filehandle to read from by calling \fB\f(BIupload()\fB\fR and
814 supplying this filename as an argument. Warning: do not modify the
815 value you get from \fB\f(BIparam()\fB\fR in any way \- you don't need to untaint it.
818 \& $fh = $q\->upload( $filename1 );
821 Now to save the file you would just do something like:
824 \& $save_path = '/path/to/write/file.name';
825 \& open FH, ">$save_path" or die "Oops $!\en";
827 \& print FH $buffer while read( $fh, $buffer, 4096 );
831 By utilizing a new feature of the upload method this process can be
835 \& $ok = $q\->upload( $q\->param('upload_file1'), '/path/to/write/file.name' );
837 \& print "Uploaded and wrote file OK!";
839 \& print $q\->cgi_error();
843 As you can see upload will accept an optional second argument and will write
844 the file to this file path. It will return 1 for success and undef if it
845 fails. If it fails you can get the error from \fBcgi_error\fR
847 You can also use just the fieldname as an argument to upload ie:
850 \& $fh = $q\->upload( 'upload_field_name' );
858 \& $ok = $q\->upload( 'upload_field_name', '/path/to/write/file.name' );
861 \&\s-1BUT\s0 there is a catch. If you have multiple upload fields, all called
862 \&'upload_field_name' then you will only get the last uploaded file from
864 .Sh "\fIupload_info()\fP Get the details about uploaded files"
865 .IX Subsection "upload_info() Get the details about uploaded files"
866 The \fB\f(BIupload_info()\fB\fR method is a new method. Called without arguments it
867 returns the number of uploaded files in scalar context and the names of
868 those files in list context.
871 \& $number_of_upload_files = $q\->upload_info();
872 \& @filenames_of_all_uploads = $q\->upload_info();
875 You can get the \s-1MIME\s0 type of an uploaded file like this:
878 \& $mime = $q\->upload_info( $filename1, 'mime' );
881 If you want to know how big a file is before you copy it you can get that
882 information from \fBuploadInfo\fR which will return the file size in bytes.
885 \& $file_size = $q\->upload_info( $filename1, 'size' );
888 The size attribute is optional as this is the default value returned.
890 Note: The old \s-1CGI\s0.pm \fB\f(BIuploadInfo()\fB\fR method has been deleted.
891 .ie n .Sh "$POST_MAX and $DISABLE_UPLOADS"
892 .el .Sh "$POST_MAX and \f(CW$DISABLE_UPLOADS\fP"
893 .IX Subsection "$POST_MAX and $DISABLE_UPLOADS"
894 \&\s-1CGI\s0.pm has a default setting that allows infinite size file uploads by
895 default. In contrast file uploads are disabled by default in CGI::Simple
896 to discourage Denial of Service attacks. You must enable them before you
897 expect file uploads to work.
899 When file uploads are disabled the file name and file size details will
900 still be available from \fB\f(BIparam()\fB\fR and \fBupload_info\fR respectively but
901 the upload filehandle returned by \fB\f(BIupload()\fB\fR will be undefined \- not
902 surprising as the underlying temp file will not exist either.
904 You can enable uploads using the '\-upload' pragma. You do this by specifying
905 this in you use statement:
908 \& use CGI::Simple qw(\-upload);
911 Alternatively you can enable uploads via the \f(CW$DISABLE_UPLOADS\fR global like this:
915 \& $CGI::Simple::DISABLE_UPLOADS = 0;
916 \& $q = new CGI::Simple;
919 If you wish to set \f(CW$DISABLE_UPLOADS\fR you must do this *after* the
920 use statement and *before* the new constructor call as shown above.
922 The maximum acceptable data via post is capped at 102_400kB rather than
923 infinity which is the \s-1CGI\s0.pm default. This should be ample for most tasks
924 but you can set this to whatever you want using the \f(CW$POST_MAX\fR global.
928 \& $CGI::Simple::DISABLE_UPLOADS = 0; # enable uploads
929 \& $CGI::Simple::POST_MAX = 1_048_576; # allow 1MB uploads
930 \& $q = new CGI::Simple;
933 If you set to \-1 infinite size uploads will be permitted, which is the \s-1CGI\s0.pm
937 \& $CGI::Simple::POST_MAX = \-1; # infinite size upload
940 Alternatively you can specify all the \s-1CGI\s0.pm default values which allow file
941 uploads of infinite size in one easy step by specifying the '\-default' pragma
942 in your use statement.
945 \& use CGI::Simple qw( \-default ..... );
947 .Sh "\fIbinmode()\fP and Win32"
948 .IX Subsection "binmode() and Win32"
949 If you are using CGI::Simple be sure to call \fB\f(BIbinmode()\fB\fR on any handle that
950 you create to write the uploaded file to disk. Calling \fB\f(BIbinmode()\fB\fR will do
951 no harm on other systems anyway.
952 .SH "MISCELANEOUS METHODS"
953 .IX Header "MISCELANEOUS METHODS"
954 .Sh "\fIescapeHTML()\fP Escaping \s-1HTML\s0 special characters"
955 .IX Subsection "escapeHTML() Escaping HTML special characters"
956 In \s-1HTML\s0 the < > " and & chars have special meaning and need to be
957 escaped to < > " and & respectively.
960 \& $escaped = $q\->escapeHTML( $string );
964 \& $escaped = $q\->escapeHTML( $string, 'new_lines_too' );
967 If the optional second argument is supplied then newlines will be escaped to.
968 .Sh "\fIunescapeHTML()\fP Unescape \s-1HTML\s0 special characters"
969 .IX Subsection "unescapeHTML() Unescape HTML special characters"
970 This performs the reverse of \fB\f(BIescapeHTML()\fB\fR.
973 \& $unescaped = $q\->unescapeHTML( $HTML_escaped_string );
975 .Sh "\fIurl_decode()\fP Decode a \s-1URL\s0 encoded string"
976 .IX Subsection "url_decode() Decode a URL encoded string"
977 This method will correctly decode a url encoded string.
980 \& $decoded = $q\->url_decode( $encoded );
982 .Sh "\fIurl_encode()\fP \s-1URL\s0 encode a string"
983 .IX Subsection "url_encode() URL encode a string"
984 This method will correctly \s-1URL\s0 encode a string.
987 \& $encoded = $q\->url_encode( $string );
989 .Sh "\fIparse_keywordlist()\fP Parse a supplied keyword list"
990 .IX Subsection "parse_keywordlist() Parse a supplied keyword list"
992 \& @keywords = $q\->parse_keywordlist( $keyword_list );
995 This method returns a list of keywords, correctly \s-1URL\s0 escaped and split out
996 of the supplied string
997 .Sh "\fIput()\fP Send output to browser"
998 .IX Subsection "put() Send output to browser"
999 \&\s-1CGI\s0.pm alias for print. \f(CW$q\fR\->put('Hello World!') will print the usual
1000 .Sh "\fIprint()\fP Send output to browser"
1001 .IX Subsection "print() Send output to browser"
1002 \&\s-1CGI\s0.pm alias for print. \f(CW$q\fR\->print('Hello World!') will print the usual
1004 .IX Header "HTTP COOKIES"
1005 \&\s-1CGI\s0.pm has several methods that support cookies.
1007 A cookie is a name=value pair much like the named parameters in a \s-1CGI\s0
1008 query string. \s-1CGI\s0 scripts create one or more cookies and send
1009 them to the browser in the \s-1HTTP\s0 header. The browser maintains a list
1010 of cookies that belong to a particular Web server, and returns them
1011 to the \s-1CGI\s0 script during subsequent interactions.
1013 In addition to the required name=value pair, each cookie has several
1014 optional attributes:
1015 .IP "1. an expiration time" 4
1016 .IX Item "1. an expiration time"
1017 This is a time/date string (in a special \s-1GMT\s0 format) that indicates
1018 when a cookie expires. The cookie will be saved and returned to your
1019 script until this expiration date is reached if the user exits
1020 the browser and restarts it. If an expiration date isn't specified, the cookie
1021 will remain active until the user quits the browser.
1023 .IX Item "2. a domain"
1024 This is a partial or complete domain name for which the cookie is
1025 valid. The browser will return the cookie to any host that matches
1026 the partial domain name. For example, if you specify a domain name
1027 of \*(L".capricorn.com\*(R", then the browser will return the cookie to
1028 Web servers running on any of the machines \*(L"www.capricorn.com\*(R",
1029 \&\*(L"www2.capricorn.com\*(R", \*(L"feckless.capricorn.com\*(R", etc. Domain names
1030 must contain at least two periods to prevent attempts to match
1031 on top level domains like \*(L".edu\*(R". If no domain is specified, then
1032 the browser will only return the cookie to servers on the host the
1033 cookie originated from.
1035 .IX Item "3. a path"
1036 If you provide a cookie path attribute, the browser will check it
1037 against your script's \s-1URL\s0 before returning the cookie. For example,
1038 if you specify the path \*(L"/cgi\-bin\*(R", then the cookie will be returned
1039 to each of the scripts \*(L"/cgi\-bin/tally.pl\*(R", \*(L"/cgi\-bin/order.pl\*(R",
1040 and \*(L"/cgi\-bin/customer_service/complain.pl\*(R", but not to the script
1041 \&\*(L"/cgi\-private/site_admin.pl\*(R". By default, path is set to \*(L"/\*(R", which
1042 causes the cookie to be sent to any \s-1CGI\s0 script on your site.
1043 .ie n .IP "4. a ""secure"" flag" 4
1044 .el .IP "4. a ``secure'' flag" 4
1045 .IX Item "4. a secure flag"
1046 If the \*(L"secure\*(R" attribute is set, the cookie will only be sent to your
1047 script if the \s-1CGI\s0 request is occurring on a secure channel, such as \s-1SSL\s0.
1048 .Sh "\fIcookie()\fP A simple access method to cookies"
1049 .IX Subsection "cookie() A simple access method to cookies"
1050 The interface to \s-1HTTP\s0 cookies is the \fB\f(BIcookie()\fB\fR method:
1053 \& $cookie = $q\->cookie( \-name => 'sessionID',
1054 \& \-value => 'xyzzy',
1055 \& \-expires => '+1h',
1056 \& \-path => '/cgi\-bin/database',
1057 \& \-domain => '.capricorn.org',
1060 \& print $q\->header(\-cookie=>$cookie);
1063 \&\fB\f(BIcookie()\fB\fR creates a new cookie. Its parameters include:
1064 .IP "\fB\-name\fR" 4
1066 The name of the cookie (required). This can be any string at all.
1067 Although browsers limit their cookie names to non-whitespace
1068 alphanumeric characters, \s-1CGI\s0.pm removes this restriction by escaping
1069 and unescaping cookies behind the scenes.
1070 .IP "\fB\-value\fR" 4
1072 The value of the cookie. This can be any scalar value,
1073 array reference, or even associative array reference. For example,
1074 you can store an entire associative array into a cookie this way:
1077 \& $cookie=$q\->cookie( \-name => 'family information',
1078 \& \-value => \e%childrens_ages );
1080 .IP "\fB\-path\fR" 4
1082 The optional partial path for which this cookie will be valid, as described
1084 .IP "\fB\-domain\fR" 4
1086 The optional partial domain for which this cookie will be valid, as described
1088 .IP "\fB\-expires\fR" 4
1090 The optional expiration date for this cookie. The format is as described
1091 in the section on the \fB\f(BIheader()\fB\fR method:
1094 \& "+1h" one hour from now
1096 .IP "\fB\-secure\fR" 4
1098 If set to true, this cookie will only be used within a secure
1099 \&\s-1SSL\s0 session.
1101 The cookie created by \fB\f(BIcookie()\fB\fR must be incorporated into the \s-1HTTP\s0
1102 header within the string returned by the \fB\f(BIheader()\fB\fR method:
1105 \& print $q\->header(\-cookie=>$my_cookie);
1108 To create multiple cookies, give \fB\f(BIheader()\fB\fR an array reference:
1111 \& $cookie1 = $q\->cookie( \-name => 'riddle_name',
1112 \& \-value => "The Sphynx's Question"
1114 \& $cookie2 = $q\->cookie( \-name => 'answers',
1115 \& \-value => \e%answers
1117 \& print $q\->header( \-cookie => [ $cookie1, $cookie2 ] );
1120 To retrieve a cookie, request it by name by calling \fB\f(BIcookie()\fB\fR method
1121 without the \fB\-value\fR parameter:
1125 \& $q = new CGI::Simple;
1126 \& $riddle = $q\->cookie('riddle_name');
1127 \& %answers = $q\->cookie('answers');
1130 Cookies created with a single scalar value, such as the \*(L"riddle_name\*(R"
1131 cookie, will be returned in that form. Cookies with array and hash
1132 values can also be retrieved.
1134 The cookie and CGI::Simple namespaces are separate. If you have a parameter
1135 named 'answers' and a cookie named 'answers', the values retrieved by
1136 \&\fB\f(BIparam()\fB\fR and \fB\f(BIcookie()\fB\fR are independent of each other. However, it's
1137 simple to turn a \s-1CGI\s0 parameter into a cookie, and vice\-versa:
1140 \& # turn a CGI parameter into a cookie
1141 \& $c = $q\->cookie( \-name=>'answers', \-value=>[$q\->param('answers')] );
1143 \& $q\->param( \-name=>'answers', \-value=>[$q\->cookie('answers')] );
1145 .Sh "\fIraw_cookie()\fP"
1146 .IX Subsection "raw_cookie()"
1147 Returns the \s-1HTTP_COOKIE\s0 variable. Cookies have a special format, and
1148 this method call just returns the raw form (?cookie dough). See
1149 \&\fB\f(BIcookie()\fB\fR for ways of setting and retrieving cooked cookies.
1151 Called with no parameters, \fB\f(BIraw_cookie()\fB\fR returns the packed cookie
1152 structure. You can separate it into individual cookies by splitting
1153 on the character sequence \*(L"; \*(R". Called with the name of a cookie,
1154 retrieves the \fBunescaped\fR form of the cookie. You can use the
1155 regular \fB\f(BIcookie()\fB\fR method to get the names, or use the \fIraw_fetch()\fR
1156 method from the CGI::Simmple::Cookie module.
1157 .SH "CREATING HTTP HEADERS"
1158 .IX Header "CREATING HTTP HEADERS"
1159 Normally the first thing you will do in any \s-1CGI\s0 script is print out an
1160 \&\s-1HTTP\s0 header. This tells the browser what type of document to expect,
1161 and gives other optional information, such as the language, expiration
1162 date, and whether to cache the document. The header can also be
1163 manipulated for special purposes, such as server push and pay per view
1165 .Sh "\fIheader()\fP Create simple or complex \s-1HTTP\s0 headers"
1166 .IX Subsection "header() Create simple or complex HTTP headers"
1168 \& print $q\->header;
1176 \& print $q\->header('image/gif');
1184 \& print $q\->header('text/html','204 No response');
1192 \& print $q\->header( \-type => 'image/gif',
1194 \& \-status => '402 Payment required',
1195 \& \-expires => '+3d',
1196 \& \-cookie => $cookie,
1197 \& \-charset => 'utf\-7',
1198 \& \-attachment => 'foo.gif',
1199 \& \-Cost => '$2.00'
1203 \&\fB\f(BIheader()\fB\fR returns the Content\-type: header. You can provide your own
1204 \&\s-1MIME\s0 type if you choose, otherwise it defaults to text/html. An
1205 optional second parameter specifies the status code and a human-readable
1206 message. For example, you can specify 204, \*(L"No response\*(R" to create a
1207 script that tells the browser to do nothing at all.
1209 The last example shows the named argument style for passing arguments
1210 to the \s-1CGI\s0 methods using named parameters. Recognized parameters are
1211 \&\fB\-type\fR, \fB\-status\fR, \fB\-cookie\fR, \fB\-target\fR, \fB\-expires\fR, \fB\-nph\fR,
1212 \&\fB\-charset\fR and \fB\-attachment\fR. Any other named parameters will be
1213 stripped of their initial hyphens and turned into header fields, allowing
1214 you to specify any \s-1HTTP\s0 header you desire.
1216 For example, you can produce non-standard \s-1HTTP\s0 header fields by providing
1217 them as named arguments:
1220 \& print $q\->header( \-type => 'text/html',
1222 \& \-cost => 'Three smackers',
1223 \& \-annoyance_level => 'high',
1224 \& \-complaints_to => 'bit bucket'
1228 This will produce the following non-standard \s-1HTTP\s0 header:
1232 \& Cost: Three smackers
1233 \& Annoyance\-level: high
1234 \& Complaints\-to: bit bucket
1235 \& Content\-type: text/html
1238 Note that underscores are translated automatically into hyphens. This feature
1239 allows you to keep up with the rapidly changing \s-1HTTP\s0 \*(L"standards\*(R".
1241 The \fB\-type\fR is a key element that tell the browser how to display your
1242 document. The default is 'text/html'. Common types are:
1250 \& application/octet\-stream
1253 The \fB\-status\fR code is the \s-1HTTP\s0 response code. The default is 200 \s-1OK\s0. Common
1259 \& 301 Moved Permanently
1262 \& 307 Temporary Redirect
1268 \& 408 Request Timed Out
1269 \& 500 Internal Server Error
1270 \& 503 Service Unavailable
1271 \& 504 Gateway Timed Out
1274 The \fB\-expires\fR parameter lets you indicate to a browser and proxy server
1275 how long to cache pages for. When you specify an absolute or relative
1276 expiration interval with this parameter, some browsers and proxy servers
1277 will cache the script's output until the indicated expiration date.
1278 The following forms are all valid for the \-expires field:
1281 \& +30s 30 seconds from now
1282 \& +10m ten minutes from now
1283 \& +1h one hour from now
1284 \& \-1d yesterday (i.e. "ASAP!")
1286 \& +3M in three months
1287 \& +10y in ten years time
1288 \& Thursday, 25\-Apr\-1999 00:40:33 GMT at the indicated time & date
1291 The \fB\-cookie\fR parameter generates a header that tells the browser to provide
1292 a \*(L"magic cookie\*(R" during all subsequent transactions with your script.
1293 Netscape cookies have a special format that includes interesting attributes
1294 such as expiration time. Use the \fB\f(BIcookie()\fB\fR method to create and retrieve
1297 The \fB\-target\fR is for frames use
1299 The \fB\-nph\fR parameter, if set to a true value, will issue the correct
1300 headers to work with a \s-1NPH\s0 (no\-parse\-header) script. This is important
1301 to use with certain servers that expect all their scripts to be \s-1NPH\s0.
1303 The \fB\-charset\fR parameter can be used to control the character set
1304 sent to the browser. If not provided, defaults to \s-1ISO\-8859\-1\s0. As a
1305 side effect, this sets the \fIcharset()\fR method as well.
1307 The \fB\-attachment\fR parameter can be used to turn the page into an
1308 attachment. Instead of displaying the page, some browsers will prompt
1309 the user to save it to disk. The value of the argument is the
1310 suggested name for the saved file. In order for this to work, you may
1311 have to set the \fB\-type\fR to 'application/octet\-stream'.
1312 .Sh "\fIno_cache()\fP Preventing browser caching of scripts"
1313 .IX Subsection "no_cache() Preventing browser caching of scripts"
1314 Most browsers will not cache the output from \s-1CGI\s0 scripts. Every time
1315 the browser reloads the page, the script is invoked anew. However some
1316 browsers do cache pages. You can discourage this behavior using the
1317 \&\fB\f(BIno_cache()\fB\fR function.
1320 \& $q\->no_cache(1); # turn caching off by sending appropriate headers
1321 \& $q\->no_cache(1); # do not send cache related headers.
1325 \& $q\->no_cache(1);
1326 \& print header (\-type=>'image/gif', \-nph=>1);
1330 \& This will produce a header like the following:
1335 \& Server: Apache \- accept no substitutes
1336 \& Expires: Thu, 15 Nov 2001 03:37:50 GMT
1337 \& Date: Thu, 15 Nov 2001 03:37:50 GMT
1338 \& Pragma: no\-cache
1339 \& Content\-Type: image/gif
1342 Both the Pragma: no-cache header field and an Expires header that corresponds
1343 to the current time (ie now) will be sent.
1344 .Sh "\fIcache()\fP Preventing browser caching of scripts"
1345 .IX Subsection "cache() Preventing browser caching of scripts"
1346 The somewhat ill named \fB\f(BIcache()\fB\fR method is a legacy from \s-1CGI\s0.pm. It operates
1347 the same as the new \fB\f(BIno_cache()\fB\fR method. The difference is/was that when set
1348 it results only in the Pragma: no-cache line being printed.
1349 Expires time data is not sent.
1350 .Sh "\fIredirect()\fP Generating a redirection header"
1351 .IX Subsection "redirect() Generating a redirection header"
1353 \& print $q\->redirect('http://somewhere.else/in/movie/land');
1356 Sometimes you don't want to produce a document yourself, but simply
1357 redirect the browser elsewhere, perhaps choosing a \s-1URL\s0 based on the
1358 time of day or the identity of the user.
1360 The \fB\f(BIredirect()\fB\fR function redirects the browser to a different \s-1URL\s0. If
1361 you use redirection like this, you should \fBnot\fR print out a header as
1364 One hint I can offer is that relative links may not work correctly
1365 when you generate a redirection to another document on your site.
1366 This is due to a well-intentioned optimization that some servers use.
1367 The solution to this is to use the full \s-1URL\s0 (including the http: part)
1368 of the document you are redirecting to.
1370 You can also use named arguments:
1373 \& print $q\->redirect( \-uri=>'http://somewhere.else/in/movie/land',
1378 The \fB\-nph\fR parameter, if set to a true value, will issue the correct
1379 headers to work with a \s-1NPH\s0 (no\-parse\-header) script. This is important
1380 to use with certain servers, such as Microsoft ones, which
1381 expect all their scripts to be \s-1NPH\s0.
1383 .IX Header "PRAGMAS"
1384 There are a number of pragmas that you can specify in your use CGI::Simple
1385 statement. Pragmas, which are always preceded by a hyphen, change the way
1386 that CGI::Simple functions in various ways. You can generally achieve
1387 exactly the same results by setting the underlying \f(CW$GLOBAL_VARIABLES\fR.
1389 For example the '\-upload' pargma will enable file uploads:
1392 \& use CGI::Simple qw(\-upload);
1395 In CGI::Simple::Standard Pragmas, function sets , and individual functions
1396 can all be imported in the same \fIuse()\fR line. For example, the following
1397 use statement imports the standard set of functions and enables debugging
1398 mode (pragma \-debug):
1401 \& use CGI::Simple::Standard qw(:standard \-debug);
1404 The current list of pragmas is as follows:
1405 .IP "\-no_undef_params" 4
1406 .IX Item "-no_undef_params"
1407 If a value is not given in the query string, as in the queries
1408 \&\*(L"name1=&name2=\*(R" or \*(L"name1&name2\*(R", by default it will be returned
1411 If you specify the '\-no_undef_params' pragma then CGI::Simple ignores
1412 parameters with no values and they will not appear in the query object.
1415 This makes \s-1CGI\s0.pm produce a header appropriate for an \s-1NPH\s0 (no
1416 parsed header) script. You may need to do other things as well
1417 to tell the server that the script is \s-1NPH\s0. See the discussion
1418 of \s-1NPH\s0 scripts below.
1419 .IP "\-newstyle_urls" 4
1420 .IX Item "-newstyle_urls"
1421 Separate the name=value pairs in \s-1CGI\s0 parameter query strings with
1422 semicolons rather than ampersands. For example:
1425 \& ?name=fred;age=24;favorite_color=3
1428 Semicolon-delimited query strings are always accepted, but will not be
1429 emitted by \fIself_url()\fR and \fIquery_string()\fR unless the \-newstyle_urls
1430 pragma is specified.
1431 .IP "\-oldstyle_urls" 4
1432 .IX Item "-oldstyle_urls"
1433 Separate the name=value pairs in \s-1CGI\s0 parameter query strings with
1434 ampersands rather than semicolons. This is the default.
1437 \& ?name=fred&age=24&favorite_color=3
1440 .IX Item "-autoload"
1441 This is only available for CGI::Simple::Standard and uses \s-1AUTOLOAD\s0 to
1442 load functions on demand. See the CGI::Simple::Standard docs for details.
1444 .IX Item "-no_debug"
1445 This turns off the command-line processing features. This is the default.
1446 .IP "\-debug1 and debug2" 4
1447 .IX Item "-debug1 and debug2"
1448 This turns on debugging. At debug level 1 CGI::Simple will read arguments
1449 from the command\-line. At debug level 2 \s-1CGI\s0.pm will produce the prompt
1450 \&\*(L"(offline mode: enter name=value pairs on standard input)\*(R" and wait for
1451 input on \s-1STDIN\s0. If no number is specified then a debug level of 2 is used.
1453 See the section on debugging for more details.
1456 This sets the default global values for \s-1CGI\s0.pm which will enable infinite
1457 size file uploads, and specify the '\-newstyle_urls' and '\-debug1' pragmas
1459 .IX Item "-no_upload"
1460 Disable uploads \- the default setting
1463 Enable uploads \- the \s-1CGI\s0.pm default
1464 .IP "\-unique_header" 4
1465 .IX Item "-unique_header"
1466 Only allows headers to be generated once per script invocation
1469 Carp when \fB\f(BIcgi_error()\fB\fR called, default is to do nothing
1472 Croak when \fB\f(BIcgi_error()\fB\fR called, default is to do nothing
1473 .SH "USING NPH SCRIPTS"
1474 .IX Header "USING NPH SCRIPTS"
1475 \&\s-1NPH\s0, or \*(L"no\-parsed\-header\*(R", scripts bypass the server completely by
1476 sending the complete \s-1HTTP\s0 header directly to the browser. This has
1477 slight performance benefits, but is of most use for taking advantage
1478 of \s-1HTTP\s0 extensions that are not directly supported by your server,
1479 such as server push and \s-1PICS\s0 headers.
1481 Servers use a variety of conventions for designating \s-1CGI\s0 scripts as
1482 \&\s-1NPH\s0. Many Unix servers look at the beginning of the script's name for
1483 the prefix \*(L"nph\-\*(R". The Macintosh WebSTAR server and Microsoft's
1484 Internet Information Server, in contrast, try to decide whether a
1485 program is an \s-1NPH\s0 script by examining the first line of script output.
1487 \&\s-1CGI\s0.pm supports \s-1NPH\s0 scripts with a special \s-1NPH\s0 mode. When in this
1488 mode, \s-1CGI\s0.pm will output the necessary extra header information when
1489 the \fB\f(BIheader()\fB\fR and \fB\f(BIredirect()\fB\fR methods are called. You can set \s-1NPH\s0 mode
1490 in any of the following ways:
1491 .IP "In the \fBuse\fR statement" 4
1492 .IX Item "In the use statement"
1493 Simply add the \*(L"\-nph\*(R" pragma to the use:
1496 \& use CGI::Simple qw(\-nph)
1498 .IP "By calling the \fB\f(BInph()\fB\fR method:" 4
1499 .IX Item "By calling the nph() method:"
1500 Call \fB\f(BInph()\fB\fR with a non-zero parameter at any point after using \s-1CGI\s0.pm in your program.
1505 .IP "By using \fB\-nph\fR parameters" 4
1506 .IX Item "By using -nph parameters"
1507 in the \fB\f(BIheader()\fB\fR and \fB\f(BIredirect()\fB\fR statements:
1510 \& print $q\->header(\-nph=>1);
1513 The Microsoft Internet Information Server requires \s-1NPH\s0 mode.
1514 CGI::Simple will automatically detect when the script is
1515 running under \s-1IIS\s0 and put itself into this mode. You do not need to
1516 do this manually, although it won't hurt anything if you do. However,
1517 note that if you have applied Service Pack 6, much of the
1518 functionality of \s-1NPH\s0 scripts, including the ability to redirect while
1519 setting a cookie, b<do not work at all> on \s-1IIS\s0 without a special patch
1521 http://support.microsoft.com/support/kb/articles/Q280/3/41.ASP:
1522 Non-Parsed Headers Stripped From \s-1CGI\s0 Applications That Have nph\-
1525 .IX Header "SERVER PUSH"
1526 \&\s-1CGI\s0.pm provides four simple functions for producing multipart
1527 documents of the type needed to implement server push. These
1528 functions were graciously provided by Ed Jordan <ed@fidalgo.net> with
1529 additions from Andrew Benham <adsb@bigfoot.com>
1531 You are also advised to put the script into \s-1NPH\s0 mode and to set $| to
1532 1 to avoid buffering problems.
1534 Browser support for server push is variable.
1536 Here is a simple script that demonstrates server push:
1539 \& #!/usr/local/bin/perl
1540 \& use CGI::Simple::Standard qw/:push \-nph/;
1542 \& print multipart_init(\-boundary=>'\-\-\-\-here we go!');
1543 \& foreach (0 .. 4) {
1544 \& print multipart_start(\-type=>'text/plain'),
1545 \& "The current time is ",scalar(localtime),"\en";
1547 \& print multipart_end;
1550 \& print multipart_final;
1556 This script initializes server push by calling \fB\f(BImultipart_init()\fB\fR.
1557 It then enters a loop in which it begins a new multipart section by
1558 calling \fB\f(BImultipart_start()\fB\fR, prints the current local time,
1559 and ends a multipart section with \fB\f(BImultipart_end()\fB\fR. It then sleeps
1560 a second, and begins again. On the final iteration, it ends the
1561 multipart section with \fB\f(BImultipart_final()\fB\fR rather than with
1562 \&\fB\f(BImultipart_end()\fB\fR.
1563 .Sh "\fImultipart_init()\fP Initialize the multipart system"
1564 .IX Subsection "multipart_init() Initialize the multipart system"
1566 \& multipart_init(\-boundary=>$boundary);
1569 Initialize the multipart system. The \-boundary argument specifies
1570 what \s-1MIME\s0 boundary string to use to separate parts of the document.
1571 If not provided, \s-1CGI\s0.pm chooses a reasonable boundary for you.
1572 .Sh "\fImultipart_start()\fP Start a new part of the multipart document"
1573 .IX Subsection "multipart_start() Start a new part of the multipart document"
1575 \& multipart_start(\-type=>$type)
1578 Start a new part of the multipart document using the specified \s-1MIME\s0
1579 type. If not specified, text/html is assumed.
1580 .Sh "\fImultipart_end()\fP End a multipart part"
1581 .IX Subsection "multipart_end() End a multipart part"
1586 End a part. You must remember to call \fB\f(BImultipart_end()\fB\fR once for each
1587 \&\fB\f(BImultipart_start()\fB\fR, except at the end of the last part of the multipart
1588 document when \fB\f(BImultipart_final()\fB\fR should be called instead of
1589 \&\fB\f(BImultipart_end()\fB\fR.
1590 .Sh "\fImultipart_final()\fP"
1591 .IX Subsection "multipart_final()"
1593 \& multipart_final()
1596 End all parts. You should call \fB\f(BImultipart_final()\fB\fR rather than
1597 \&\fB\f(BImultipart_end()\fB\fR at the end of the last part of the multipart document.
1599 .IX Subsection "CGI::Push"
1600 Users interested in server push applications should also have a look
1601 at the \fBCGI::Push\fR module.
1603 .IX Header "DEBUGGING"
1604 If you are running the script from the command line or in the perl
1605 debugger, you can pass the script a list of keywords or
1606 parameter=value pairs on the command line or from standard input (you
1607 don't have to worry about tricking your script into reading from
1608 environment variables). Before you do this you will need to change the
1609 debug level from the default level of 0 (no debug) to either 1 if you
1610 want to debug from \f(CW@ARGV\fR (the command line) of 2 if you want to debug from
1611 \&\s-1STDIN\s0. You can do this using the debug pragma like this:
1614 \& use CGI::Simple qw(\-debug2); # set debug to level 2 => from STDIN
1622 \& $CGI::Simple::DEBUG = 1; # set debug to level 1 => from @ARGV
1625 At debug level 1 you can pass keywords and name=value pairs like this:
1628 \& your_script.pl keyword1 keyword2 keyword3
1636 \& your_script.pl keyword1+keyword2+keyword3
1644 \& your_script.pl name1=value1 name2=value2
1652 \& your_script.pl name1=value1&name2=value2
1655 At debug level 2 you can feed newline-delimited name=value
1656 pairs to the script on standard input. You will be presented
1657 with the following prompt:
1660 \& (offline mode: enter name=value pairs on standard input)
1663 You end the input with your system dependent end of file character.
1664 You should try ^Z ^X ^D and ^C if all else fails. The ^ means hold down
1665 the [Ctrl] button while you press the other key.
1667 When debugging, you can use quotes and backslashes to escape
1668 characters in the familiar shell manner, letting you place
1669 spaces and other funny characters in your parameter=value
1673 \& your_script.pl "name1='I am a long value'" "name2=two\e words"
1675 .Sh "\fIDump()\fP Dumping the current object details"
1676 .IX Subsection "Dump() Dumping the current object details"
1677 The \fB\f(BIDump()\fB\fR method produces a string consisting of all the
1678 query's object attributes formatted nicely as a nested list. This dump
1679 includes the name/value pairs and a number of other details. This is useful
1680 for debugging purposes:
1686 The actual result of this is \s-1HTML\s0 escaped formatted text wrapped in <pre> tags
1687 so if you send it straight to the browser it produces something that looks
1692 \& '.parameters' => [
1700 \& 'POST_MAX' => 102400,
1701 \& 'USE_CGI_PM_DEFAULTS' => 0,
1702 \& 'HEADERS_ONCE' => 0,
1704 \& 'DISABLE_UPLOADS' => 1,
1705 \& 'NO_UNDEF_PARAMS' => 0,
1706 \& 'USE_PARAM_SEMICOLONS' => 0
1708 \& '.fieldnames' => {
1712 \& '.mod_perl' => '',
1721 \& }, 'CGI::Simple' );
1724 You may recognize this as valid Perl syntax (which it is) and/or the output
1725 from Data::Dumper (also true). This is the actual guts of how the information
1726 is stored in the query object. All the internal params start with a . char
1728 Alternatively you can dump your object and the current environment using:
1731 \& print $q\->Dump(\e%ENV);
1733 .Sh "\fIPrintEnv()\fP Dumping the environment"
1734 .IX Subsection "PrintEnv() Dumping the environment"
1735 You can get a similar browser friendly dump of the current \f(CW%ENV\fR hash using:
1738 \& print $q\->PrintEnv;
1741 This will produce something like (in the browser):
1745 \& 'QUERY_STRING' => 'name=JaPh%2C&color=red&color=green&color=blue',
1746 \& 'CONTENT_TYPE' => 'application/x\-www\-form\-urlencoded',
1747 \& 'REGRESSION_TEST' => 'simple.t.pl',
1748 \& 'VIM' => 'C:\e\eWINDOWS\e\eDesktop\e\evim',
1749 \& 'HTTP_REFERER' => 'xxx.sex.com',
1750 \& 'HTTP_USER_AGENT' => 'LWP',
1751 \& 'HTTP_ACCEPT' => 'text/html;q=1, image/gif;q=0.42, */*;q=0.001',
1752 \& 'REMOTE_HOST' => 'localhost',
1753 \& 'HTTP_HOST' => 'the.restaurant.at.the.end.of.the.universe',
1754 \& 'GATEWAY_INTERFACE' => 'bleeding edge',
1755 \& 'REMOTE_IDENT' => 'None of your damn business',
1756 \& 'SCRIPT_NAME' => '/cgi\-bin/foo.cgi',
1757 \& 'SERVER_NAME' => 'nowhere.com',
1758 \& 'HTTP_COOKIE' => '',
1759 \& 'CONTENT_LENGTH' => '42',
1760 \& 'HTTPS_A' => 'A',
1761 \& 'HTTP_FROM' => 'spammer@nowhere.com',
1762 \& 'HTTPS_B' => 'B',
1763 \& 'SERVER_PROTOCOL' => 'HTTP/1.0',
1764 \& 'PATH_TRANSLATED' => '/usr/local/somewhere/else',
1765 \& 'SERVER_SOFTWARE' => 'Apache \- accept no substitutes',
1766 \& 'PATH_INFO' => '/somewhere/else',
1767 \& 'REMOTE_USER' => 'Just another Perl hacker,',
1768 \& 'REMOTE_ADDR' => '127.0.0.1',
1770 \& 'DOCUMENT_ROOT' => '/vs/www/foo',
1771 \& 'REQUEST_METHOD' => 'GET',
1772 \& 'REDIRECT_QUERY_STRING' => '',
1773 \& 'AUTH_TYPE' => 'PGP MD5 DES rot13',
1774 \& 'COOKIE' => 'foo=a%20phrase; bar=yes%2C%20a%20phrase&;I%20say;',
1775 \& 'SERVER_PORT' => '8080'
1778 .Sh "\fIcgi_error()\fP Retrieving CGI::Simple error messages"
1779 .IX Subsection "cgi_error() Retrieving CGI::Simple error messages"
1780 Errors can occur while processing user input, particularly when
1781 processing uploaded files. When these errors occur, CGI::Simple will stop
1782 processing and return an empty parameter list. You can test for
1783 the existence and nature of errors using the \fB\f(BIcgi_error()\fB\fR function.
1784 The error messages are formatted as \s-1HTTP\s0 status codes. You can either
1785 incorporate the error text into an \s-1HTML\s0 page, or use it as the value
1786 of the \s-1HTTP\s0 status:
1789 \& my $error = $q\->cgi_error;
1791 \& print $q\->header(\-status=>$error);
1792 \& print "<H2>$error</H2>;
1796 .SH "ACCESSOR METHODS"
1797 .IX Header "ACCESSOR METHODS"
1798 .Sh "\fIversion()\fP Get the CGI::Simple version info"
1799 .IX Subsection "version() Get the CGI::Simple version info"
1801 \& $version = $q\->version();
1804 The \fB\f(BIversion()\fB\fR method returns the value of \f(CW$VERSION\fR
1805 .Sh "\fInph()\fP Enable/disable \s-1NPH\s0 (Non Parsed Header) mode"
1806 .IX Subsection "nph() Enable/disable NPH (Non Parsed Header) mode"
1808 \& $q\->nph(1); # enable NPH mode
1809 \& $q\->nph(0); # disable NPH mode
1812 The \fB\f(BInph()\fB\fR method enables and disables \s-1NPH\s0 headers. See the \s-1NPH\s0 section.
1813 .Sh "\fIall_parameters()\fP Get the names/values of all parameters"
1814 .IX Subsection "all_parameters() Get the names/values of all parameters"
1816 \& @all_parameters = $q\->all_parameters();
1819 The \fB\f(BIall_parameters()\fB\fR method is an alias for \fB\f(BIparam()\fB\fR
1820 .Sh "\fIcharset()\fP Get/set the current character set."
1821 .IX Subsection "charset() Get/set the current character set."
1823 \& $charset = $q\->charset(); # get current charset
1824 \& $q\->charset('utf\-42'); # set the charset
1827 The \fB\f(BIcharset()\fB\fR method gets the current charset value if no argument is
1828 supplied or sets it if an argument is supplied.
1829 .Sh "\fIcrlf()\fP Get the system specific line ending sequence"
1830 .IX Subsection "crlf() Get the system specific line ending sequence"
1832 \& $crlf = $q\->crlf();
1835 The \fB\f(BIcrlf()\fB\fR method returns the system specific line ending sequence.
1836 .Sh "\fIglobals()\fP Get/set the value of the remaining global variables"
1837 .IX Subsection "globals() Get/set the value of the remaining global variables"
1839 \& $globals = $q\->globals('FATAL'); # get the current value of $FATAL
1840 \& $globals = $q\->globals('FATAL', 1 ); # set croak mode on cgi_error()
1843 The \fB\f(BIglobals()\fB\fR method gets/sets the values of the global variables after the
1844 script has been invoked. For globals like \f(CW$POST_MAX\fR and \f(CW$DISABLE_UPLOADS\fR this
1845 makes no difference as they must be set prior to calling the new constructor
1846 but there might be reason the change the value of others.
1847 .Sh "\fIauth_type()\fP Get the current authorization/verification method"
1848 .IX Subsection "auth_type() Get the current authorization/verification method"
1850 \& $auth_type = $q\->auth_type();
1853 The \fB\f(BIauth_type()\fB\fR method returns the value of \f(CW$ENV\fR{'\s-1AUTH_TYPE\s0'} which should
1854 contain the authorization/verification method in use for this script, if any.
1855 .Sh "\fIcontent_length()\fP Get the content length submitted in a \s-1POST\s0"
1856 .IX Subsection "content_length() Get the content length submitted in a POST"
1858 \& $content_length = $q\->content_length();
1861 The \fB\f(BIcontent_length()\fB\fR method returns the value of \f(CW$ENV\fR{'\s-1AUTH_TYPE\s0'}
1862 .Sh "\fIcontent_type()\fP Get the content_type of data submitted in a \s-1POST\s0"
1863 .IX Subsection "content_type() Get the content_type of data submitted in a POST"
1865 \& $content_type = $q\->content_type();
1868 The \fB\f(BIcontent_type()\fB\fR method returns the content_type of data submitted in
1869 a \s-1POST\s0, generally 'multipart/form\-data' or
1870 \&'application/x\-www\-form\-urlencoded' as supplied in \f(CW$ENV\fR{'\s-1CONTENT_TYPE\s0'}
1871 .Sh "\fIdocument_root()\fP Get the document root"
1872 .IX Subsection "document_root() Get the document root"
1874 \& $document_root = $q\->document_root();
1877 The \fB\f(BIdocument_root()\fB\fR method returns the value of \f(CW$ENV\fR{'\s-1DOCUMENT_ROOT\s0'}
1878 .Sh "\fIgateway_interface()\fP Get the gateway interface"
1879 .IX Subsection "gateway_interface() Get the gateway interface"
1881 \& $gateway_interface = $q\->gateway_interface();
1884 The \fB\f(BIgateway_interface()\fB\fR method returns the value of
1885 \&\f(CW$ENV\fR{'\s-1GATEWAY_INTERFACE\s0'}
1886 .Sh "\fIpath_translated()\fP Get the value of path translated"
1887 .IX Subsection "path_translated() Get the value of path translated"
1889 \& $path_translated = $q\->path_translated();
1892 The \fB\f(BIpath_translated()\fB\fR method returns the value of \f(CW$ENV\fR{'\s-1PATH_TRANSLATED\s0'}
1893 .Sh "\fIreferer()\fP Spy on your users"
1894 .IX Subsection "referer() Spy on your users"
1896 \& $referer = $q\->referer();
1899 The \fB\f(BIreferer()\fB\fR method returns the value of \f(CW$ENV\fR{'\s-1REFERER\s0'} This will return
1900 the \s-1URL\s0 of the page the browser was viewing prior to fetching your script.
1901 Not available for all browsers.
1902 .Sh "\fIremote_addr()\fP Get the remote address"
1903 .IX Subsection "remote_addr() Get the remote address"
1905 \& $remote_addr = $q\->remote_addr();
1908 The \fB\f(BIremote_addr()\fB\fR method returns the value of \f(CW$ENV\fR{'\s-1REMOTE_ADDR\s0'} or
1909 127.0.0.1 (localhost) if this is not defined.
1910 .Sh "\fIremote_host()\fP Get a value for remote host"
1911 .IX Subsection "remote_host() Get a value for remote host"
1913 \& $remote_host = $q\->remote_host();
1916 The \fB\f(BIremote_host()\fB\fR method returns the value of \f(CW$ENV\fR{'\s-1REMOTE_HOST\s0'} if it is
1917 defined. If this is not defined it returns \f(CW$ENV\fR{'\s-1REMOTE_ADDR\s0'} If this is not
1918 defined it returns 'localhost'
1919 .Sh "\fIremote_ident()\fP Get the remote identity"
1920 .IX Subsection "remote_ident() Get the remote identity"
1922 \& $remote_ident = $q\->remote_ident();
1925 The \fB\f(BIremote_ident()\fB\fR method returns the value of \f(CW$ENV\fR{'\s-1REMOTE_IDENT\s0'}
1926 .Sh "\fIremote_user()\fP Get the remote user"
1927 .IX Subsection "remote_user() Get the remote user"
1929 \& $remote_user = $q\->remote_user();
1932 The \fB\f(BIremote_user()\fB\fR method returns the authorization/verification name used
1933 for user verification, if this script is protected. The value comes from
1934 \&\f(CW$ENV\fR{'\s-1REMOTE_USER\s0'}
1935 .Sh "\fIrequest_method()\fP Get the request method"
1936 .IX Subsection "request_method() Get the request method"
1938 \& $request_method = $q\->request_method();
1941 The \fB\f(BIrequest_method()\fB\fR method returns the method used to access your
1942 script, usually one of '\s-1POST\s0', '\s-1GET\s0' or '\s-1HEAD\s0' as supplied by
1943 \&\f(CW$ENV\fR{'\s-1REQUEST_METHOD\s0'}
1944 .Sh "\fIscript_name()\fP Get the script name"
1945 .IX Subsection "script_name() Get the script name"
1947 \& $script_name = $q\->script_name();
1950 The \fB\f(BIscript_name()\fB\fR method returns the value of \f(CW$ENV\fR{'\s-1SCRIPT_NAME\s0'} if it is
1951 defined. Otherwise it returns Perl's script name from \f(CW$0\fR. Failing this it
1952 returns a null string ''
1953 .Sh "\fIserver_name()\fP Get the server name"
1954 .IX Subsection "server_name() Get the server name"
1956 \& $server_name = $q\->server_name();
1959 The \fB\f(BIserver_name()\fB\fR method returns the value of \f(CW$ENV\fR{'\s-1SERVER_NAME\s0'} if defined
1960 or 'localhost' otherwise
1961 .Sh "\fIserver_port()\fP Get the port the server is listening on"
1962 .IX Subsection "server_port() Get the port the server is listening on"
1964 \& $server_port = $q\->server_port();
1967 The \fB\f(BIserver_port()\fB\fR method returns the value \f(CW$ENV\fR{'\s-1SERVER_PORT\s0'} if defined or
1969 .Sh "\fIserver_protocol()\fP Get the current server protocol"
1970 .IX Subsection "server_protocol() Get the current server protocol"
1972 \& $server_protocol = $q\->server_protocol();
1975 The \fB\f(BIserver_protocol()\fB\fR method returns the value of \f(CW$ENV\fR{'\s-1SERVER_PROTOCOL\s0'} if
1976 defined or '\s-1HTTP/1\s0.0' otherwise
1977 .Sh "\fIserver_software()\fP Get the server software"
1978 .IX Subsection "server_software() Get the server software"
1980 \& $server_software = $q\->server_software();
1983 The \fB\f(BIserver_software()\fB\fR method returns the value \f(CW$ENV\fR{'\s-1SERVER_SOFTWARE\s0'} or
1984 \&'cmdline' If the server software is \s-1IIS\s0 it formats your hard drive, installs
1985 Linux, FTPs to www.apache.org, installs Apache, and then restores your system
1986 from tape. Well maybe not, but it's a nice thought.
1987 .Sh "\fIuser_name()\fP Get a value for the user name."
1988 .IX Subsection "user_name() Get a value for the user name."
1990 \& $user_name = $q\->user_name();
1993 Attempt to obtain the remote user's name, using a variety of different
1994 techniques. This only works with older browsers such as Mosaic.
1995 Newer browsers do not report the user name for privacy reasons!
1997 Technically the \fB\f(BIuser_name()\fB\fR method returns the value of \f(CW$ENV\fR{'\s-1HTTP_FROM\s0'}
1998 or failing that \f(CW$ENV\fR{'\s-1REMOTE_IDENT\s0'} or as a last choice \f(CW$ENV\fR{'\s-1REMOTE_USER\s0'}
1999 .Sh "\fIuser_agent()\fP Get the users browser type"
2000 .IX Subsection "user_agent() Get the users browser type"
2002 \& $ua = $q\->user_agent(); # return the user agent
2003 \& $ok = $q\->user_agent('mozilla'); # return true if user agent 'mozilla'
2006 The \fB\f(BIuser_agent()\fB\fR method returns the value of \f(CW$ENV\fR{'\s-1HTTP_USER_AGENT\s0'} when
2007 called without an argument or true or false if the \f(CW$ENV\fR{'\s-1HTTP_USER_AGENT\s0'}
2008 matches the passed argument. The matching is case insensitive and partial.
2009 .Sh "\fIvirtual_host()\fP Get the virtual host"
2010 .IX Subsection "virtual_host() Get the virtual host"
2012 \& $virtual_host = $q\->virtual_host();
2015 The \fB\f(BIvirtual_host()\fB\fR method returns the value of \f(CW$ENV\fR{'\s-1HTTP_HOST\s0'} if defined
2016 or \f(CW$ENV\fR{'\s-1SERVER_NAME\s0'} as a default. Port numbers are removed.
2017 .Sh "\fIpath_info()\fP Get any extra path info set to the script"
2018 .IX Subsection "path_info() Get any extra path info set to the script"
2020 \& $path_info = $q\->path_info();
2023 The \fB\f(BIpath_info()\fB\fR method returns additional path information from the script
2024 \&\s-1URL\s0. E.G. fetching /cgi\-bin/your_script/additional/stuff will result in
2025 \&\f(CW$q\fR\->\fIpath_info()\fR returning \*(L"/additional/stuff\*(R".
2027 \&\s-1NOTE:\s0 The Microsoft Internet Information Server
2028 is broken with respect to additional path information. If
2029 you use the Perl \s-1DLL\s0 library, the \s-1IIS\s0 server will attempt to
2030 execute the additional path information as a Perl script.
2031 If you use the ordinary file associations mapping, the
2032 path information will be present in the environment,
2033 but incorrect. The best thing to do is to avoid using additional
2034 path information in \s-1CGI\s0 scripts destined for use with \s-1IIS\s0.
2035 .Sh "\fIAccept()\fP Get the browser \s-1MIME\s0 types"
2036 .IX Subsection "Accept() Get the browser MIME types"
2038 \& $Accept = $q\->Accept();
2041 The \fB\f(BIAccept()\fB\fR method returns a list of \s-1MIME\s0 types that the remote browser
2042 accepts. If you give this method a single argument corresponding to a
2043 \&\s-1MIME\s0 type, as in \f(CW$q\fR\->Accept('text/html'), it will return a floating point
2044 value corresponding to the browser's preference for this type from 0.0
2045 (don't want) to 1.0. Glob types (e.g. text/*) in the browser's accept
2046 list are handled correctly.
2047 .Sh "\fIaccept()\fP Alias for \fIAccept()\fP"
2048 .IX Subsection "accept() Alias for Accept()"
2050 \& $accept = $q\->accept();
2053 The \fB\f(BIaccept()\fB\fR Method is an alias for \fIAccept()\fR
2054 .Sh "\fIhttp()\fP Get a range of \s-1HTTP\s0 related information"
2055 .IX Subsection "http() Get a range of HTTP related information"
2057 \& $http = $q\->http();
2060 Called with no arguments the \fB\f(BIhttp()\fB\fR method returns the list of \s-1HTTP\s0 or \s-1HTTPS\s0
2061 environment variables, including such things as \s-1HTTP_USER_AGENT\s0,
2062 \&\s-1HTTP_ACCEPT_LANGUAGE\s0, and \s-1HTTP_ACCEPT_CHARSET\s0, corresponding to the
2063 like-named \s-1HTTP\s0 header fields in the request. Called with the name of
2064 an \s-1HTTP\s0 header field, returns its value. Capitalization and the use
2065 of hyphens versus underscores are not significant.
2067 For example, all three of these examples are equivalent:
2070 \& $requested_language = $q\->http('Accept\-language');
2071 \& $requested_language = $q\->http('Accept_language');
2072 \& $requested_language = $q\->http('HTTP_ACCEPT_LANGUAGE');
2074 .Sh "\fIhttps()\fP Get a range of \s-1HTTPS\s0 related information"
2075 .IX Subsection "https() Get a range of HTTPS related information"
2077 \& $https = $q\->https();
2080 The \fB\f(BIhttps()\fB\fR method is similar to the \fIhttp()\fR method except that when called
2081 without an argument it returns the value of \f(CW$ENV\fR{'\s-1HTTPS\s0'} which will be
2082 true if a \s-1HTTPS\s0 connection is in use and false otherwise.
2083 .Sh "\fIprotocol()\fP Get the current protocol"
2084 .IX Subsection "protocol() Get the current protocol"
2086 \& $protocol = $q\->protocol();
2089 The \fB\f(BIprotocol()\fB\fR method returns 'https' if a \s-1HTTPS\s0 connection is in use or the
2090 \&\fB\f(BIserver_protocol()\fB\fR minus version numbers ('http') otherwise.
2091 .Sh "\fIurl()\fP Return the script's \s-1URL\s0 in several formats"
2092 .IX Subsection "url() Return the script's URL in several formats"
2094 \& $full_url = $q\->url();
2095 \& $full_url = $q\->url(\-full=>1);
2096 \& $relative_url = $q\->url(\-relative=>1);
2097 \& $absolute_url = $q\->url(\-absolute=>1);
2098 \& $url_with_path = $q\->url(\-path_info=>1);
2099 \& $url_with_path_and_query = $q\->url(\-path_info=>1,\-query=>1);
2100 \& $netloc = $q\->url(\-base => 1);
2103 \&\fB\f(BIurl()\fB\fR returns the script's \s-1URL\s0 in a variety of formats. Called
2104 without any arguments, it returns the full form of the \s-1URL\s0, including
2105 host name and port number
2108 \& http://your.host.com/path/to/script.cgi
2111 You can modify this format with the following named arguments:
2112 .IP "\fB\-absolute\fR" 4
2113 .IX Item "-absolute"
2114 If true, produce an absolute \s-1URL\s0, e.g.
2117 \& /path/to/script.cgi
2119 .IP "\fB\-relative\fR" 4
2120 .IX Item "-relative"
2121 Produce a relative \s-1URL\s0. This is useful if you want to reinvoke your
2122 script with different parameters. For example:
2127 .IP "\fB\-full\fR" 4
2129 Produce the full \s-1URL\s0, exactly as if called without any arguments.
2130 This overrides the \-relative and \-absolute arguments.
2131 .IP "\fB\-path\fR (\fB\-path_info\fR)" 4
2132 .IX Item "-path (-path_info)"
2133 Append the additional path information to the \s-1URL\s0. This can be
2134 combined with \fB\-full\fR, \fB\-absolute\fR or \fB\-relative\fR. \fB\-path_info\fR
2135 is provided as a synonym.
2136 .IP "\fB\-query\fR (\fB\-query_string\fR)" 4
2137 .IX Item "-query (-query_string)"
2138 Append the query string to the \s-1URL\s0. This can be combined with
2139 \&\fB\-full\fR, \fB\-absolute\fR or \fB\-relative\fR. \fB\-query_string\fR is provided
2141 .IP "\fB\-base\fR" 4
2143 Generate just the protocol and net location, as in http://www.foo.com:8000
2144 .Sh "\fIself_url()\fP Get the scripts complete \s-1URL\s0"
2145 .IX Subsection "self_url() Get the scripts complete URL"
2147 \& $self_url = $q\->self_url();
2150 The \fB\f(BIself_url()\fB\fR method returns the value of:
2153 \& $self\->url( '\-path_info'=>1, '\-query'=>1, '\-full'=>1 );
2155 .Sh "\fIstate()\fP Alias for \fIself_url()\fP"
2156 .IX Subsection "state() Alias for self_url()"
2158 \& $state = $q\->state();
2161 The \fB\f(BIstate()\fB\fR method is an alias for \fIself_url()\fR
2162 .SH "COMPATIBILITY WITH cgi\-lib.pl 2.18"
2163 .IX Header "COMPATIBILITY WITH cgi-lib.pl 2.18"
2164 To make it easier to port existing programs that use cgi\-lib.pl all
2165 the subs within cgi\-lib.pl are available in CGI::Simple. Using the
2166 functional interface of CGI::Simple::Standard porting is
2171 \& require "cgi\-lib.pl";
2173 \& print "The value of the antique is $in{'antique'}.\en";
2178 \& use CGI::Simple::Standard qw(:cgi\-lib);
2180 \& print "The value of the antique is $in{'antique'}.\en";
2183 CGI:Simple's \fB\f(BIReadParse()\fB\fR routine creates a variable named \f(CW%in\fR,
2184 which can be accessed to obtain the query variables. Like
2185 ReadParse, you can also provide your own variable via a glob. Infrequently
2186 used features of \fB\f(BIReadParse()\fB\fR, such as the creation of \f(CW@in\fR and \f(CW$in\fR
2187 variables, are not supported.
2189 You can also use the \s-1OO\s0 interface of CGI::Simple and call \fB\f(BIReadParse()\fB\fR and
2190 other cgi\-lib.pl functions like this:
2193 \& &CGI::Simple::ReadParse; # get hash values in %in
2197 \& my $q = new CGI::Simple;
2198 \& $q\->ReadParse(); # same thing
2202 \& CGI::Simple::ReadParse(*field); # get hash values in %field function style
2206 \& my $q = new CGI::Simple;
2207 \& $q\->ReadParse(*field); # same thing
2210 Once you use \fB\f(BIReadParse()\fB\fR under the functional interface , you can retrieve
2211 the query object itself this way if needed:
2217 Either way it allows you to start using the more interesting features
2218 of \s-1CGI\s0.pm without rewriting your old scripts from scratch.
2220 Unlike \s-1CGI\s0.pm all the cgi\-lib.pl functions from Version 2.18 are supported:
2238 .SH "COMPATIBILITY WITH CGI.pm"
2239 .IX Header "COMPATIBILITY WITH CGI.pm"
2240 I has long been suggested that the \s-1CGI\s0 and \s-1HTML\s0 parts of \s-1CGI\s0.pm should be
2241 split into separate modules (even the author suggests this!), CGI::Simple
2242 represents the realization of this and contains the complete \s-1CGI\s0 side of
2243 \&\s-1CGI\s0.pm. Code-wise it weighs in at a little under 30% of the size of \s-1CGI\s0.pm at
2244 a little under 1000 lines.
2246 A great deal of care has been taken to ensure that the interface remains
2247 unchanged although a few tweaks have been made. The test suite is extensive
2248 and includes all the \s-1CGI\s0.pm test scripts as well as a series of new test
2249 scripts. You may like to have a look at /t/concur.t which makes 160 tests
2250 of CGI::Simple and \s-1CGI\s0 in parallel and compares the results to ensure they
2251 are identical. This is the case as of \s-1CGI\s0.pm 2.78.
2253 You can't make an omelet without breaking eggs. A large number of methods
2254 and global variables have been deleted as detailed below. Some pragmas are
2255 also gone. In the tarball there is a script \fB/misc/check.pl\fR that will check if
2256 a script seems to be using any of these now non existent methods, globals or
2257 pragmas. You call it like this:
2260 \& perl check.pl <files>
2263 If it finds any likely candidates it will print a line with the line number,
2264 problem method/global and the complete line. For example here is some output
2265 from running the script on \s-1CGI\s0.pm:
2269 \& 3162: Problem:'$CGI::OS' local($CRLF) = "\e015\e012" if $CGI::OS eq 'VMS';
2270 \& 3165: Problem:'fillBuffer' $self\->fillBuffer($FILLUNIT);
2273 .SH "DIFFERENCES FROM CGI.pm"
2274 .IX Header "DIFFERENCES FROM CGI.pm"
2275 CGI::Simple is strict and warnings compliant.
2277 There are 4 modules in this distribution:
2280 \& CGI/Simple.pm supplies all the core code.
2281 \& CGI/Simple/Cookie.pm supplies the cookie handling functions.
2282 \& CGI/Simple/Util.pm supplies a variety of utility functions
2283 \& CGI/Simple/Standard.pm supplies a functional interface for Simple.pm
2286 Simple.pm is the core module that provide all the essential functionality.
2287 Cookie.pm is a shortened rehash of the \s-1CGI\s0.pm module of the same name
2288 which supplies the required cookie functionality. Util.pm has been recoded to
2289 use an internal object for data storage and supplies rarely needed non core
2290 functions and/or functions needed for the \s-1HTML\s0 side of things. Standard.pm is
2291 a wrapper module that supplies a complete functional interface to the \s-1OO\s0
2292 back end supplied by CGI::Simple.
2294 Although a serious attempt has been made to keep the interface identical,
2295 some minor changes and tweaks have been made. They will likely be
2296 insignificant to most users but here are the gory details.
2297 .Sh "Globals Variables"
2298 .IX Subsection "Globals Variables"
2299 The list of global variables has been pruned by 75%. Here is the complete
2300 list of the global variables used:
2303 \& $VERSION = "0.01";
2304 \& # set this to 1 to use CGI.pm default global settings
2305 \& $USE_CGI_PM_DEFAULTS = 0 unless defined $USE_CGI_PM_DEFAULTS;
2306 \& # see if user wants old CGI.pm defaults
2307 \& do{ _use_cgi_pm_global_settings(); return } if $USE_CGI_PM_DEFAULTS;
2308 \& # no file uploads by default, set to 0 to enable uploads
2309 \& $DISABLE_UPLOADS = 1 unless defined $DISABLE_UPLOADS;
2310 \& # use a post max of 100K, set to \-1 for no limits
2311 \& $POST_MAX = 102_400 unless defined $POST_MAX;
2312 \& # do not include undefined params parsed from query string
2313 \& $NO_UNDEF_PARAMS = 0 unless defined $NO_UNDEF_PARAMS;
2314 \& # separate the name=value pairs with ; rather than &
2315 \& $USE_PARAM_SEMICOLONS = 0 unless defined $USE_PARAM_SEMICOLONS;
2316 \& # only print headers once
2317 \& $HEADERS_ONCE = 0 unless defined $HEADERS_ONCE;
2318 \& # Set this to 1 to enable NPH scripts
2319 \& $NPH = 0 unless defined $NPH;
2320 \& # 0 => no debug, 1 => from @ARGV, 2 => from STDIN
2321 \& $DEBUG = 0 unless defined $DEBUG;
2322 \& # filter out null bytes in param \- value pairs
2323 \& $NO_NULL = 1 unless defined $NO_NULL;
2324 \& # set behavior when cgi_err() called \-1 => silent, 0 => carp, 1 => croak
2325 \& $FATAL = \-1 unless defined $FATAL;
2328 Four of the default values of the old \s-1CGI\s0.pm variables have been changed.
2329 Unlike \s-1CGI\s0.pm which by default allows unlimited \s-1POST\s0 data and file uploads
2330 by default CGI::Simple limits \s-1POST\s0 data size to 100kB and denies file uploads
2331 by default. \f(CW$USE_PARAM_SEMICOLONS\fR is set to 0 by default so we use (old style)
2332 & rather than ; as the pair separator for query strings. Debugging is
2333 disabled by default.
2335 There are three new global variables. If \f(CW$NO_NULL\fR is true (the default) then
2336 CGI::Simple will strip null bytes out of names, values and keywords. Null
2337 bytes can do interesting things to C based code like Perl. Uploaded files
2338 are not touched. \f(CW$FATAL\fR controls the behavior when \fB\f(BIcgi_error()\fB\fR is called.
2339 The default value of \-1 makes errors silent. \f(CW$USE_CGI_PM_DEFAULTS\fR reverts the
2340 defaults to the \s-1CGI\s0.pm standard values ie unlimited file uploads via \s-1POST\s0
2341 for \s-1DNS\s0 attacks. You can also get the defaults back by using the '\-default'
2345 \& use CGI::Simple qw(\-default);
2346 \& use CGI::Simple::Standard qw(\-default);
2349 The values of the global variables are stored in the CGI::Simple object and
2350 can be referenced and changed using the \fB\f(BIglobals()\fB\fR method like this:
2353 \& my $value = $q\->globals( 'VARNAME' ); # get
2354 \& $q\->globals( 'VARNAME', 'some value' ); # set
2357 As with many \s-1CGI\s0.pm methods if you pass the optional value that will
2360 The \f(CW$CGI::Simple::VARNAME\fR = 'N' syntax is only useful prior to calling the
2361 \&\fB\f(BInew()\fB\fR constructor. After that all reference is to the values stored in the
2362 CGI::Simple object so you must change these using the \fB\f(BIglobals()\fB\fR method.
2364 $DISABLE_UPLOADS and \f(CW$POST_MAX\fR *must* be set prior to calling the constructor
2365 if you want the changes to have any effect as they control behavior during
2366 initialization. This is the same a \s-1CGI\s0.pm although some people seem to miss
2367 this rather important point and set these after calling the constructor which
2370 The following globals are no longer relevant and have all been deleted:
2373 \& $AUTOLOADED_ROUTINES
2383 \& $INITIAL_FILLUNIT
2391 \& $PRIVATE_TEMPFILES
2405 \& %QUERY_FIELDNAMES
2411 Notes: CGI::Simple uses IO::File\->new_tmpfile to get tempfile filehandles.
2412 These are private by default so \f(CW$PRIVATE_TEMPFILES\fR is no longer required nor
2413 is \f(CW$TMPDIRECTORY\fR. The value that were stored in \f(CW$OS\fR, \f(CW$CRLF\fR, \f(CW$QUERY_CHARSET\fR
2414 and \f(CW$EBCDIC\fR are now stored in the CGI::Simple::Util object where they find
2415 most of their use. The \f(CW$MOD_PERL\fR and \f(CW$PERLEX\fR values are now stored in our
2416 CGI::Simple object. \f(CW$IIS\fR was only used once in \fIpath_info()\fR. \f(CW$SL\fR the system
2417 specific / \e : path delimiter is not required as we let IO::File handle our
2418 tempfile requirements. The rest of the globals are \s-1HTML\s0 related, export
2419 related, hand rolled autoload related or serve obscure purposes in \s-1CGI\s0.pm
2420 .Sh "Changes to pragmas"
2421 .IX Subsection "Changes to pragmas"
2422 There are some new pragmas available. See the pragmas section for details.
2423 The following \s-1CGI\s0.pm pragmas are not available:
2430 \& \-private_tempfiles
2433 .IX Subsection "Filehandles"
2434 Unlike \s-1CGI\s0.pm which tries to accept all filehandle like objects only \e*FH
2435 and \f(CW$fh\fR are accepted by CGI::Simple as file accessors for \fB\f(BInew()\fB\fR and \fB\f(BIsave()\fB\fR.
2436 IO::File objects work fine.
2437 .Sh "Hash interface"
2438 .IX Subsection "Hash interface"
2440 \& %hash = $q\->Vars(); # pack values with "\e0";
2441 \& %hash = $q\->Vars(","); # comma separate values
2444 You may optionally pass \fB\f(BIVars()\fB\fR a string that will be used to separate multiple
2445 values when they are packed into the single hash value. If no value is
2446 supplied the default \*(L"\e0\*(R" (null byte) will be used. Null bytes are dangerous
2447 things for C based code (ie Perl).
2449 .IX Subsection "cgi-lib.pl"
2450 All the cgi\-lib.pl 2.18 routines are supported. Unlike \s-1CGI\s0.pm all the
2451 subroutines from cgi\-lib.pl are included. They have been \s-1GOLFED\s0 down to
2452 25 lines but they all work pretty much the same as the originals.
2453 .SH "CGI::Simple COMPLETE METHOD LIST"
2454 .IX Header "CGI::Simple COMPLETE METHOD LIST"
2455 Here is a complete list of all the CGI::Simple methods.
2456 .Sh "Guts (hands off, except of course for new)"
2457 .IX Subsection "Guts (hands off, except of course for new)"
2459 \& _initialize_globals
2460 \& _use_cgi_pm_global_settings
2469 \& _parse_keywordlist
2475 .IX Subsection "Core Methods"
2491 \& parse_query_string
2492 \& parse_keywordlist
2494 .Sh "Save and Restore from File Methods"
2495 .IX Subsection "Save and Restore from File Methods"
2501 .Sh "Miscellaneous Methods"
2502 .IX Subsection "Miscellaneous Methods"
2511 .Sh "Cookie Methods"
2512 .IX Subsection "Cookie Methods"
2517 .Sh "Header Methods"
2518 .IX Subsection "Header Methods"
2525 .Sh "Server Push Methods"
2526 .IX Subsection "Server Push Methods"
2533 .Sh "Debugging Methods"
2534 .IX Subsection "Debugging Methods"
2536 \& read_from_cmdline
2541 .Sh "cgi\-lib.pl Compatibility Routines \- all 2.18 functions available"
2542 .IX Subsection "cgi-lib.pl Compatibility Routines - all 2.18 functions available"
2560 .Sh "Accessor Methods"
2561 .IX Subsection "Accessor Methods"
2567 \& crlf # new, returns OS specific CRLF sequence
2568 \& globals # get/set global variables
2573 \& gateway_interface
2599 .SH "NEW METHODS IN CGI::Simple"
2600 .IX Header "NEW METHODS IN CGI::Simple"
2601 There are a few new methods in CGI::Simple as listed below. The highlights are
2602 the \fB\f(BIparse_query_string()\fB\fR method to add the \s-1QUERY_STRING\s0 data to your object if
2603 the method was \s-1POST\s0. The \fB\f(BIno_cache()\fB\fR method adds an expires now directive and
2604 the Pragma: no-cache directive to the header to encourage some browsers to
2605 do the right thing. \fB\f(BIPrintEnv()\fB\fR from the cgi\-lib.pl routines will dump an
2606 \&\s-1HTML\s0 friendly list of the \f(CW%ENV\fR and makes a handy addition to \fB\f(BIDump()\fB\fR for use
2607 in debugging. The upload method now accepts a filepath as an optional second
2608 argument as shown in the synopsis. If this is supplied the uploaded file will
2609 be written to there automagically.
2610 .Sh "Internal Routines"
2611 .IX Subsection "Internal Routines"
2613 \& _initialize_globals()
2614 \& _use_cgi_pm_global_settings()
2617 \& _init_from_file()
2621 \& _parse_keywordlist()
2622 \& _parse_multipart()
2626 .Sh "New Public Methods"
2627 .IX Subsection "New Public Methods"
2629 \& add_param() # adds a param/value(s) pair +/\- overwrite
2630 \& upload_info() # uploaded files MIME type and size
2631 \& url_decode() # decode s url encoded string
2632 \& url_encode() # url encode a string
2633 \& parse_query_string() # add QUERY_STRING data to $q object if 'POST'
2634 \& no_cache() # add both the Pragma: no\-cache
2635 \& # and Expires/Date => 'now' to header
2637 .Sh "cgi\-lib.pl methods added for completeness"
2638 .IX Subsection "cgi-lib.pl methods added for completeness"
2640 \& _shift_if_ref() # internal hack reminiscent of self_or_default :\-)
2650 .IX Subsection "New Accessors"
2652 \& crlf() # returns CRLF sequence
2653 \& globals() # global vars now stored in $q object \- get/set
2654 \& content_length() # returns $ENV{'CONTENT_LENGTH'}
2655 \& document_root() # returns $ENV{'DOCUMENT_ROOT'}
2656 \& gateway_interface() # returns $ENV{'GATEWAY_INTERFACE'}
2658 .SH "METHODS IN CGI.pm NOT IN CGI::Simple"
2659 .IX Header "METHODS IN CGI.pm NOT IN CGI::Simple"
2660 Here is a complete list of what is not included in CGI::Simple. Basically all
2661 the \s-1HTML\s0 related stuff plus large redundant chunks of the guts. The check.pl
2662 script in the /misc dir will check to see if a script is using any of these.
2663 .Sh "Guts \- rearranged, recoded, renamed and hacked out of existence"
2664 .IX Subsection "Guts - rearranged, recoded, renamed and hacked out of existence"
2666 \& initialize_globals()
2669 \& self_or_default()
2681 \& new_MultipartBuffer()
2682 \& read_from_client()
2683 \& import_names() # I dislike this and left it out, so shoot me.
2685 .Sh "\s-1HTML\s0 Related"
2686 .IX Subsection "HTML Related"
2699 \& end_multipart_form()
2700 \& start_multipart_form()
2724 .Sh "Upload Related"
2725 .IX Subsection "Upload Related"
2726 CGI::Simple uses anonymous tempfiles supplied by IO::File to spool uploaded
2730 \& private_tempfiles() # automatic in CGI::Simple
2731 \& tmpFileName() # all upload files are anonymous
2732 \& uploadInfo() # relied on FH access, replaced with upload_info()
2734 .Sh "Really Private Subs (marked as so)"
2735 .IX Subsection "Really Private Subs (marked as so)"
2737 \& previous_or_default()
2738 \& register_parameter()
2740 \& _set_values_and_labels()
2745 .Sh "Internal Multipart Parsing Routines"
2746 .IX Subsection "Internal Multipart Parsing Routines"
2758 .SH "AUTHOR INFORMATION"
2759 .IX Header "AUTHOR INFORMATION"
2760 Originally copyright 2001 Dr James Freeman <jfreeman@tassie.net.au>
2761 This release by Andy Armstrong <andy@hexten.net>
2763 This package is free software and is provided \*(L"as is\*(R" without express or
2764 implied warranty. It may be used, redistributed and/or modified under the terms
2765 of the Perl Artistic License (see http://www.perl.com/perl/misc/Artistic.html)
2767 Address bug reports and comments to: andy@hexten.net. When sending
2768 bug reports, please provide the version of CGI::Simple, the version of
2769 Perl, the name and version of your Web server, and the name and
2770 version of the operating system you are using. If the problem is even
2771 remotely browser dependent, please provide information about the
2772 affected browsers as well.
2774 Address bug reports and comments to: andy@hexten.net
2776 .IX Header "CREDITS"
2777 Lincoln D. Stein (lstein@cshl.org) and everyone else who worked on the
2778 original \s-1CGI\s0.pm upon which this module is heavily based
2780 Brandon Black for some heavy duty testing and bug fixes
2782 John D Robinson and Jeroen Latour for helping solve some interesting test
2783 failures as well as Perlmonks:
2784 tommyw, grinder, Jaap, vek, erasei, jlongino and strider_corinth
2786 Thanks for patches to:
2788 Ewan Edwards, Joshua N Pritikin, Mike Barry
2789 .SH "LICENCE AND COPYRIGHT"
2790 .IX Header "LICENCE AND COPYRIGHT"
2791 Copyright (c) 2007, Andy Armstrong \f(CW\*(C`<andy@hexten.net>\*(C'\fR. All rights reserved.
2793 This module is free software; you can redistribute it and/or
2794 modify it under the same terms as Perl itself. See perlartistic.
2796 .IX Header "SEE ALSO"
2797 \&\fB\s-1CGI\s0\fR, CGI::Simple::Standard, CGI::Simple::Cookie,
2798 CGI::Simple::Util, CGI::Minimal
projects / catagits/Gitalist.git / blob