1CGI::Simple(3)        User Contributed Perl Documentation       CGI::Simple(3)
2
3
4

NAME

6       CGI::Simple - A Simple totally OO CGI interface that is CGI.pm
7       compliant
8

VERSION

10       This document describes CGI::Simple version 1.25.
11

SYNOPSIS

13           use CGI::Simple;
14           $CGI::Simple::POST_MAX = 1024;       # max upload via post default 100kB
15           $CGI::Simple::DISABLE_UPLOADS = 0;   # enable uploads
16
17           $q = CGI::Simple->new;
18           $q = CGI::Simple->new( { 'foo'=>'1', 'bar'=>[2,3,4] } );
19           $q = CGI::Simple->new( 'foo=1&bar=2&bar=3&bar=4' );
20           $q = CGI::Simple->new( \*FILEHANDLE );
21
22           $q->save( \*FILEHANDLE );   # save current object to a file as used by new
23
24           @params = $q->param;        # return all param names as a list
25           $value = $q->param('foo');  # return the first value supplied for 'foo'
26           @values = $q->param('foo'); # return all values supplied for foo
27
28           %fields   = $q->Vars;      # returns untied key value pair hash
29           $hash_ref = $q->Vars;      # or as a hash ref
30           %fields   = $q->Vars("|"); # packs multiple values with "|" rather than "\0";
31
32           @keywords = $q->keywords;  # return all keywords as a list
33
34           $q->param( 'foo', 'some', 'new', 'values' );      # set new 'foo' values
35           $q->param( -name=>'foo', -value=>'bar' );
36           $q->param( -name=>'foo', -value=>['bar','baz'] );
37
38           $q->param( 'foo', 'some', 'new', 'values' );      # append values to 'foo'
39           $q->append( -name=>'foo', -value=>'bar' );
40           $q->append( -name=>'foo', -value=>['some', 'new', 'values'] );
41
42           $q->delete('foo'); # delete param 'foo' and all its values
43           $q->delete_all;    # delete everything
44
45           <INPUT TYPE="file" NAME="upload_file" SIZE="42">
46
47           $files    = $q->upload()                # number of files uploaded
48           @files    = $q->upload();               # names of all uploaded files
49           $filename = $q->param('upload_file')    # filename of uploaded file
50           $mime     = $q->upload_info($filename,'mime'); # MIME type of uploaded file
51           $size     = $q->upload_info($filename,'size'); # size of uploaded file
52
53           my $fh = $q->upload($filename);         # get filehandle to read from
54           while ( read( $fh, $buffer, 1024 ) ) { ... }
55
56           # short and sweet upload
57           $ok = $q->upload( $q->param('upload_file'), '/path/to/write/file.name' );
58           print "Uploaded ".$q->param('upload_file')." and wrote it OK!" if $ok;
59
60           $decoded    = $q->url_decode($encoded);
61           $encoded    = $q->url_encode($unencoded);
62           $escaped    = $q->escapeHTML('<>"&');
63           $unescaped  = $q->unescapeHTML('&lt;&gt;&quot;&amp;');
64
65           $qs = $q->query_string; # get all data in $q as a query string OK for GET
66
67           $q->no_cache(1);        # set Pragma: no-cache + expires
68           print $q->header();     # print a simple header
69           # get a complex header
70           $header = $q->header(   -type       => 'image/gif'
71                                   -nph        => 1,
72                                   -status     => '402 Payment required',
73                                   -expires    =>'+24h',
74                                   -cookie     => $cookie,
75                                   -charset    => 'utf-7',
76                                   -attachment => 'foo.gif',
77                                   -Cost       => '$2.00'
78                               );
79           # a p3p header (OK for redirect use as well)
80           $header = $q->header( -p3p => 'policyref="http://somesite.com/P3P/PolicyReferences.xml' );
81
82           @cookies = $q->cookie();        # get names of all available cookies
83           $value   = $q->cookie('foo')    # get first value of cookie 'foo'
84           @value   = $q->cookie('foo')    # get all values of cookie 'foo'
85           # get a cookie formatted for header() method
86           $cookie  = $q->cookie(  -name    => 'Password',
87                                   -values  => ['superuser','god','my dog woofie'],
88                                   -expires => '+3d',
89                                   -domain  => '.nowhere.com',
90                                   -path    => '/cgi-bin/database',
91                                   -secure  => 1
92                                );
93           print $q->header( -cookie=>$cookie );       # set cookie
94
95           print $q->redirect('http://go.away.now');   # print a redirect header
96
97           dienice( $q->cgi_error ) if $q->cgi_error;
98

DESCRIPTION

100       CGI::Simple provides a relatively lightweight drop in replacement for
101       CGI.pm.  It shares an identical OO interface to CGI.pm for parameter
102       parsing, file upload, cookie handling and header generation. This
103       module is entirely object oriented, however a complete functional
104       interface is available by using the CGI::Simple::Standard module.
105
106       Essentially everything in CGI.pm that relates to the CGI (not HTML)
107       side of things is available. There are even a few new methods and
108       additions to old ones! If you are interested in what has gone on under
109       the hood see the Compatibility with CGI.pm section at the end.
110
111       In practical testing this module loads and runs about twice as fast as
112       CGI.pm depending on the precise task.
113

CALLING CGI::Simple ROUTINES USING THE OBJECT INTERFACE

115       Here is a very brief rundown on how you use the interface. Full details
116       follow.
117
118   First you need to initialize an object
119       Before you can call a CGI::Simple method you must create a CGI::Simple
120       object.  You do that by using the module and then calling the new()
121       constructor:
122
123           use CGI::Simple;
124           my $q = CGI::Simple->new;
125
126       It is traditional to call your object $q for query or perhaps $cgi.
127
128   Next you call methods on that object
129       Once you have your object you can call methods on it using the -> arrow
130       syntax For example to get the names of all the parameters passed to
131       your script you would just write:
132
133           @names = $q->param();
134
135       Many methods are sensitive to the context in which you call them. In
136       the example above the param() method returns a list of all the
137       parameter names when called without any arguments.
138
139       When you call param('arg') with a single argument it assumes you want
140       to get the value(s) associated with that argument (parameter). If you
141       ask for an array it gives you an array of all the values associated
142       with it's argument:
143
144           @values = $q->param('foo');  # get all the values for 'foo'
145
146       whereas if you ask for a scalar like this:
147
148           $value = $q->param('foo');   # get only the first value for 'foo'
149
150       then it returns only the first value (if more than one value for 'foo'
151       exists).
152
153       In case you ased for a list it will return all the values preserving
154       the order in which the values of the given key were passed in the
155       request.
156
157       Most CGI::Simple routines accept several arguments, sometimes as many
158       as 10 optional ones!  To simplify this interface, all routines use a
159       named argument calling style that looks like this:
160
161           print $q->header( -type=>'image/gif', -expires=>'+3d' );
162
163       Each argument name is preceded by a dash.  Neither case nor order
164       matters in the argument list.  -type, -Type, and -TYPE are all
165       acceptable.
166
167       Several routines are commonly called with just one argument.  In the
168       case of these routines you can provide the single argument without an
169       argument name.  header() happens to be one of these routines.  In this
170       case, the single argument is the document type.
171
172          print $q->header('text/html');
173
174       Sometimes methods expect a scalar, sometimes a reference to an array,
175       and sometimes a reference to a hash.  Often, you can pass any type of
176       argument and the routine will do whatever is most appropriate.  For
177       example, the param() method can be used to set a CGI parameter to a
178       single or a multi-valued value.  The two cases are shown below:
179
180          $q->param(-name=>'veggie',-value=>'tomato');
181          $q->param(-name=>'veggie',-value=>['tomato','tomahto','potato','potahto']);
182

CALLING CGI::Simple ROUTINES USING THE FUNCTION INTERFACE

184       For convenience a functional interface is provided by the
185       CGI::Simple::Standard module. This hides the OO details from you and
186       allows you to simply call methods. You may either use AUTOLOADING of
187       methods or import specific method sets into you namespace. Here are the
188       first few examples again using the function interface.
189
190           use CGI::Simple::Standard qw(-autoload);
191           @names  = param();
192           @values = param('foo');
193           $value  = param('foo');
194           print header(-type=>'image/gif',-expires=>'+3d');
195           print header('text/html');
196
197       Yes that's it. Not a $q-> in sight. You just use the module and select
198       how/which methods to load. You then just call the methods you want
199       exactly as before but without the $q-> notation.
200
201       When (if) you read the following docs and are using the functional
202       interface just pretend the $q-> is not there.
203
204   Selecting which methods to load
205       When you use the functional interface Perl needs to be able to find the
206       functions you call. The simplest way of doing this is to use
207       autoloading as shown above. When you use CGI::Simple::Standard with the
208       '-autoload' pragma it exports a single AUTOLOAD sub into you namespace.
209       Every time you call a non existent function AUTOLOAD is called and will
210       load the required function and install it in your namespace. Thus only
211       the AUTOLOAD sub and those functions you specifically call will be
212       imported.
213
214       Alternatively CGI::Simple::Standard provides a range of function sets
215       you can import or you can just select exactly what you want. You do
216       this using the familiar
217
218           use CGI::Simple::Standard qw( :func_set  some_func);
219
220       notation. This will import the ':func_set' function set and the
221       specific function 'some_func'.
222
223   To Autoload or not to Autoload, that is the question.
224       If you do not have a AUTOLOAD sub in you script it is generally best to
225       use the '-autoload' option. Under autoload you can use any method you
226       want but only import and compile those functions you actually use.
227
228       If you do not use autoload you must specify what functions to import.
229       You can only use functions that you have imported. For comvenience
230       functions are grouped into related sets. If you choose to import one or
231       more ':func_set' you may have potential namespace collisions so check
232       out the docs to see what gets imported. Using the ':all' tag is pretty
233       slack but it is there if you want. Full details of the function sets
234       are provided in the CGI::Simple::Standard docs
235
236       If you just want say the param and header methods just load these two.
237
238           use CGI::Simple::Standard qw(param header);
239
240   Setting globals using the functional interface
241       Where you see global variables being set using the syntax:
242
243           $CGI::Simple::DEBUG = 1;
244
245       You use exactly the same syntax when using CGI::Simple::Standard.
246

THE CORE METHODS

248   new() Creating a new query object
249       The first step in using CGI::Simple is to create a new query object
250       using the new() constructor:
251
252            $q = CGI::Simple->new;
253
254       This will parse the input (from both POST and GET methods) and store it
255       into an object called $q.
256
257       If you provide a file handle to the new() method, it will read
258       parameters from the file (or STDIN, or whatever).
259
260       Historically people were doing this way:
261
262            open FH, "test.in" or die $!;
263            $q = CGI::Simple->new(\*FH);
264
265       but this is the recommended way:
266
267            open $fh, '<', "test.in" or die $!;
268            $q = CGI::Simple->new($fh);
269
270       The file should be a series of newline delimited TAG=VALUE pairs.
271       Conveniently, this type of file is created by the save() method (see
272       below). Multiple records can be saved and restored.  IO::File objects
273       work fine.
274
275       If you are using the function-oriented interface provided by
276       CGI::Simple::Standard and want to initialize from a file handle, the
277       way to do this is with restore_parameters().  This will (re)initialize
278       the default CGI::Simple object from the indicated file handle.
279
280           restore_parameters($fh);
281
282       In fact for all intents and purposes restore_parameters() is identical
283       to new() Note that restore_parameters() does not exist in CGI::Simple
284       itself so you can't use it.
285
286       You can also initialize the query object from an associative array
287       reference:
288
289           $q = CGI::Simple->new( { 'dinosaur' => 'barney',
290                                   'song'     => 'I love you',
291                                   'friends'  => [qw/Jessica George Nancy/] }
292                               );
293
294       or from a properly formatted, URL-escaped query string:
295
296           $q = CGI::Simple->new( 'dinosaur=barney&color=purple' );
297
298       or from a previously existing CGI::Simple object (this generates an
299       identical clone including all global variable settings, etc that are
300       stored in the object):
301
302           $old_query = CGI::Simple->new;
303           $new_query = CGI::Simple->new($old_query);
304
305       To create an empty query, initialize it from an empty string or hash:
306
307           $empty_query = CGI::Simple->new("");
308
309              -or-
310
311           $empty_query = CGI::Simple->new({});
312
313   keywords() Fetching a list of keywords from a query
314           @keywords = $q->keywords;
315
316       If the script was invoked as the result of an <ISINDEX> search, the
317       parsed keywords can be obtained as an array using the keywords()
318       method.
319
320   param() Fetching the names of all parameters passed to your script
321           @names = $q->param;
322
323       If the script was invoked with a parameter list (e.g.
324       "name1=value1&name2=value2&name3=value3"), the param() method will
325       return the parameter names as a list.  If the script was invoked as an
326       <ISINDEX> script and contains a string without ampersands (e.g.
327       "value1+value2+value3") , there will be a single parameter named
328       "keywords" containing the "+"-delimited keywords.
329
330       NOTE: The array of parameter names returned will be in the same order
331       as they were submitted by the browser.  Usually this order is the same
332       as the order in which the parameters are defined in the form (however,
333       this isn't part of the spec, and so isn't guaranteed).
334
335   param() Fetching the value or values of a simple named parameter
336           @values = $q->param('foo');
337
338                 -or-
339
340           $value = $q->param('foo');
341
342       Pass the param() method a single argument to fetch the value of the
343       named parameter. If the parameter is multi-valued (e.g. from multiple
344       selections in a scrolling list), you can ask to receive an array.
345       Otherwise the method will return a single value.
346
347       If a value is not given in the query string, as in the queries
348       "name1=&name2=" or "name1&name2", it will be returned by default as an
349       empty string. If you set the global variable:
350
351           $CGI::Simple::NO_UNDEF_PARAMS = 1;
352
353       Then value-less parameters will be ignored, and will not exist in the
354       query object. If you try to access them via param you will get an undef
355       return value.
356
357   param() Setting the values of a named parameter
358           $q->param('foo','an','array','of','values');
359
360       This sets the value for the named parameter 'foo' to an array of
361       values.  This is one way to change the value of a field.
362
363       param() also recognizes a named parameter style of calling described in
364       more detail later:
365
366           $q->param(-name=>'foo',-values=>['an','array','of','values']);
367
368                         -or-
369
370           $q->param(-name=>'foo',-value=>'the value');
371
372   param() Retrieving non-application/x-www-form-urlencoded data
373       If POSTed or PUTed data is not of type
374       application/x-www-form-urlencoded or multipart/form-data, then the data
375       will not be processed, but instead be returned as-is in a parameter
376       named POSTDATA or PUTDATA.  To retrieve it, use code like this:
377
378           my $data = $q->param( 'POSTDATA' );
379
380                         -or-
381
382           my $data = $q->param( 'PUTDATA' );
383
384       (If you don't know what the preceding means, don't worry about it.  It
385       only affects people trying to use CGI::Simple for REST webservices)
386
387   add_param() Setting the values of a named parameter
388       You nay also use the new method add_param to add parameters. This is an
389       alias to the _add_param() internal method that actually does all the
390       work.  You can call it like this:
391
392           $q->add_param('foo', 'new');
393           $q->add_param('foo', [1,2,3,4,5]);
394           $q->add_param( 'foo', 'bar', 'overwrite' );
395
396       The first argument is the parameter, the second the value or an array
397       ref of values and the optional third argument sets overwrite mode. If
398       the third argument is absent of false the values will be appended. If
399       true the values will overwrite any existing ones
400
401   append() Appending values to a named parameter
402          $q->append(-name=>'foo',-values=>['yet','more','values']);
403
404       This adds a value or list of values to the named parameter.  The values
405       are appended to the end of the parameter if it already exists.
406       Otherwise the parameter is created.  Note that this method only
407       recognizes the named argument calling syntax.
408
409   import_names() Importing all parameters into a namespace.
410       This method was silly, non OO and has been deleted. You can get all the
411       params as a hash using Vars or via all the other accessors.
412
413   delete() Deleting a parameter completely
414           $q->delete('foo');
415
416       This completely clears a parameter. If you are using the function call
417       interface, use Delete() instead to avoid conflicts with Perl's built-in
418       delete operator.
419
420       If you are using the function call interface, use Delete() instead to
421       avoid conflicts with Perl's built-in delete operator.
422
423   delete_all() Deleting all parameters
424           $q->delete_all();
425
426       This clears the CGI::Simple object completely. For CGI.pm compatibility
427       Delete_all() is provided however there is no reason to use this in the
428       function call interface other than symmetry.
429
430       For CGI.pm compatibility Delete_all() is provided as an alias for
431       delete_all however there is no reason to use this, even in the function
432       call interface.
433
434   param_fetch() Direct access to the parameter list
435       This method is provided for CGI.pm compatibility only. It returns an
436       array ref to the values associated with a named param. It is
437       deprecated.
438
439   Vars() Fetching the entire parameter list as a hash
440           $params = $q->Vars;  # as a tied hash ref
441           print $params->{'address'};
442           @foo = split "\0", $params->{'foo'};
443
444           %params = $q->Vars;  # as a plain hash
445           print $params{'address'};
446           @foo = split "\0", $params{'foo'};
447
448           %params = $q->Vars(','); # specifying a different separator than "\0"
449           @foo = split ',', $params{'foo'};
450
451       Many people want to fetch the entire parameter list as a hash in which
452       the keys are the names of the CGI parameters, and the values are the
453       parameters' values.  The Vars() method does this.
454
455       Called in a scalar context, it returns the parameter list as a tied
456       hash reference. Because this hash ref is tied changing a key/value
457       changes the underlying CGI::Simple object.
458
459       Called in a list context, it returns the parameter list as an ordinary
460       hash.  Changing this hash will not change the underlying CGI::Simple
461       object
462
463       When using Vars(), the thing you must watch out for are multi-valued
464       CGI parameters.  Because a hash cannot distinguish between scalar and
465       list context, multi-valued parameters will be returned as a packed
466       string, separated by the "\0" (null) character.  You must split this
467       packed string in order to get at the individual values.  This is the
468       convention introduced long ago by Steve Brenner in his cgi-lib.pl
469       module for Perl version 4.
470
471       You can change the character used to do the multiple value packing by
472       passing it to Vars() as an argument as shown.
473
474   url_param() Access the QUERY_STRING regardless of 'GET' or 'POST'
475       The url_param() method makes the QUERY_STRING data available regardless
476       of whether the REQUEST_METHOD was 'GET' or 'POST'. You can do anything
477       with url_param that you can do with param(), however the data set is
478       completely independent.
479
480       Technically what happens if you use this method is that the
481       QUERY_STRING data is parsed into a new CGI::Simple object which is
482       stored within the current object. url_param then just calls param() on
483       this new object.
484
485   parse_query_string() Add QUERY_STRING data to 'POST' requests
486       When the REQUEST_METHOD is 'POST' the default behavior is to ignore
487       name/value pairs or keywords in the $ENV{'QUERY_STRING'}. You can
488       override this by calling parse_query_string() which will add the
489       QUERY_STRING data to the data already in our CGI::Simple object if the
490       REQUEST_METHOD was 'POST'
491
492           $q = CGI::Simple->new;
493           $q->parse_query_string;  # add $ENV{'QUERY_STRING'} data to our $q object
494
495       If the REQUEST_METHOD was 'GET' then the QUERY_STRING will already be
496       stored in our object so parse_query_string will be ignored.
497
498       This is a new method in CGI::Simple that is not available in CGI.pm
499
500   save() Saving the state of an object to file
501           $q->save(\*FILEHANDLE)
502
503       This will write the current state of the form to the provided
504       filehandle.  You can read it back in by providing a filehandle to the
505       new() method.
506
507       The format of the saved file is:
508
509           NAME1=VALUE1
510           NAME1=VALUE1'
511           NAME2=VALUE2
512           NAME3=VALUE3
513           =
514
515       Both name and value are URL escaped.  Multi-valued CGI parameters are
516       represented as repeated names.  A session record is delimited by a
517       single = symbol.  You can write out multiple records and read them back
518       in with several calls to new().
519
520           open my $fh, '<', "test.in" or die $!;
521           $q1 = CGI::Simple->new($fh);  # get the first record
522           $q2 = CGI::Simple->new($fh);  # get the next record
523
524       Note: If you wish to use this method from the function-oriented (non-
525       OO) interface, the exported name for this method is save_parameters().
526       Also if you want to initialize from a file handle, the way to do this
527       is with restore_parameters().  This will (re)initialize the default
528       CGI::Simple object from the indicated file handle.
529
530           restore_parameters($fh);
531

FILE UPLOADS

533       File uploads are easy with CGI::Simple. You use the upload() method.
534       Assuming you have the following in your HTML:
535
536           <FORM
537            METHOD="POST"
538            ACTION="http://somewhere.com/cgi-bin/script.cgi"
539            ENCTYPE="multipart/form-data">
540               <INPUT TYPE="file" NAME="upload_file1" SIZE="42">
541               <INPUT TYPE="file" NAME="upload_file2" SIZE="42">
542           </FORM>
543
544       Note that the ENCTYPE is "multipart/form-data". You must specify this
545       or the browser will default to "application/x-www-form-urlencoded"
546       which will result in no files being uploaded although on the surface
547       things will appear OK.
548
549       When the user submits this form any supplied files will be spooled onto
550       disk and saved in temporary files. These files will be deleted when
551       your script.cgi exits so if you want to keep them you will need to
552       proceed as follows.
553
554   upload() The key file upload method
555       The upload() method is quite versatile. If you call upload() without
556       any arguments it will return a list of uploaded files in list context
557       and the number of uploaded files in scalar context.
558
559           $number_of_files = $q->upload;
560           @list_of_files   = $q->upload;
561
562       Having established that you have uploaded files available you can get
563       the browser supplied filename using param() like this:
564
565           $filename1 = $q->param('upload_file1');
566
567       You can then get a filehandle to read from by calling upload() and
568       supplying this filename as an argument. Warning: do not modify the
569       value you get from param() in any way - you don't need to untaint it.
570
571           $fh = $q->upload( $filename1 );
572
573       Now to save the file you would just do something like:
574
575           $save_path = '/path/to/write/file.name';
576           open my $out, '>', $save_path or die "Oops $!\n";
577           binmode $out;
578           print $out $buffer while read( $fh, $buffer, 4096 );
579           close $out;
580
581       By utilizing a new feature of the upload method this process can be
582       simplified to:
583
584           $ok = $q->upload( $q->param('upload_file1'), '/path/to/write/file.name' );
585           if ($ok) {
586               print "Uploaded and wrote file OK!";
587           } else {
588               print $q->cgi_error();
589           }
590
591       As you can see upload will accept an optional second argument and will
592       write the file to this file path. It will return 1 for success and
593       undef if it fails. If it fails you can get the error from cgi_error
594
595       You can also use just the fieldname as an argument to upload ie:
596
597           $fh = $q->upload( 'upload_field_name' );
598
599           or
600
601           $ok = $q->upload( 'upload_field_name', '/path/to/write/file.name' );
602
603       BUT there is a catch. If you have multiple upload fields, all called
604       'upload_field_name' then you will only get the last uploaded file from
605       these fields.
606
607   upload_info() Get the details about uploaded files
608       The upload_info() method is a new method. Called without arguments it
609       returns the number of uploaded files in scalar context and the names of
610       those files in list context.
611
612           $number_of_upload_files   = $q->upload_info();
613           @filenames_of_all_uploads = $q->upload_info();
614
615       You can get the MIME type of an uploaded file like this:
616
617           $mime = $q->upload_info( $filename1, 'mime' );
618
619       If you want to know how big a file is before you copy it you can get
620       that information from uploadInfo which will return the file size in
621       bytes.
622
623           $file_size = $q->upload_info( $filename1, 'size' );
624
625       The size attribute is optional as this is the default value returned.
626
627       Note: The old CGI.pm uploadInfo() method has been deleted.
628
629   $POST_MAX and $DISABLE_UPLOADS
630       CGI.pm has a default setting that allows infinite size file uploads by
631       default. In contrast file uploads are disabled by default in
632       CGI::Simple to discourage Denial of Service attacks. You must enable
633       them before you expect file uploads to work.
634
635       When file uploads are disabled the file name and file size details will
636       still be available from param() and upload_info respectively but the
637       upload filehandle returned by upload() will be undefined - not
638       surprising as the underlying temp file will not exist either.
639
640       You can enable uploads using the '-upload' pragma. You do this by
641       specifying this in you use statement:
642
643           use CGI::Simple qw(-upload);
644
645       Alternatively you can enable uploads via the $DISABLE_UPLOADS global
646       like this:
647
648           use CGI::Simple;
649           $CGI::Simple::DISABLE_UPLOADS = 0;
650           $q = CGI::Simple->new;
651
652       If you wish to set $DISABLE_UPLOADS you must do this *after* the use
653       statement and *before* the new constructor call as shown above.
654
655       The maximum acceptable data via post is capped at 102_400kB rather than
656       infinity which is the CGI.pm default. This should be ample for most
657       tasks but you can set this to whatever you want using the $POST_MAX
658       global.
659
660           use CGI::Simple;
661           $CGI::Simple::DISABLE_UPLOADS = 0;      # enable uploads
662           $CGI::Simple::POST_MAX = 1_048_576;     # allow 1MB uploads
663           $q = CGI::Simple->new;
664
665       If you set to -1 infinite size uploads will be permitted, which is the
666       CGI.pm default.
667
668           $CGI::Simple::POST_MAX = -1;            # infinite size upload
669
670       Alternatively you can specify all the CGI.pm default values which allow
671       file uploads of infinite size in one easy step by specifying the
672       '-default' pragma in your use statement.
673
674           use CGI::Simple qw( -default ..... );
675
676   binmode() and Win32
677       If you are using CGI::Simple be sure to call binmode() on any handle
678       that you create to write the uploaded file to disk. Calling binmode()
679       will do no harm on other systems anyway.
680

MISCELANEOUS METHODS

682   escapeHTML() Escaping HTML special characters
683       In HTML the < > " and & chars have special meaning and need to be
684       escaped to &lt; &gt; &quot; and &amp; respectively.
685
686           $escaped = $q->escapeHTML( $string );
687
688           $escaped = $q->escapeHTML( $string, 'new_lines_too' );
689
690       If the optional second argument is supplied then newlines will be
691       escaped to.
692
693   unescapeHTML() Unescape HTML special characters
694       This performs the reverse of escapeHTML().
695
696           $unescaped = $q->unescapeHTML( $HTML_escaped_string );
697
698   url_decode() Decode a URL encoded string
699       This method will correctly decode a url encoded string.
700
701           $decoded = $q->url_decode( $encoded );
702
703   url_encode() URL encode a string
704       This method will correctly URL encode a string.
705
706           $encoded = $q->url_encode( $string );
707
708   parse_keywordlist() Parse a supplied keyword list
709           @keywords = $q->parse_keywordlist( $keyword_list );
710
711       This method returns a list of keywords, correctly URL escaped and split
712       out of the supplied string
713
714   put() Send output to browser
715       CGI.pm alias for print. $q->put('Hello World!') will print the usual
716
717   print() Send output to browser
718       CGI.pm alias for print. $q->print('Hello World!') will print the usual
719

HTTP COOKIES

721       CGI.pm has several methods that support cookies.
722
723       A cookie is a name=value pair much like the named parameters in a CGI
724       query string.  CGI scripts create one or more cookies and send them to
725       the browser in the HTTP header.  The browser maintains a list of
726       cookies that belong to a particular Web server, and returns them to the
727       CGI script during subsequent interactions.
728
729       In addition to the required name=value pair, each cookie has several
730       optional attributes:
731
732       1. an expiration time
733           This is a time/date string (in a special GMT format) that indicates
734           when a cookie expires.  The cookie will be saved and returned to
735           your script until this expiration date is reached if the user exits
736           the browser and restarts it.  If an expiration date isn't
737           specified, the cookie will remain active until the user quits the
738           browser.
739
740       2. a domain
741           This is a partial or complete domain name for which the cookie is
742           valid.  The browser will return the cookie to any host that matches
743           the partial domain name.  For example, if you specify a domain name
744           of ".capricorn.com", then the browser will return the cookie to Web
745           servers running on any of the machines "www.capricorn.com",
746           "www2.capricorn.com", "feckless.capricorn.com", etc.  Domain names
747           must contain at least two periods to prevent attempts to match on
748           top level domains like ".edu".  If no domain is specified, then the
749           browser will only return the cookie to servers on the host the
750           cookie originated from.
751
752       3. a path
753           If you provide a cookie path attribute, the browser will check it
754           against your script's URL before returning the cookie.  For
755           example, if you specify the path "/cgi-bin", then the cookie will
756           be returned to each of the scripts "/cgi-bin/tally.pl",
757           "/cgi-bin/order.pl", and "/cgi-bin/customer_service/complain.pl",
758           but not to the script "/cgi-private/site_admin.pl".  By default,
759           path is set to "/", which causes the cookie to be sent to any CGI
760           script on your site.
761
762       4. a "secure" flag
763           If the "secure" attribute is set, the cookie will only be sent to
764           your script if the CGI request is occurring on a secure channel,
765           such as SSL.
766
767   cookie() A simple access method to cookies
768       The interface to HTTP cookies is the cookie() method:
769
770           $cookie = $q->cookie( -name      => 'sessionID',
771                                 -value     => 'xyzzy',
772                                 -expires   => '+1h',
773                                 -path      => '/cgi-bin/database',
774                                 -domain    => '.capricorn.org',
775                                 -secure    => 1
776                                );
777           print $q->header(-cookie=>$cookie);
778
779       cookie() creates a new cookie.  Its parameters include:
780
781       -name
782           The name of the cookie (required).  This can be any string at all.
783           Although browsers limit their cookie names to non-whitespace
784           alphanumeric characters, CGI.pm removes this restriction by
785           escaping and unescaping cookies behind the scenes.
786
787       -value
788           The value of the cookie.  This can be any scalar value, array
789           reference, or even associative array reference.  For example, you
790           can store an entire associative array into a cookie this way:
791
792               $cookie=$q->cookie( -name   => 'family information',
793                                   -value  => \%childrens_ages );
794
795       -path
796           The optional partial path for which this cookie will be valid, as
797           described above.
798
799       -domain
800           The optional partial domain for which this cookie will be valid, as
801           described above.
802
803       -expires
804           The optional expiration date for this cookie.  The format is as
805           described in the section on the header() method:
806
807               "+1h"  one hour from now
808
809       -secure
810           If set to true, this cookie will only be used within a secure SSL
811           session.
812
813       The cookie created by cookie() must be incorporated into the HTTP
814       header within the string returned by the header() method:
815
816           print $q->header(-cookie=>$my_cookie);
817
818       To create multiple cookies, give header() an array reference:
819
820           $cookie1 = $q->cookie( -name  => 'riddle_name',
821                                  -value => "The Sphynx's Question"
822                                );
823           $cookie2 = $q->cookie( -name  => 'answers',
824                                  -value => \%answers
825                                );
826           print $q->header( -cookie => [ $cookie1, $cookie2 ] );
827
828       To retrieve a cookie, request it by name by calling cookie() method
829       without the -value parameter:
830
831           use CGI::Simple;
832           $q = CGI::Simple->new;
833           $riddle  = $q->cookie('riddle_name');
834           %answers = $q->cookie('answers');
835
836       Cookies created with a single scalar value, such as the "riddle_name"
837       cookie, will be returned in that form.  Cookies with array and hash
838       values can also be retrieved.
839
840       The cookie and CGI::Simple  namespaces are separate.  If you have a
841       parameter named 'answers' and a cookie named 'answers', the values
842       retrieved by param() and cookie() are independent of each other.
843       However, it's simple to turn a CGI parameter into a cookie, and vice-
844       versa:
845
846           # turn a CGI parameter into a cookie
847           $c = $q->cookie( -name=>'answers', -value=>[$q->param('answers')] );
848           # vice-versa
849           $q->param( -name=>'answers', -value=>[$q->cookie('answers')] );
850
851   raw_cookie()
852       Returns the HTTP_COOKIE variable. Cookies have a special format, and
853       this method call just returns the raw form (?cookie dough). See
854       cookie() for ways of setting and retrieving cooked cookies.
855
856       Called with no parameters, raw_cookie() returns the packed cookie
857       structure.  You can separate it into individual cookies by splitting on
858       the character sequence "; ".  Called with the name of a cookie,
859       retrieves the unescaped form of the cookie.  You can use the regular
860       cookie() method to get the names, or use the raw_fetch() method from
861       the CGI::Simmple::Cookie module.
862

CREATING HTTP HEADERS

864       Normally the first thing you will do in any CGI script is print out an
865       HTTP header.  This tells the browser what type of document to expect,
866       and gives other optional information, such as the language, expiration
867       date, and whether to cache the document.  The header can also be
868       manipulated for special purposes, such as server push and pay per view
869       pages.
870
871   header() Create simple or complex HTTP headers
872           print $q->header;
873
874                -or-
875
876           print $q->header('image/gif');
877
878                -or-
879
880           print $q->header('text/html','204 No response');
881
882                -or-
883
884           print $q->header( -type       => 'image/gif',
885                             -nph        => 1,
886                             -status     => '402 Payment required',
887                             -expires    => '+3d',
888                             -cookie     => $cookie,
889                             -charset    => 'utf-7',
890                             -attachment => 'foo.gif',
891                             -Cost       => '$2.00'
892                           );
893
894       header() returns the Content-type: header.  You can provide your own
895       MIME type if you choose, otherwise it defaults to text/html.  An
896       optional second parameter specifies the status code and a human-
897       readable message.  For example, you can specify 204, "No response" to
898       create a script that tells the browser to do nothing at all.
899
900       The last example shows the named argument style for passing arguments
901       to the CGI methods using named parameters.  Recognized parameters are
902       -type, -status, -cookie, -target, -expires, -nph, -charset and
903       -attachment.  Any other named parameters will be stripped of their
904       initial hyphens and turned into header fields, allowing you to specify
905       any HTTP header you desire.
906
907       For example, you can produce non-standard HTTP header fields by
908       providing them as named arguments:
909
910         print $q->header( -type            => 'text/html',
911                           -nph             => 1,
912                           -cost            => 'Three smackers',
913                           -annoyance_level => 'high',
914                           -complaints_to   => 'bit bucket'
915                         );
916
917       This will produce the following non-standard HTTP header:
918
919           HTTP/1.0 200 OK
920           Cost: Three smackers
921           Annoyance-level: high
922           Complaints-to: bit bucket
923           Content-type: text/html
924
925       Note that underscores are translated automatically into hyphens. This
926       feature allows you to keep up with the rapidly changing HTTP
927       "standards".
928
929       The -type is a key element that tell the browser how to display your
930       document. The default is 'text/html'. Common types are:
931
932           text/html
933           text/plain
934           image/gif
935           image/jpg
936           image/png
937           application/octet-stream
938
939       The -status code is the HTTP response code. The default is 200 OK.
940       Common status codes are:
941
942           200 OK
943           204 No Response
944           301 Moved Permanently
945           302 Found
946           303 See Other
947           307 Temporary Redirect
948           400 Bad Request
949           401 Unauthorized
950           403 Forbidden
951           404 Not Found
952           405 Not Allowed
953           408 Request Timed Out
954           500 Internal Server Error
955           503 Service Unavailable
956           504 Gateway Timed Out
957
958       The -expires parameter lets you indicate to a browser and proxy server
959       how long to cache pages for. When you specify an absolute or relative
960       expiration interval with this parameter, some browsers and proxy
961       servers will cache the script's output until the indicated expiration
962       date.  The following forms are all valid for the -expires field:
963
964           +30s                                30 seconds from now
965           +10m                                ten minutes from now
966           +1h                                 one hour from now
967           -1d                                 yesterday (i.e. "ASAP!")
968           now                                 immediately
969           +3M                                 in three months
970           +10y                                in ten years time
971           Thursday, 25-Apr-1999 00:40:33 GMT  at the indicated time & date
972
973       The -cookie parameter generates a header that tells the browser to
974       provide a "magic cookie" during all subsequent transactions with your
975       script.  Netscape cookies have a special format that includes
976       interesting attributes such as expiration time.  Use the cookie()
977       method to create and retrieve session cookies.
978
979       The -target is for frames use
980
981       The -nph parameter, if set to a true value, will issue the correct
982       headers to work with a NPH (no-parse-header) script.  This is important
983       to use with certain servers that expect all their scripts to be NPH.
984
985       The -charset parameter can be used to control the character set sent to
986       the browser.  If not provided, defaults to ISO-8859-1.  As a side
987       effect, this sets the charset() method as well.
988
989       The -attachment parameter can be used to turn the page into an
990       attachment.  Instead of displaying the page, some browsers will prompt
991       the user to save it to disk.  The value of the argument is the
992       suggested name for the saved file.  In order for this to work, you may
993       have to set the -type to 'application/octet-stream'.
994
995   no_cache() Preventing browser caching of scripts
996       Most browsers will not cache the output from CGI scripts. Every time
997       the browser reloads the page, the script is invoked anew. However some
998       browsers do cache pages. You can discourage this behavior using the
999       no_cache() function.
1000
1001           $q->no_cache(1); # turn caching off by sending appropriate headers
1002           $q->no_cache(1); # do not send cache related headers.
1003
1004           $q->no_cache(1);
1005           print header (-type=>'image/gif', -nph=>1);
1006
1007           This will produce a header like the following:
1008
1009           HTTP/1.0 200 OK
1010           Server: Apache - accept no substitutes
1011           Expires: Thu, 15 Nov 2001 03:37:50 GMT
1012           Date: Thu, 15 Nov 2001 03:37:50 GMT
1013           Pragma: no-cache
1014           Content-Type: image/gif
1015
1016       Both the Pragma: no-cache header field and an Expires header that
1017       corresponds to the current time (ie now) will be sent.
1018
1019   cache() Preventing browser caching of scripts
1020       The somewhat ill named cache() method is a legacy from CGI.pm. It
1021       operates the same as the new no_cache() method. The difference is/was
1022       that when set it results only in the Pragma: no-cache line being
1023       printed.  Expires time data is not sent.
1024
1025   redirect() Generating a redirection header
1026           print $q->redirect('http://somewhere.else/in/movie/land');
1027
1028       Sometimes you don't want to produce a document yourself, but simply
1029       redirect the browser elsewhere, perhaps choosing a URL based on the
1030       time of day or the identity of the user.
1031
1032       The redirect() function redirects the browser to a different URL.  If
1033       you use redirection like this, you should not print out a header as
1034       well.
1035
1036       One hint I can offer is that relative links may not work correctly when
1037       you generate a redirection to another document on your site.  This is
1038       due to a well-intentioned optimization that some servers use.  The
1039       solution to this is to use the full URL (including the http: part) of
1040       the document you are redirecting to.
1041
1042       You can also use named arguments:
1043
1044           print $q->redirect( -uri=>'http://somewhere.else/in/movie/land',
1045                               -nph=>1
1046                             );
1047
1048       The -nph parameter, if set to a true value, will issue the correct
1049       headers to work with a NPH (no-parse-header) script.  This is important
1050       to use with certain servers, such as Microsoft ones, which expect all
1051       their scripts to be NPH.
1052

PRAGMAS

1054       There are a number of pragmas that you can specify in your use
1055       CGI::Simple statement. Pragmas, which are always preceded by a hyphen,
1056       change the way that CGI::Simple functions in various ways. You can
1057       generally achieve exactly the same results by setting the underlying
1058       $GLOBAL_VARIABLES.
1059
1060       For example the '-upload' pargma will enable file uploads:
1061
1062           use CGI::Simple qw(-upload);
1063
1064       In CGI::Simple::Standard Pragmas, function sets , and individual
1065       functions can all be imported in the same use() line.  For example, the
1066       following use statement imports the standard set of functions and
1067       enables debugging mode (pragma -debug):
1068
1069           use CGI::Simple::Standard qw(:standard -debug);
1070
1071       The current list of pragmas is as follows:
1072
1073       -no_undef_params
1074           If a value is not given in the query string, as in the queries
1075           "name1=&name2=" or "name1&name2", by default it will be returned as
1076           an empty string.
1077
1078           If you specify the '-no_undef_params' pragma then CGI::Simple
1079           ignores parameters with no values and they will not appear in the
1080           query object.
1081
1082       -nph
1083           This makes CGI.pm produce a header appropriate for an NPH (no
1084           parsed header) script.  You may need to do other things as well to
1085           tell the server that the script is NPH.  See the discussion of NPH
1086           scripts below.
1087
1088       -newstyle_urls
1089           Separate the name=value pairs in CGI parameter query strings with
1090           semicolons rather than ampersands.  For example:
1091
1092               ?name=fred;age=24;favorite_color=3
1093
1094           Semicolon-delimited query strings are always accepted, but will not
1095           be emitted by self_url() and query_string() unless the
1096           -newstyle_urls pragma is specified.
1097
1098       -oldstyle_urls
1099           Separate the name=value pairs in CGI parameter query strings with
1100           ampersands rather than semicolons.  This is the default.
1101
1102               ?name=fred&age=24&favorite_color=3
1103
1104       -autoload
1105           This is only available for CGI::Simple::Standard and uses AUTOLOAD
1106           to load functions on demand. See the CGI::Simple::Standard docs for
1107           details.
1108
1109       -no_debug
1110           This turns off the command-line processing features. This is the
1111           default.
1112
1113       -debug1 and debug2
1114           This turns on debugging.  At debug level 1 CGI::Simple will read
1115           arguments from the command-line. At debug level 2 CGI.pm will
1116           produce the prompt "(offline mode: enter name=value pairs on
1117           standard input)" and wait for input on STDIN. If no number is
1118           specified then a debug level of 2 is used.
1119
1120           See the section on debugging for more details.
1121
1122       -default
1123           This sets the default global values for CGI.pm which will enable
1124           infinite size file uploads, and specify the '-newstyle_urls' and
1125           '-debug1' pragmas
1126
1127       -no_upload
1128           Disable uploads - the default setting
1129
1130       - upload
1131           Enable uploads - the CGI.pm default
1132
1133       -unique_header
1134           Only allows headers to be generated once per script invocation
1135
1136       -carp
1137           Carp when cgi_error() called, default is to do nothing
1138
1139       -croak
1140           Croak when cgi_error() called, default is to do nothing
1141

USING NPH SCRIPTS

1143       NPH, or "no-parsed-header", scripts bypass the server completely by
1144       sending the complete HTTP header directly to the browser.  This has
1145       slight performance benefits, but is of most use for taking advantage of
1146       HTTP extensions that are not directly supported by your server, such as
1147       server push and PICS headers.
1148
1149       Servers use a variety of conventions for designating CGI scripts as
1150       NPH.  Many Unix servers look at the beginning of the script's name for
1151       the prefix "nph-".  The Macintosh WebSTAR server and Microsoft's
1152       Internet Information Server, in contrast, try to decide whether a
1153       program is an NPH script by examining the first line of script output.
1154
1155       CGI.pm supports NPH scripts with a special NPH mode.  When in this
1156       mode, CGI.pm will output the necessary extra header information when
1157       the header() and redirect() methods are called. You can set NPH mode in
1158       any of the following ways:
1159
1160       In the use statement
1161           Simply add the "-nph" pragma to the use:
1162
1163               use CGI::Simple qw(-nph)
1164
1165       By calling the nph() method:
1166           Call nph() with a non-zero parameter at any point after using
1167           CGI.pm in your program.
1168
1169               $q->nph(1)
1170
1171       By using -nph parameters
1172           in the header() and redirect()  statements:
1173
1174               print $q->header(-nph=>1);
1175
1176       The Microsoft Internet Information Server requires NPH mode.
1177       CGI::Simple will automatically detect when the script is running under
1178       IIS and put itself into this mode.  You do not need to do this
1179       manually, although it won't hurt anything if you do.  However, note
1180       that if you have applied Service Pack 6, much of the functionality of
1181       NPH scripts, including the ability to redirect while setting a cookie,
1182       b<do not work at all> on IIS without a special patch from Microsoft.
1183       See http://support.microsoft.com/support/kb/articles/Q280/3/41.ASP:
1184       Non-Parsed Headers Stripped From CGI Applications That Have nph- Prefix
1185       in Name.
1186

SERVER PUSH

1188       CGI.pm provides four simple functions for producing multipart documents
1189       of the type needed to implement server push.  These functions were
1190       graciously provided by Ed Jordan <ed@fidalgo.net> with additions from
1191       Andrew Benham <adsb@bigfoot.com>
1192
1193       You are also advised to put the script into NPH mode and to set $| to 1
1194       to avoid buffering problems.
1195
1196       Browser support for server push is variable.
1197
1198       Here is a simple script that demonstrates server push:
1199
1200           #!/usr/local/bin/perl
1201           use CGI::Simple::Standard qw/:push -nph/;
1202           $| = 1;
1203           print multipart_init(-boundary=>'----here we go!');
1204           foreach (0 .. 4) {
1205               print multipart_start(-type=>'text/plain'),
1206               "The current time is ",scalar(localtime),"\n";
1207               if ($_ < 4) {
1208                   print multipart_end;
1209               }
1210               else {
1211                   print multipart_final;
1212               }
1213               sleep 1;
1214           }
1215
1216       This script initializes server push by calling multipart_init().  It
1217       then enters a loop in which it begins a new multipart section by
1218       calling multipart_start(), prints the current local time, and ends a
1219       multipart section with multipart_end().  It then sleeps a second, and
1220       begins again. On the final iteration, it ends the multipart section
1221       with multipart_final() rather than with multipart_end().
1222
1223   multipart_init() Initialize the multipart system
1224           multipart_init(-boundary=>$boundary);
1225
1226       Initialize the multipart system.  The -boundary argument specifies what
1227       MIME boundary string to use to separate parts of the document.  If not
1228       provided, CGI.pm chooses a reasonable boundary for you.
1229
1230   multipart_start() Start a new part of the multipart document
1231           multipart_start(-type=>$type)
1232
1233       Start a new part of the multipart document using the specified MIME
1234       type.  If not specified, text/html is assumed.
1235
1236   multipart_end() End a multipart part
1237           multipart_end()
1238
1239       End a part.  You must remember to call multipart_end() once for each
1240       multipart_start(), except at the end of the last part of the multipart
1241       document when multipart_final() should be called instead of
1242       multipart_end().
1243
1244   multipart_final()
1245           multipart_final()
1246
1247       End all parts.  You should call multipart_final() rather than
1248       multipart_end() at the end of the last part of the multipart document.
1249
1250   CGI::Push
1251       Users interested in server push applications should also have a look at
1252       the CGI::Push module.
1253

DEBUGGING

1255       If you are running the script from the command line or in the perl
1256       debugger, you can pass the script a list of keywords or parameter=value
1257       pairs on the command line or from standard input (you don't have to
1258       worry about tricking your script into reading from environment
1259       variables).  Before you do this you will need to change the debug level
1260       from the default level of 0 (no debug) to either 1 if you want to debug
1261       from @ARGV (the command line) of 2 if you want to debug from STDIN. You
1262       can do this using the debug pragma like this:
1263
1264           use CGI::Simple qw(-debug2);  # set debug to level 2 => from STDIN
1265
1266               or this:
1267
1268           $CGI::Simple::DEBUG = 1;      # set debug to level 1 => from @ARGV
1269
1270       At debug level 1 you can pass keywords and name=value pairs like this:
1271
1272           your_script.pl keyword1 keyword2 keyword3
1273
1274               or this:
1275
1276           your_script.pl keyword1+keyword2+keyword3
1277
1278               or this:
1279
1280           your_script.pl name1=value1 name2=value2
1281
1282               or this:
1283
1284           your_script.pl name1=value1&name2=value2
1285
1286       At debug level 2 you can feed newline-delimited name=value pairs to the
1287       script on standard input. You will be presented with the following
1288       prompt:
1289
1290           (offline mode: enter name=value pairs on standard input)
1291
1292       You end the input with your system dependent end of file character.
1293       You should try ^Z ^X ^D and ^C if all else fails. The ^ means hold down
1294       the [Ctrl] button while you press the other key.
1295
1296       When debugging, you can use quotes and backslashes to escape characters
1297       in the familiar shell manner, letting you place spaces and other funny
1298       characters in your parameter=value pairs:
1299
1300           your_script.pl "name1='I am a long value'" "name2=two\ words"
1301
1302   Dump() Dumping the current object details
1303       The Dump() method produces a string consisting of all the query's
1304       object attributes formatted nicely as a nested list.  This dump
1305       includes the name/value pairs and a number of other details. This is
1306       useful for debugging purposes:
1307
1308           print $q->Dump
1309
1310       The actual result of this is HTML escaped formatted text wrapped in
1311       <pre> tags so if you send it straight to the browser it produces
1312       something that looks like:
1313
1314           $VAR1 = bless( {
1315                '.parameters' => [
1316                                   'name',
1317                                   'color'
1318                                 ],
1319                '.globals' => {
1320                                'FATAL' => -1,
1321                                'DEBUG' => 0,
1322                                'NO_NULL' => 1,
1323                                'POST_MAX' => 102400,
1324                                'USE_CGI_PM_DEFAULTS' => 0,
1325                                'HEADERS_ONCE' => 0,
1326                                'NPH' => 0,
1327                                'DISABLE_UPLOADS' => 1,
1328                                'NO_UNDEF_PARAMS' => 0,
1329                                'USE_PARAM_SEMICOLONS' => 0
1330                              },
1331                '.fieldnames' => {
1332                                   'color' => '1',
1333                                   'name' => '1'
1334                                 },
1335                '.mod_perl' => '',
1336                'color' => [
1337                             'red',
1338                             'green',
1339                             'blue'
1340                           ],
1341                'name' => [
1342                            'JaPh,'
1343                          ]
1344               }, 'CGI::Simple' );
1345
1346       You may recognize this as valid Perl syntax (which it is) and/or the
1347       output from Data::Dumper (also true). This is the actual guts of how
1348       the information is stored in the query object. All the internal params
1349       start with a . char
1350
1351       Alternatively you can dump your object and the current environment
1352       using:
1353
1354           print $q->Dump(\%ENV);
1355
1356   PrintEnv() Dumping the environment
1357       You can get a similar browser friendly dump of the current %ENV hash
1358       using:
1359
1360           print $q->PrintEnv;
1361
1362       This will produce something like (in the browser):
1363
1364           $VAR1 = {
1365                 'QUERY_STRING' => 'name=JaPh%2C&color=red&color=green&color=blue',
1366                 'CONTENT_TYPE' => 'application/x-www-form-urlencoded',
1367                 'REGRESSION_TEST' => 'simple.t.pl',
1368                 'VIM' => 'C:\\WINDOWS\\Desktop\\vim',
1369                 'HTTP_REFERER' => 'xxx.sex.com',
1370                 'HTTP_USER_AGENT' => 'LWP',
1371                 'HTTP_ACCEPT' => 'text/html;q=1, image/gif;q=0.42, */*;q=0.001',
1372                 'REMOTE_HOST' => 'localhost',
1373                 'HTTP_HOST' => 'the.restaurant.at.the.end.of.the.universe',
1374                 'GATEWAY_INTERFACE' => 'bleeding edge',
1375                 'REMOTE_IDENT' => 'None of your damn business',
1376                 'SCRIPT_NAME' => '/cgi-bin/foo.cgi',
1377                 'SERVER_NAME' => 'nowhere.com',
1378                 'HTTP_COOKIE' => '',
1379                 'CONTENT_LENGTH' => '42',
1380                 'HTTPS_A' => 'A',
1381                 'HTTP_FROM' => 'spammer@nowhere.com',
1382                 'HTTPS_B' => 'B',
1383                 'SERVER_PROTOCOL' => 'HTTP/1.0',
1384                 'PATH_TRANSLATED' => '/usr/local/somewhere/else',
1385                 'SERVER_SOFTWARE' => 'Apache - accept no substitutes',
1386                 'PATH_INFO' => '/somewhere/else',
1387                 'REMOTE_USER' => 'Just another Perl hacker,',
1388                 'REMOTE_ADDR' => '127.0.0.1',
1389                 'HTTPS' => 'ON',
1390                 'DOCUMENT_ROOT' => '/vs/www/foo',
1391                 'REQUEST_METHOD' => 'GET',
1392                 'REDIRECT_QUERY_STRING' => '',
1393                 'AUTH_TYPE' => 'PGP MD5 DES rot13',
1394                 'COOKIE' => 'foo=a%20phrase; bar=yes%2C%20a%20phrase&;I%20say;',
1395                 'SERVER_PORT' => '8080'
1396               };
1397
1398   cgi_error() Retrieving CGI::Simple error messages
1399       Errors can occur while processing user input, particularly when
1400       processing uploaded files.  When these errors occur, CGI::Simple will
1401       stop processing and return an empty parameter list.  You can test for
1402       the existence and nature of errors using the cgi_error() function.  The
1403       error messages are formatted as HTTP status codes. You can either
1404       incorporate the error text into an HTML page, or use it as the value of
1405       the HTTP status:
1406
1407           my $error = $q->cgi_error;
1408           if ($error) {
1409               print $q->header(-status=>$error);
1410               print "<H2>$error</H2>;
1411             exit;
1412           }
1413

ACCESSOR METHODS

1415   version() Get the CGI::Simple version info
1416           $version = $q->version();
1417
1418       The version() method returns the value of $VERSION
1419
1420   nph() Enable/disable NPH (Non Parsed Header) mode
1421           $q->nph(1);  # enable NPH mode
1422           $q->nph(0);  # disable NPH mode
1423
1424       The nph() method enables and disables NPH headers. See the NPH section.
1425
1426   all_parameters() Get the names/values of all parameters
1427           @all_parameters = $q->all_parameters();
1428
1429       The all_parameters() method is an alias for param()
1430
1431   charset() Get/set the current character set.
1432           $charset = $q->charset(); # get current charset
1433           $q->charset('utf-42');    # set the charset
1434
1435       The charset() method gets the current charset value if no argument is
1436       supplied or sets it if an argument is supplied.
1437
1438   crlf() Get the system specific line ending sequence
1439           $crlf = $q->crlf();
1440
1441       The crlf() method returns the system specific line ending sequence.
1442
1443   globals() Get/set the value of the remaining global variables
1444           $globals = $q->globals('FATAL');     # get the current value of $FATAL
1445           $globals = $q->globals('FATAL', 1 ); # set croak mode on cgi_error()
1446
1447       The globals() method gets/sets the values of the global variables after
1448       the script has been invoked. For globals like $POST_MAX and
1449       $DISABLE_UPLOADS this makes no difference as they must be set prior to
1450       calling the new constructor but there might be reason the change the
1451       value of others.
1452
1453   auth_type() Get the current authorization/verification method
1454           $auth_type = $q->auth_type();
1455
1456       The auth_type() method returns the value of $ENV{'AUTH_TYPE'} which
1457       should contain the authorization/verification method in use for this
1458       script, if any.
1459
1460   content_length() Get the content length submitted in a POST
1461           $content_length = $q->content_length();
1462
1463       The content_length() method returns the value of $ENV{'AUTH_TYPE'}
1464
1465   content_type() Get the content_type of data submitted in a POST
1466           $content_type = $q->content_type();
1467
1468       The content_type() method returns the content_type of data submitted in
1469       a POST, generally 'multipart/form-data' or
1470       'application/x-www-form-urlencoded' as supplied in $ENV{'CONTENT_TYPE'}
1471
1472   document_root() Get the document root
1473           $document_root = $q->document_root();
1474
1475       The document_root() method returns the value of $ENV{'DOCUMENT_ROOT'}
1476
1477   gateway_interface() Get the gateway interface
1478           $gateway_interface = $q->gateway_interface();
1479
1480       The gateway_interface() method returns the value of
1481       $ENV{'GATEWAY_INTERFACE'}
1482
1483   path_translated() Get the value of path translated
1484           $path_translated = $q->path_translated();
1485
1486       The path_translated() method returns the value of
1487       $ENV{'PATH_TRANSLATED'}
1488
1489   referer() Spy on your users
1490           $referer = $q->referer();
1491
1492       The referer() method returns the value of $ENV{'REFERER'} This will
1493       return the URL of the page the browser was viewing prior to fetching
1494       your script.  Not available for all browsers.
1495
1496   remote_addr() Get the remote address
1497           $remote_addr = $q->remote_addr();
1498
1499       The remote_addr() method returns the value of $ENV{'REMOTE_ADDR'} or
1500       127.0.0.1 (localhost) if this is not defined.
1501
1502   remote_host() Get a value for remote host
1503           $remote_host = $q->remote_host();
1504
1505       The remote_host() method returns the value of $ENV{'REMOTE_HOST'} if it
1506       is defined. If this is not defined it returns $ENV{'REMOTE_ADDR'} If
1507       this is not defined it returns 'localhost'
1508
1509   remote_ident() Get the remote identity
1510           $remote_ident = $q->remote_ident();
1511
1512       The remote_ident() method returns the value of $ENV{'REMOTE_IDENT'}
1513
1514   remote_user() Get the remote user
1515           $remote_user = $q->remote_user();
1516
1517       The remote_user() method returns the authorization/verification name
1518       used for user verification, if this script is protected. The value
1519       comes from $ENV{'REMOTE_USER'}
1520
1521   request_method() Get the request method
1522           $request_method = $q->request_method();
1523
1524       The request_method() method returns the method used to access your
1525       script, usually one of 'POST', 'GET' or 'HEAD' as supplied by
1526       $ENV{'REQUEST_METHOD'}
1527
1528   script_name() Get the script name
1529           $script_name = $q->script_name();
1530
1531       The script_name() method returns the value of $ENV{'SCRIPT_NAME'} if it
1532       is defined. Otherwise it returns Perl's script name from $0. Failing
1533       this it returns a null string ''
1534
1535   server_name() Get the server name
1536           $server_name = $q->server_name();
1537
1538       The server_name() method returns the value of $ENV{'SERVER_NAME'} if
1539       defined or 'localhost' otherwise
1540
1541   server_port() Get the port the server is listening on
1542           $server_port = $q->server_port();
1543
1544       The server_port() method returns the value $ENV{'SERVER_PORT'} if
1545       defined or 80 if not.
1546
1547   server_protocol() Get the current server protocol
1548           $server_protocol = $q->server_protocol();
1549
1550       The server_protocol() method returns the value of
1551       $ENV{'SERVER_PROTOCOL'} if defined or 'HTTP/1.0' otherwise
1552
1553   server_software() Get the server software
1554           $server_software = $q->server_software();
1555
1556       The server_software() method returns the value $ENV{'SERVER_SOFTWARE'}
1557       or 'cmdline' If the server software is IIS it formats your hard drive,
1558       installs Linux, FTPs to www.apache.org, installs Apache, and then
1559       restores your system from tape. Well maybe not, but it's a nice
1560       thought.
1561
1562   user_name() Get a value for the user name.
1563           $user_name = $q->user_name();
1564
1565       Attempt to obtain the remote user's name, using a variety of different
1566       techniques.  This only works with older browsers such as Mosaic.  Newer
1567       browsers do not report the user name for privacy reasons!
1568
1569       Technically the user_name() method returns the value of
1570       $ENV{'HTTP_FROM'} or failing that $ENV{'REMOTE_IDENT'} or as a last
1571       choice $ENV{'REMOTE_USER'}
1572
1573   user_agent() Get the users browser type
1574           $ua = $q->user_agent();          # return the user agent
1575           $ok = $q->user_agent('mozilla'); # return true if user agent 'mozilla'
1576
1577       The user_agent() method returns the value of $ENV{'HTTP_USER_AGENT'}
1578       when called without an argument or true or false if the
1579       $ENV{'HTTP_USER_AGENT'} matches the passed argument. The matching is
1580       case insensitive and partial.
1581
1582   virtual_host() Get the virtual host
1583           $virtual_host = $q->virtual_host();
1584
1585       The virtual_host() method returns the value of  $ENV{'HTTP_HOST'} if
1586       defined or $ENV{'SERVER_NAME'} as a default. Port numbers are removed.
1587
1588   path_info() Get any extra path info set to the script
1589           $path_info = $q->path_info();
1590
1591       The path_info() method returns additional path information from the
1592       script URL. E.G. fetching /cgi-bin/your_script/additional/stuff will
1593       result in $q->path_info() returning "/additional/stuff".
1594
1595       NOTE: The Microsoft Internet Information Server is broken with respect
1596       to additional path information.  If you use the Perl DLL library, the
1597       IIS server will attempt to execute the additional path information as a
1598       Perl script.  If you use the ordinary file associations mapping, the
1599       path information will be present in the environment, but incorrect.
1600       The best thing to do is to avoid using additional path information in
1601       CGI scripts destined for use with IIS.
1602
1603   Accept() Get the browser MIME types
1604           $Accept = $q->Accept();
1605
1606       The Accept() method returns a list of MIME types that the remote
1607       browser accepts. If you give this method a single argument
1608       corresponding to a MIME type, as in $q->Accept('text/html'), it will
1609       return a floating point value corresponding to the browser's preference
1610       for this type from 0.0 (don't want) to 1.0.  Glob types (e.g. text/*)
1611       in the browser's accept list are handled correctly.
1612
1613   accept() Alias for Accept()
1614           $accept = $q->accept();
1615
1616       The accept() Method is an alias for Accept()
1617
1618   http() Get a range of HTTP related information
1619           $http = $q->http();
1620
1621       Called with no arguments the http() method returns the list of HTTP or
1622       HTTPS environment variables, including such things as HTTP_USER_AGENT,
1623       HTTP_ACCEPT_LANGUAGE, and HTTP_ACCEPT_CHARSET, corresponding to the
1624       like-named HTTP header fields in the request. Called with the name of
1625       an HTTP header field, returns its value.  Capitalization and the use of
1626       hyphens versus underscores are not significant.
1627
1628       For example, all three of these examples are equivalent:
1629
1630          $requested_language = $q->http('Accept-language');
1631          $requested_language = $q->http('Accept_language');
1632          $requested_language = $q->http('HTTP_ACCEPT_LANGUAGE');
1633
1634   https() Get a range of HTTPS related information
1635           $https = $q->https();
1636
1637       The https() method is similar to the http() method except that when
1638       called without an argument it returns the value of $ENV{'HTTPS'} which
1639       will be true if a HTTPS connection is in use and false otherwise.
1640
1641   protocol() Get the current protocol
1642           $protocol = $q->protocol();
1643
1644       The protocol() method returns 'https' if a HTTPS connection is in use
1645       or the server_protocol() minus version numbers ('http') otherwise.
1646
1647   url() Return the script's URL in several formats
1648           $full_url      = $q->url();
1649           $full_url      = $q->url(-full=>1);
1650           $relative_url  = $q->url(-relative=>1);
1651           $absolute_url  = $q->url(-absolute=>1);
1652           $url_with_path = $q->url(-path_info=>1);
1653           $url_with_path_and_query = $q->url(-path_info=>1,-query=>1);
1654           $netloc        = $q->url(-base => 1);
1655
1656       url() returns the script's URL in a variety of formats.  Called without
1657       any arguments, it returns the full form of the URL, including host name
1658       and port number
1659
1660           http://your.host.com/path/to/script.cgi
1661
1662       You can modify this format with the following named arguments:
1663
1664       -absolute
1665           If true, produce an absolute URL, e.g.
1666
1667               /path/to/script.cgi
1668
1669       -relative
1670           Produce a relative URL.  This is useful if you want to reinvoke
1671           your script with different parameters. For example:
1672
1673               script.cgi
1674
1675       -full
1676           Produce the full URL, exactly as if called without any arguments.
1677           This overrides the -relative and -absolute arguments.
1678
1679       -path (-path_info)
1680           Append the additional path information to the URL.  This can be
1681           combined with -full, -absolute or -relative.  -path_info is
1682           provided as a synonym.
1683
1684       -query (-query_string)
1685           Append the query string to the URL.  This can be combined with
1686           -full, -absolute or -relative.  -query_string is provided as a
1687           synonym.
1688
1689       -base
1690           Generate just the protocol and net location, as in
1691           http://www.foo.com:8000
1692
1693   self_url() Get the scripts complete URL
1694           $self_url = $q->self_url();
1695
1696       The self_url() method returns the value of:
1697
1698          $self->url( '-path_info'=>1, '-query'=>1, '-full'=>1 );
1699
1700   state() Alias for self_url()
1701           $state = $q->state();
1702
1703       The state() method is an alias for self_url()
1704

COMPATIBILITY WITH cgi-lib.pl 2.18

1706       To make it easier to port existing programs that use cgi-lib.pl all the
1707       subs within cgi-lib.pl are available in CGI::Simple.  Using the
1708       functional interface of CGI::Simple::Standard porting is as easy as:
1709
1710           OLD VERSION
1711               require "cgi-lib.pl";
1712               &ReadParse;
1713               print "The value of the antique is $in{'antique'}.\n";
1714
1715           NEW VERSION
1716               use CGI::Simple::Standard qw(:cgi-lib);
1717               &ReadParse;
1718               print "The value of the antique is $in{'antique'}.\n";
1719
1720       CGI:Simple's ReadParse() routine creates a variable named %in, which
1721       can be accessed to obtain the query variables.  Like ReadParse, you can
1722       also provide your own variable via a glob. Infrequently used features
1723       of ReadParse(), such as the creation of @in and $in variables, are not
1724       supported.
1725
1726       You can also use the OO interface of CGI::Simple and call ReadParse()
1727       and other cgi-lib.pl functions like this:
1728
1729           &CGI::Simple::ReadParse;       # get hash values in %in
1730
1731           my $q = CGI::Simple->new;
1732           $q->ReadParse();                # same thing
1733
1734           CGI::Simple::ReadParse(*field); # get hash values in %field function style
1735
1736           my $q = CGI::Simple->new;
1737           $q->ReadParse(*field);          # same thing
1738
1739       Once you use ReadParse() under the functional interface , you can
1740       retrieve the query object itself this way if needed:
1741
1742           $q = $in{'CGI'};
1743
1744       Either way it allows you to start using the more interesting features
1745       of CGI.pm without rewriting your old scripts from scratch.
1746
1747       Unlike CGI.pm all the cgi-lib.pl functions from Version 2.18 are
1748       supported:
1749
1750           ReadParse()
1751           SplitParam()
1752           MethGet()
1753           MethPost()
1754           MyBaseUrl()
1755           MyURL()
1756           MyFullUrl()
1757           PrintHeader()
1758           HtmlTop()
1759           HtmlBot()
1760           PrintVariables()
1761           PrintEnv()
1762           CgiDie()
1763           CgiError()
1764

COMPATIBILITY WITH CGI.pm

1766       I has long been suggested that the CGI and HTML parts of CGI.pm should
1767       be split into separate modules (even the author suggests this!),
1768       CGI::Simple represents the realization of this and contains the
1769       complete CGI side of CGI.pm. Code-wise it weighs in at a little under
1770       30% of the size of CGI.pm at a little under 1000 lines.
1771
1772       A great deal of care has been taken to ensure that the interface
1773       remains unchanged although a few tweaks have been made. The test suite
1774       is extensive and includes all the CGI.pm test scripts as well as a
1775       series of new test scripts. You may like to have a look at /t/concur.t
1776       which makes 160 tests of CGI::Simple and CGI in parallel and compares
1777       the results to ensure they are identical. This is the case as of CGI.pm
1778       2.78.
1779
1780       You can't make an omelet without breaking eggs. A large number of
1781       methods and global variables have been deleted as detailed below. Some
1782       pragmas are also gone. In the tarball there is a script /misc/check.pl
1783       that will check if a script seems to be using any of these now non
1784       existent methods, globals or pragmas. You call it like this:
1785
1786           perl check.pl <files>
1787
1788       If it finds any likely candidates it will print a line with the line
1789       number, problem method/global and the complete line. For example here
1790       is some output from running the script on CGI.pm:
1791
1792           ...
1793           3162: Problem:'$CGI::OS'   local($CRLF) = "\015\012" if $CGI::OS eq 'VMS';
1794           3165: Problem:'fillBuffer' $self->fillBuffer($FILLUNIT);
1795           ....
1796

DIFFERENCES FROM CGI.pm

1798       CGI::Simple is strict and warnings compliant.
1799
1800       There are 4 modules in this distribution:
1801
1802           CGI/Simple.pm           supplies all the core code.
1803           CGI/Simple/Cookie.pm    supplies the cookie handling functions.
1804           CGI/Simple/Util.pm      supplies a variety of utility functions
1805           CGI/Simple/Standard.pm  supplies a functional interface for Simple.pm
1806
1807       Simple.pm is the core module that provide all the essential
1808       functionality.  Cookie.pm is a shortened rehash of the CGI.pm module of
1809       the same name which supplies the required cookie functionality. Util.pm
1810       has been recoded to use an internal object for data storage and
1811       supplies rarely needed non core functions and/or functions needed for
1812       the HTML side of things. Standard.pm is a wrapper module that supplies
1813       a complete functional interface to the OO back end supplied by
1814       CGI::Simple.
1815
1816       Although a serious attempt has been made to keep the interface
1817       identical, some minor changes and tweaks have been made. They will
1818       likely be insignificant to most users but here are the gory details.
1819
1820   Globals Variables
1821       The list of global variables has been pruned by 75%. Here is the
1822       complete list of the global variables used:
1823
1824           $VERSION = "0.01";
1825           # set this to 1 to use CGI.pm default global settings
1826           $USE_CGI_PM_DEFAULTS = 0 unless defined $USE_CGI_PM_DEFAULTS;
1827           # see if user wants old  CGI.pm defaults
1828           do{ _use_cgi_pm_global_settings(); return } if $USE_CGI_PM_DEFAULTS;
1829           # no file uploads by default, set to 0 to enable uploads
1830           $DISABLE_UPLOADS = 1 unless defined $DISABLE_UPLOADS;
1831           # use a post max of 100K, set to -1 for no limits
1832           $POST_MAX = 102_400 unless defined $POST_MAX;
1833           # do not include undefined params parsed from query string
1834           $NO_UNDEF_PARAMS = 0 unless defined $NO_UNDEF_PARAMS;
1835           # separate the name=value pairs with ; rather than &
1836           $USE_PARAM_SEMICOLONS = 0 unless defined $USE_PARAM_SEMICOLONS;
1837           # only print headers once
1838           $HEADERS_ONCE = 0 unless defined $HEADERS_ONCE;
1839           # Set this to 1 to enable NPH scripts
1840           $NPH = 0 unless defined $NPH;
1841           # 0 => no debug, 1 => from @ARGV,  2 => from STDIN
1842           $DEBUG = 0 unless defined $DEBUG;
1843           # filter out null bytes in param - value pairs
1844           $NO_NULL  = 1 unless defined $NO_NULL;
1845           # set behavior when cgi_err() called -1 => silent, 0 => carp, 1 => croak
1846           $FATAL = -1 unless defined $FATAL;
1847
1848       Four of the default values of the old CGI.pm variables have been
1849       changed.  Unlike CGI.pm which by default allows unlimited POST data and
1850       file uploads by default CGI::Simple limits POST data size to 100kB and
1851       denies file uploads by default. $USE_PARAM_SEMICOLONS is set to 0 by
1852       default so we use (old style) & rather than ; as the pair separator for
1853       query strings. Debugging is disabled by default.
1854
1855       There are three new global variables. If $NO_NULL is true (the default)
1856       then CGI::Simple will strip null bytes out of names, values and
1857       keywords. Null bytes can do interesting things to C based code like
1858       Perl. Uploaded files are not touched. $FATAL controls the behavior when
1859       cgi_error() is called.  The default value of -1 makes errors silent.
1860       $USE_CGI_PM_DEFAULTS reverts the defaults to the CGI.pm standard values
1861       ie unlimited file uploads via POST for DNS attacks. You can also get
1862       the defaults back by using the '-default' pragma in the use:
1863
1864           use CGI::Simple qw(-default);
1865           use CGI::Simple::Standard qw(-default);
1866
1867       The values of the global variables are stored in the CGI::Simple object
1868       and can be referenced and changed using the globals() method like this:
1869
1870           my $value = $q->globals( 'VARNAME' );      # get
1871           $q->globals( 'VARNAME', 'some value' );    # set
1872
1873       As with many CGI.pm methods if you pass the optional value that will be
1874       set.
1875
1876       The $CGI::Simple::VARNAME = 'N' syntax is only useful prior to calling
1877       the new() constructor. After that all reference is to the values stored
1878       in the CGI::Simple object so you must change these using the globals()
1879       method.
1880
1881       $DISABLE_UPLOADS and $POST_MAX *must* be set prior to calling the
1882       constructor if you want the changes to have any effect as they control
1883       behavior during initialization. This is the same a CGI.pm although some
1884       people seem to miss this rather important point and set these after
1885       calling the constructor which does nothing.
1886
1887       The following globals are no longer relevant and have all been deleted:
1888
1889           $AUTOLOADED_ROUTINES
1890           $AUTOLOAD_DEBUG
1891           $BEEN_THERE
1892           $CRLF
1893           $DEFAULT_DTD
1894           $EBCDIC
1895           $FH
1896           $FILLUNIT
1897           $IIS
1898           $IN
1899           $INITIAL_FILLUNIT
1900           $JSCRIPT
1901           $MAC
1902           $MAXTRIES
1903           $MOD_PERL
1904           $NOSTICKY
1905           $OS
1906           $PERLEX
1907           $PRIVATE_TEMPFILES
1908           $Q
1909           $QUERY_CHARSET
1910           $QUERY_PARAM
1911           $SCRATCH
1912           $SL
1913           $SPIN_LOOP_MAX
1914           $TIMEOUT
1915           $TMPDIRECTORY
1916           $XHTML
1917           %EXPORT
1918           %EXPORT_OK
1919           %EXPORT_TAGS
1920           %OVERLOAD
1921           %QUERY_FIELDNAMES
1922           %SUBS
1923           @QUERY_PARAM
1924           @TEMP
1925
1926       Notes: CGI::Simple uses IO::File->new_tmpfile to get tempfile
1927       filehandles.  These are private by default so $PRIVATE_TEMPFILES is no
1928       longer required nor is $TMPDIRECTORY. The value that were stored in
1929       $OS, $CRLF, $QUERY_CHARSET and $EBCDIC are now stored in the
1930       CGI::Simple::Util object where they find most of their use. The
1931       $MOD_PERL and $PERLEX values are now stored in our CGI::Simple object.
1932       $IIS was only used once in path_info().  $SL the system specific / \ :
1933       path delimiter is not required as we let IO::File handle our tempfile
1934       requirements. The rest of the globals are HTML related, export related,
1935       hand rolled autoload related or serve obscure purposes in CGI.pm
1936
1937   Changes to pragmas
1938       There are some new pragmas available. See the pragmas section for
1939       details.  The following CGI.pm pragmas are not available:
1940
1941           -any
1942           -compile
1943           -nosticky
1944           -no_xhtml
1945           -private_tempfiles
1946
1947   Filehandles
1948       Unlike CGI.pm which tries to accept all filehandle like objects only
1949       \*FH and $fh are accepted by CGI::Simple as file accessors for new()
1950       and save().  IO::File objects work fine.
1951
1952   Hash interface
1953           %hash = $q->Vars();     # pack values with "\0";
1954           %hash = $q->Vars(",");  # comma separate values
1955
1956       You may optionally pass Vars() a string that will be used to separate
1957       multiple values when they are packed into the single hash value. If no
1958       value is supplied the default "\0" (null byte) will be used. Null bytes
1959       are dangerous things for C based code (ie Perl).
1960
1961   cgi-lib.pl
1962       All the cgi-lib.pl 2.18 routines are supported. Unlike CGI.pm all the
1963       subroutines from cgi-lib.pl are included. They have been GOLFED down to
1964       25 lines but they all work pretty much the same as the originals.
1965

CGI::Simple COMPLETE METHOD LIST

1967       Here is a complete list of all the CGI::Simple methods.
1968
1969   Guts (hands off, except of course for new)
1970           _initialize_globals
1971           _use_cgi_pm_global_settings
1972           _store_globals
1973           import
1974           _reset_globals
1975           new
1976           _initialize
1977           _read_parse
1978           _parse_params
1979           _add_param
1980           _parse_keywordlist
1981           _parse_multipart
1982           _save_tmpfile
1983           _read_data
1984
1985   Core Methods
1986           param
1987           add_param
1988           param_fetch
1989           url_param
1990           keywords
1991           Vars
1992           append
1993           delete
1994           Delete
1995           delete_all
1996           Delete_all
1997           upload
1998           upload_info
1999           query_string
2000           parse_query_string
2001           parse_keywordlist
2002
2003   Save and Restore from File Methods
2004           _init_from_file
2005           save
2006           save_parameters
2007
2008   Miscellaneous Methods
2009           url_decode
2010           url_encode
2011           escapeHTML
2012           unescapeHTML
2013           put
2014           print
2015
2016   Cookie Methods
2017           cookie
2018           raw_cookie
2019
2020   Header Methods
2021           header
2022           cache
2023           no_cache
2024           redirect
2025
2026   Server Push Methods
2027           multipart_init
2028           multipart_start
2029           multipart_end
2030           multipart_final
2031
2032   Debugging Methods
2033           read_from_cmdline
2034           Dump
2035           as_string
2036           cgi_error
2037
2038   cgi-lib.pl Compatibility Routines - all 2.18 functions available
2039           _shift_if_ref
2040           ReadParse
2041           SplitParam
2042           MethGet
2043           MethPost
2044           MyBaseUrl
2045           MyURL
2046           MyFullUrl
2047           PrintHeader
2048           HtmlTop
2049           HtmlBot
2050           PrintVariables
2051           PrintEnv
2052           CgiDie
2053           CgiError
2054
2055   Accessor Methods
2056           version
2057           nph
2058           all_parameters
2059           charset
2060           crlf                # new, returns OS specific CRLF sequence
2061           globals             # get/set global variables
2062           auth_type
2063           content_length
2064           content_type
2065           document_root
2066           gateway_interface
2067           path_translated
2068           referer
2069           remote_addr
2070           remote_host
2071           remote_ident
2072           remote_user
2073           request_method
2074           script_name
2075           server_name
2076           server_port
2077           server_protocol
2078           server_software
2079           user_name
2080           user_agent
2081           virtual_host
2082           path_info
2083           Accept
2084           accept
2085           http
2086           https
2087           protocol
2088           url
2089           self_url
2090           state
2091

NEW METHODS IN CGI::Simple

2093       There are a few new methods in CGI::Simple as listed below. The
2094       highlights are the parse_query_string() method to add the QUERY_STRING
2095       data to your object if the method was POST. The no_cache() method adds
2096       an expires now directive and the Pragma: no-cache directive to the
2097       header to encourage some browsers to do the right thing. PrintEnv()
2098       from the cgi-lib.pl routines will dump an HTML friendly list of the
2099       %ENV and makes a handy addition to Dump() for use in debugging. The
2100       upload method now accepts a filepath as an optional second argument as
2101       shown in the synopsis. If this is supplied the uploaded file will be
2102       written to there automagically.
2103
2104   Internal Routines
2105           _initialize_globals()
2106           _use_cgi_pm_global_settings()
2107           _store_globals()
2108           _initialize()
2109           _init_from_file()
2110           _read_parse()
2111           _parse_params()
2112           _add_param()
2113           _parse_keywordlist()
2114           _parse_multipart()
2115           _save_tmpfile()
2116           _read_data()
2117
2118   New Public Methods
2119           add_param()             # adds a param/value(s) pair +/- overwrite
2120           upload_info()           # uploaded files MIME type and size
2121           url_decode()            # decode s url encoded string
2122           url_encode()            # url encode a string
2123           parse_query_string()    # add QUERY_STRING data to $q object if 'POST'
2124           no_cache()              # add both the Pragma: no-cache
2125                                   # and Expires/Date => 'now' to header
2126
2127   cgi-lib.pl methods added for completeness
2128           _shift_if_ref()         # internal hack reminiscent of self_or_default :-)
2129           MyBaseUrl()
2130           MyURL()
2131           MyFullUrl()
2132           PrintVariables()
2133           PrintEnv()
2134           CgiDie()
2135           CgiError()
2136
2137   New Accessors
2138           crlf()                  # returns CRLF sequence
2139           globals()               # global vars now stored in $q object - get/set
2140           content_length()        # returns $ENV{'CONTENT_LENGTH'}
2141           document_root()         # returns $ENV{'DOCUMENT_ROOT'}
2142           gateway_interface()     # returns $ENV{'GATEWAY_INTERFACE'}
2143

METHODS IN CGI.pm NOT IN CGI::Simple

2145       Here is a complete list of what is not included in CGI::Simple.
2146       Basically all the HTML related stuff plus large redundant chunks of the
2147       guts. The check.pl script in the /misc dir will check to see if a
2148       script is using any of these.
2149
2150   Guts - rearranged, recoded, renamed and hacked out of existence
2151           initialize_globals()
2152           compile()
2153           expand_tags()
2154           self_or_default()
2155           self_or_CGI()
2156           init()
2157           to_filehandle()
2158           save_request()
2159           parse_params()
2160           add_parameter()
2161           binmode()
2162           _make_tag_func()
2163           AUTOLOAD()
2164           _compile()
2165           _setup_symbols()
2166           new_MultipartBuffer()
2167           read_from_client()
2168           import_names()     # I dislike this and left it out, so shoot me.
2169
2170   HTML Related
2171           autoEscape()
2172           URL_ENCODED()
2173           MULTIPART()
2174           SERVER_PUSH()
2175           start_html()
2176           _style()
2177           _script()
2178           end_html()
2179           isindex()
2180           startform()
2181           start_form()
2182           end_multipart_form()
2183           start_multipart_form()
2184           endform()
2185           end_form()
2186           _textfield()
2187           textfield()
2188           filefield()
2189           password_field()
2190           textarea()
2191           button()
2192           submit()
2193           reset()
2194           defaults()
2195           comment()
2196           checkbox()
2197           checkbox_group()
2198           _tableize()
2199           radio_group()
2200           popup_menu()
2201           scrolling_list()
2202           hidden()
2203           image_button()
2204           nosticky()
2205           default_dtd()
2206
2207   Upload Related
2208       CGI::Simple uses anonymous tempfiles supplied by IO::File to spool
2209       uploaded files to.
2210
2211           private_tempfiles() # automatic in CGI::Simple
2212           tmpFileName()       # all upload files are anonymous
2213           uploadInfo()        # relied on FH access, replaced with upload_info()
2214
2215   Really Private Subs (marked as so)
2216           previous_or_default()
2217           register_parameter()
2218           get_fields()
2219           _set_values_and_labels()
2220           _compile_all()
2221           asString()
2222           compare()
2223
2224   Internal Multipart Parsing Routines
2225           read_multipart()
2226           readHeader()
2227           readBody()
2228           read()
2229           fillBuffer()
2230           eof()
2231

EXPORT

2233       Nothing.
2234

AUTHOR INFORMATION

2236       Originally copyright 2001 Dr James Freeman <jfreeman@tassie.net.au>
2237       This release by Andy Armstrong <andy@hexten.net>
2238
2239       This package is free software and is provided "as is" without express
2240       or implied warranty. It may be used, redistributed and/or modified
2241       under the terms of the Perl Artistic License (see
2242       http://www.perl.com/perl/misc/Artistic.html)
2243
2244       Address bug reports and comments to: andy@hexten.net.  When sending bug
2245       reports, please provide the version of CGI::Simple, the version of
2246       Perl, the name and version of your Web server, and the name and version
2247       of the operating system you are using.  If the problem is even remotely
2248       browser dependent, please provide information about the affected
2249       browsers as well.
2250
2251       Address bug reports and comments to: andy@hexten.net
2252

CREDITS

2254       Lincoln D. Stein (lstein@cshl.org) and everyone else who worked on the
2255       original CGI.pm upon which this module is heavily based
2256
2257       Brandon Black for some heavy duty testing and bug fixes
2258
2259       John D Robinson and Jeroen Latour for helping solve some interesting
2260       test failures as well as Perlmonks: tommyw, grinder, Jaap, vek, erasei,
2261       jlongino and strider_corinth
2262
2263       Thanks for patches to:
2264
2265       Ewan Edwards, Joshua N Pritikin, Mike Barry, Michael Nachbaur, Chris
2266       Williams, Mark Stosberg, Krasimir Berov, Yamada Masahiro
2267
2269       Copyright (c) 2007, Andy Armstrong "<andy@hexten.net>". All rights
2270       reserved.
2271
2272       This module is free software; you can redistribute it and/or modify it
2273       under the same terms as Perl itself. See perlartistic.
2274

SEE ALSO

2276       CGI, CGI::Simple::Standard, CGI::Simple::Cookie, CGI::Simple::Util,
2277       CGI::Minimal
2278
2279
2280
2281perl v5.32.0                      2020-07-28                    CGI::Simple(3)
Impressum