.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "CGI::Simple 3pm"
.TH CGI::Simple 3pm 2024-02-04 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
CGI::Simple \- A Simple totally OO CGI interface that is CGI.pm compliant
.SH VERSION
.IX Header "VERSION"
This document describes CGI::Simple version 1.281.
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 3
\& use CGI::Simple;
\& $CGI::Simple::POST_MAX = 1024; # max upload via post default 100kB
\& $CGI::Simple::DISABLE_UPLOADS = 0; # enable uploads
\&
\& $q = CGI::Simple\->new;
\& $q = CGI::Simple\->new( { \*(Aqfoo\*(Aq=>\*(Aq1\*(Aq, \*(Aqbar\*(Aq=>[2,3,4] } );
\& $q = CGI::Simple\->new( \*(Aqfoo=1&bar=2&bar=3&bar=4\*(Aq );
\& $q = CGI::Simple\->new( \e*FILEHANDLE );
\&
\& $q\->save( \e*FILEHANDLE ); # save current object to a file as used by new
\&
\& @params = $q\->param; # return all param names as a list
\& $value = $q\->param(\*(Aqfoo\*(Aq); # return the first value supplied for \*(Aqfoo\*(Aq
\& @values = $q\->param(\*(Aqfoo\*(Aq); # return all values supplied for foo
\&
\& %fields = $q\->Vars; # returns untied key value pair hash
\& $hash_ref = $q\->Vars; # or as a hash ref
\& %fields = $q\->Vars("|"); # packs multiple values with "|" rather than "\e0";
\&
\& @keywords = $q\->keywords; # return all keywords as a list
\&
\& $q\->param( \*(Aqfoo\*(Aq, \*(Aqsome\*(Aq, \*(Aqnew\*(Aq, \*(Aqvalues\*(Aq ); # set new \*(Aqfoo\*(Aq values
\& $q\->param( \-name=>\*(Aqfoo\*(Aq, \-value=>\*(Aqbar\*(Aq );
\& $q\->param( \-name=>\*(Aqfoo\*(Aq, \-value=>[\*(Aqbar\*(Aq,\*(Aqbaz\*(Aq] );
\&
\& $q\->param( \*(Aqfoo\*(Aq, \*(Aqsome\*(Aq, \*(Aqnew\*(Aq, \*(Aqvalues\*(Aq ); # append values to \*(Aqfoo\*(Aq
\& $q\->append( \-name=>\*(Aqfoo\*(Aq, \-value=>\*(Aqbar\*(Aq );
\& $q\->append( \-name=>\*(Aqfoo\*(Aq, \-value=>[\*(Aqsome\*(Aq, \*(Aqnew\*(Aq, \*(Aqvalues\*(Aq] );
\&
\& $q\->delete(\*(Aqfoo\*(Aq); # delete param \*(Aqfoo\*(Aq and all its values
\& $q\->delete_all; # delete everything
\&
\&
\&
\& $files = $q\->upload() # number of files uploaded
\& @files = $q\->upload(); # names of all uploaded files
\& $filename = $q\->param(\*(Aqupload_file\*(Aq) # filename of uploaded file
\& $mime = $q\->upload_info($filename,\*(Aqmime\*(Aq); # MIME type of uploaded file
\& $size = $q\->upload_info($filename,\*(Aqsize\*(Aq); # size of uploaded file
\&
\& my $fh = $q\->upload($filename); # get filehandle to read from
\& while ( read( $fh, $buffer, 1024 ) ) { ... }
\&
\& # short and sweet upload
\& $ok = $q\->upload( $q\->param(\*(Aqupload_file\*(Aq), \*(Aq/path/to/write/file.name\*(Aq );
\& print "Uploaded ".$q\->param(\*(Aqupload_file\*(Aq)." and wrote it OK!" if $ok;
\&
\& $decoded = $q\->url_decode($encoded);
\& $encoded = $q\->url_encode($unencoded);
\& $escaped = $q\->escapeHTML(\*(Aq<>"&\*(Aq);
\& $unescaped = $q\->unescapeHTML(\*(Aq<>"&\*(Aq);
\&
\& $qs = $q\->query_string; # get all data in $q as a query string OK for GET
\&
\& $q\->no_cache(1); # set Pragma: no\-cache + expires
\& print $q\->header(); # print a simple header
\& # get a complex header
\& $header = $q\->header( \-type => \*(Aqimage/gif\*(Aq
\& \-nph => 1,
\& \-status => \*(Aq402 Payment required\*(Aq,
\& \-expires =>\*(Aq+24h\*(Aq,
\& \-cookie => $cookie,
\& \-charset => \*(Aqutf\-7\*(Aq,
\& \-attachment => \*(Aqfoo.gif\*(Aq,
\& \-Cost => \*(Aq$2.00\*(Aq
\& );
\& # a p3p header (OK for redirect use as well)
\& $header = $q\->header( \-p3p => \*(Aqpolicyref="http://somesite.com/P3P/PolicyReferences.xml\*(Aq );
\&
\& @cookies = $q\->cookie(); # get names of all available cookies
\& $value = $q\->cookie(\*(Aqfoo\*(Aq) # get first value of cookie \*(Aqfoo\*(Aq
\& @value = $q\->cookie(\*(Aqfoo\*(Aq) # get all values of cookie \*(Aqfoo\*(Aq
\& # get a cookie formatted for header() method
\& $cookie = $q\->cookie( \-name => \*(AqPassword\*(Aq,
\& \-values => [\*(Aqsuperuser\*(Aq,\*(Aqgod\*(Aq,\*(Aqmy dog woofie\*(Aq],
\& \-expires => \*(Aq+3d\*(Aq,
\& \-domain => \*(Aq.nowhere.com\*(Aq,
\& \-path => \*(Aq/cgi\-bin/database\*(Aq,
\& \-secure => 1
\& );
\& print $q\->header( \-cookie=>$cookie ); # set cookie
\&
\& print $q\->redirect(\*(Aqhttp://go.away.now\*(Aq); # print a redirect header
\&
\& dienice( $q\->cgi_error ) if $q\->cgi_error;
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
CGI::Simple provides a relatively lightweight drop in replacement for CGI.pm.
It shares an identical OO interface to CGI.pm for parameter parsing, file
upload, cookie handling and header generation. This module is entirely object
oriented, however a complete functional interface is available by using the
CGI::Simple::Standard module.
.PP
Essentially everything in CGI.pm that relates to the CGI (not HTML) side of
things is available. There are even a few new methods and additions to old
ones! If you are interested in what has gone on under the hood see the
Compatibility with CGI.pm section at the end.
.PP
In practical testing this module loads and runs about twice as fast as CGI.pm
depending on the precise task.
.SH "CALLING CGI::Simple ROUTINES USING THE OBJECT INTERFACE"
.IX Header "CALLING CGI::Simple ROUTINES USING THE OBJECT INTERFACE"
Here is a very brief rundown on how you use the interface. Full details
follow.
.SS "First you need to initialize an object"
.IX Subsection "First you need to initialize an object"
Before you can call a CGI::Simple method you must create a CGI::Simple object.
You do that by using the module and then calling the \fBnew()\fR constructor:
.PP
.Vb 2
\& use CGI::Simple;
\& my $q = CGI::Simple\->new;
.Ve
.PP
It is traditional to call your object \f(CW$q\fR for query or perhaps \f(CW$cgi\fR.
.SS "Next you call methods on that object"
.IX Subsection "Next you call methods on that object"
Once you have your object you can call methods on it using the \-> arrow
syntax For example to get the names of all the parameters passed to your
script you would just write:
.PP
.Vb 1
\& @names = $q\->param();
.Ve
.PP
Many methods are sensitive to the context in which you call them. In the
example above the \fBparam()\fR method returns a list of all the parameter names
when called without any arguments.
.PP
When you call \fBparam('arg')\fR with a single argument it assumes you want
to get the value(s) associated with that argument (parameter). If you ask
for an array it gives you an array of all the values associated with it's
argument:
.PP
.Vb 1
\& @values = $q\->param(\*(Aqfoo\*(Aq); # get all the values for \*(Aqfoo\*(Aq
.Ve
.PP
whereas if you ask for a scalar like this:
.PP
.Vb 1
\& $value = $q\->param(\*(Aqfoo\*(Aq); # get only the first value for \*(Aqfoo\*(Aq
.Ve
.PP
then it returns only the first value (if more than one value for
\&'foo' exists).
.PP
In case you ased for a list it will return all the values preserving the
order in which the values of the given key were passed in the request.
.PP
Most CGI::Simple routines accept several arguments, sometimes as many as
10 optional ones! To simplify this interface, all routines use a named
argument calling style that looks like this:
.PP
.Vb 1
\& print $q\->header( \-type=>\*(Aqimage/gif\*(Aq, \-expires=>\*(Aq+3d\*(Aq );
.Ve
.PP
Each argument name is preceded by a dash. Neither case nor order
matters in the argument list. \-type, \-Type, and \-TYPE are all
acceptable.
.PP
Several routines are commonly called with just one argument. In the
case of these routines you can provide the single argument without an
argument name. \fBheader()\fR happens to be one of these routines. In this
case, the single argument is the document type.
.PP
.Vb 1
\& print $q\->header(\*(Aqtext/html\*(Aq);
.Ve
.PP
Sometimes methods expect a scalar, sometimes a reference to an
array, and sometimes a reference to a hash. Often, you can pass any
type of argument and the routine will do whatever is most appropriate.
For example, the \fBparam()\fR method can be used to set a CGI parameter to a
single or a multi-valued value. The two cases are shown below:
.PP
.Vb 2
\& $q\->param(\-name=>\*(Aqveggie\*(Aq,\-value=>\*(Aqtomato\*(Aq);
\& $q\->param(\-name=>\*(Aqveggie\*(Aq,\-value=>[\*(Aqtomato\*(Aq,\*(Aqtomahto\*(Aq,\*(Aqpotato\*(Aq,\*(Aqpotahto\*(Aq]);
.Ve
.SH "CALLING CGI::Simple ROUTINES USING THE FUNCTION INTERFACE"
.IX Header "CALLING CGI::Simple ROUTINES USING THE FUNCTION INTERFACE"
For convenience a functional interface is provided by the
CGI::Simple::Standard module. This hides the OO details from you and allows
you to simply call methods. You may either use AUTOLOADING of methods or
import specific method sets into you namespace. Here are the first few
examples again using the function interface.
.PP
.Vb 6
\& use CGI::Simple::Standard qw(\-autoload);
\& @names = param();
\& @values = param(\*(Aqfoo\*(Aq);
\& $value = param(\*(Aqfoo\*(Aq);
\& print header(\-type=>\*(Aqimage/gif\*(Aq,\-expires=>\*(Aq+3d\*(Aq);
\& print header(\*(Aqtext/html\*(Aq);
.Ve
.PP
Yes that's it. Not a \f(CW$q\fR\-> in sight. You just use the module and select
how/which methods to load. You then just call the methods you want exactly
as before but without the \f(CW$q\fR\-> notation.
.PP
When (if) you read the following docs and are using the functional interface
just pretend the \f(CW$q\fR\-> is not there.
.SS "Selecting which methods to load"
.IX Subsection "Selecting which methods to load"
When you use the functional interface Perl needs to be able to find the
functions you call. The simplest way of doing this is to use autoloading as
shown above. When you use CGI::Simple::Standard with the '\-autoload' pragma
it exports a single AUTOLOAD sub into you namespace. Every time you call a
non existent function AUTOLOAD is called and will load the required
function and install it in your namespace. Thus only the AUTOLOAD sub and
those functions you specifically call will be imported.
.PP
Alternatively CGI::Simple::Standard provides a range of function sets you can
import or you can just select exactly what you want. You do this using the
familiar
.PP
.Vb 1
\& use CGI::Simple::Standard qw( :func_set some_func);
.Ve
.PP
notation. This will import the ':func_set' function set and the specific
function 'some_func'.
.SS "To Autoload or not to Autoload, that is the question."
.IX Subsection "To Autoload or not to Autoload, that is the question."
If you do not have a AUTOLOAD sub in you script it is generally best to use
the '\-autoload' option. Under autoload you can use any method you want but
only import and compile those functions you actually use.
.PP
If you do not use autoload you must specify what functions to import. You can
only use functions that you have imported. For comvenience functions are
grouped into related sets. If you choose to import one or more ':func_set'
you may have potential namespace collisions so check out the docs to see
what gets imported. Using the ':all' tag is pretty slack but it is there
if you want. Full details of the function sets are provided in the
CGI::Simple::Standard docs
.PP
If you just want say the param and header methods just load these two.
.PP
.Vb 1
\& use CGI::Simple::Standard qw(param header);
.Ve
.SS "Setting globals using the functional interface"
.IX Subsection "Setting globals using the functional interface"
Where you see global variables being set using the syntax:
.PP
.Vb 1
\& $CGI::Simple::DEBUG = 1;
.Ve
.PP
You use exactly the same syntax when using CGI::Simple::Standard.
.SH "THE CORE METHODS"
.IX Header "THE CORE METHODS"
.SS "\fBnew()\fP Creating a new query object"
.IX Subsection "new() Creating a new query object"
The first step in using CGI::Simple is to create a new query object using
the \fBnew()\fR constructor:
.PP
.Vb 1
\& $q = CGI::Simple\->new;
.Ve
.PP
This will parse the input (from both POST and GET methods) and store
it into an object called \f(CW$q\fR.
.PP
If you provide a file handle to the \fBnew()\fR method, it will read
parameters from the file (or STDIN, or whatever).
.PP
Historically people were doing this way:
.PP
.Vb 2
\& open FH, "test.in" or die $!;
\& $q = CGI::Simple\->new(\e*FH);
.Ve
.PP
but this is the recommended way:
.PP
.Vb 2
\& open $fh, \*(Aq<\*(Aq, "test.in" or die $!;
\& $q = CGI::Simple\->new($fh);
.Ve
.PP
The file should be a series of newline delimited TAG=VALUE pairs.
Conveniently, this type of file is created by the \fBsave()\fR method
(see below). Multiple records can be saved and restored.
IO::File objects work fine.
.PP
If you are using the function-oriented interface provided by
CGI::Simple::Standard and want to initialize from a file handle,
the way to do this is with \fBrestore_parameters()\fR. This will (re)initialize
the default CGI::Simple object from the indicated file handle.
.PP
.Vb 1
\& restore_parameters($fh);
.Ve
.PP
In fact for all intents and purposes \fBrestore_parameters()\fR is identical
to \fBnew()\fR Note that \fBrestore_parameters()\fR does not exist in
CGI::Simple itself so you can't use it.
.PP
You can also initialize the query object from an associative array
reference:
.PP
.Vb 4
\& $q = CGI::Simple\->new( { \*(Aqdinosaur\*(Aq => \*(Aqbarney\*(Aq,
\& \*(Aqsong\*(Aq => \*(AqI love you\*(Aq,
\& \*(Aqfriends\*(Aq => [qw/Jessica George Nancy/] }
\& );
.Ve
.PP
or from a properly formatted, URL-escaped query string:
.PP
.Vb 1
\& $q = CGI::Simple\->new( \*(Aqdinosaur=barney&color=purple\*(Aq );
.Ve
.PP
or from a previously existing CGI::Simple object (this generates an identical clone
including all global variable settings, etc that are stored in the object):
.PP
.Vb 2
\& $old_query = CGI::Simple\->new;
\& $new_query = CGI::Simple\->new($old_query);
.Ve
.PP
To create an empty query, initialize it from an empty string or hash:
.PP
.Vb 1
\& $empty_query = CGI::Simple\->new("");
\&
\& \-or\-
\&
\& $empty_query = CGI::Simple\->new({});
.Ve
.SS "\fBkeywords()\fP Fetching a list of keywords from a query"
.IX Subsection "keywords() Fetching a list of keywords from a query"
.Vb 1
\& @keywords = $q\->keywords;
.Ve
.PP
If the script was invoked as the result of an
tags so if you send it straight to the browser it produces something that looks like: .PP .Vb 10 \& $VAR1 = bless( { \& \*(Aq.parameters\*(Aq => [ \& \*(Aqname\*(Aq, \& \*(Aqcolor\*(Aq \& ], \& \*(Aq.globals\*(Aq => { \& \*(AqFATAL\*(Aq => \-1, \& \*(AqDEBUG\*(Aq => 0, \& \*(AqNO_NULL\*(Aq => 1, \& \*(AqPOST_MAX\*(Aq => 102400, \& \*(AqUSE_CGI_PM_DEFAULTS\*(Aq => 0, \& \*(AqHEADERS_ONCE\*(Aq => 0, \& \*(AqNPH\*(Aq => 0, \& \*(AqDISABLE_UPLOADS\*(Aq => 1, \& \*(AqNO_UNDEF_PARAMS\*(Aq => 0, \& \*(AqUSE_PARAM_SEMICOLONS\*(Aq => 0 \& }, \& \*(Aq.fieldnames\*(Aq => { \& \*(Aqcolor\*(Aq => \*(Aq1\*(Aq, \& \*(Aqname\*(Aq => \*(Aq1\*(Aq \& }, \& \*(Aq.mod_perl\*(Aq => \*(Aq\*(Aq, \& \*(Aqcolor\*(Aq => [ \& \*(Aqred\*(Aq, \& \*(Aqgreen\*(Aq, \& \*(Aqblue\*(Aq \& ], \& \*(Aqname\*(Aq => [ \& \*(AqJaPh,\*(Aq \& ] \& }, \*(AqCGI::Simple\*(Aq ); .Ve .PP You may recognize this as valid Perl syntax (which it is) and/or the output from Data::Dumper (also true). This is the actual guts of how the information is stored in the query object. All the internal params start with a . char .PP Alternatively you can dump your object and the current environment using: .PP .Vb 1 \& print $q\->Dump(\e%ENV); .Ve .SS "\fBPrintEnv()\fP Dumping the environment" .IX Subsection "PrintEnv() Dumping the environment" You can get a similar browser friendly dump of the current \f(CW%ENV\fR hash using: .PP .Vb 1 \& print $q\->PrintEnv; .Ve .PP This will produce something like (in the browser): .PP .Vb 10 \& $VAR1 = { \& \*(AqQUERY_STRING\*(Aq => \*(Aqname=JaPh%2C&color=red&color=green&color=blue\*(Aq, \& \*(AqCONTENT_TYPE\*(Aq => \*(Aqapplication/x\-www\-form\-urlencoded\*(Aq, \& \*(AqREGRESSION_TEST\*(Aq => \*(Aqsimple.t.pl\*(Aq, \& \*(AqVIM\*(Aq => \*(AqC:\e\eWINDOWS\e\eDesktop\e\evim\*(Aq, \& \*(AqHTTP_REFERER\*(Aq => \*(Aqxxx.sex.com\*(Aq, \& \*(AqHTTP_USER_AGENT\*(Aq => \*(AqLWP\*(Aq, \& \*(AqHTTP_ACCEPT\*(Aq => \*(Aqtext/html;q=1, image/gif;q=0.42, */*;q=0.001\*(Aq, \& \*(AqREMOTE_HOST\*(Aq => \*(Aqlocalhost\*(Aq, \& \*(AqHTTP_HOST\*(Aq => \*(Aqthe.restaurant.at.the.end.of.the.universe\*(Aq, \& \*(AqGATEWAY_INTERFACE\*(Aq => \*(Aqbleeding edge\*(Aq, \& \*(AqREMOTE_IDENT\*(Aq => \*(AqNone of your damn business\*(Aq, \& \*(AqSCRIPT_NAME\*(Aq => \*(Aq/cgi\-bin/foo.cgi\*(Aq, \& \*(AqSERVER_NAME\*(Aq => \*(Aqnowhere.com\*(Aq, \& \*(AqHTTP_COOKIE\*(Aq => \*(Aq\*(Aq, \& \*(AqCONTENT_LENGTH\*(Aq => \*(Aq42\*(Aq, \& \*(AqHTTPS_A\*(Aq => \*(AqA\*(Aq, \& \*(AqHTTP_FROM\*(Aq => \*(Aqspammer@nowhere.com\*(Aq, \& \*(AqHTTPS_B\*(Aq => \*(AqB\*(Aq, \& \*(AqSERVER_PROTOCOL\*(Aq => \*(AqHTTP/1.0\*(Aq, \& \*(AqPATH_TRANSLATED\*(Aq => \*(Aq/usr/local/somewhere/else\*(Aq, \& \*(AqSERVER_SOFTWARE\*(Aq => \*(AqApache \- accept no substitutes\*(Aq, \& \*(AqPATH_INFO\*(Aq => \*(Aq/somewhere/else\*(Aq, \& \*(AqREMOTE_USER\*(Aq => \*(AqJust another Perl hacker,\*(Aq, \& \*(AqREMOTE_ADDR\*(Aq => \*(Aq127.0.0.1\*(Aq, \& \*(AqHTTPS\*(Aq => \*(AqON\*(Aq, \& \*(AqDOCUMENT_ROOT\*(Aq => \*(Aq/vs/www/foo\*(Aq, \& \*(AqREQUEST_METHOD\*(Aq => \*(AqGET\*(Aq, \& \*(AqREDIRECT_QUERY_STRING\*(Aq => \*(Aq\*(Aq, \& \*(AqAUTH_TYPE\*(Aq => \*(AqPGP MD5 DES rot13\*(Aq, \& \*(AqCOOKIE\*(Aq => \*(Aqfoo=a%20phrase; bar=yes%2C%20a%20phrase&;I%20say;\*(Aq, \& \*(AqSERVER_PORT\*(Aq => \*(Aq8080\*(Aq \& }; .Ve .SS "\fBcgi_error()\fP Retrieving CGI::Simple error messages" .IX Subsection "cgi_error() Retrieving CGI::Simple error messages" Errors can occur while processing user input, particularly when processing uploaded files. When these errors occur, CGI::Simple will stop processing and return an empty parameter list. You can test for the existence and nature of errors using the \fBcgi_error()\fR function. The error messages are formatted as HTTP status codes. You can either incorporate the error text into an HTML page, or use it as the value of the HTTP status: .PP .Vb 6 \& my $error = $q\->cgi_error; \& if ($error) { \& print $q\->header(\-status=>$error); \& print "$error
; \& exit; \& } .Ve .SH "ACCESSOR METHODS" .IX Header "ACCESSOR METHODS" .SS "\fBversion()\fP Get the CGI::Simple version info" .IX Subsection "version() Get the CGI::Simple version info" .Vb 1 \& $version = $q\->version(); .Ve .PP The \fBversion()\fR method returns the value of \f(CW$VERSION\fR .SS "\fBnph()\fP Enable/disable NPH (Non Parsed Header) mode" .IX Subsection "nph() Enable/disable NPH (Non Parsed Header) mode" .Vb 2 \& $q\->nph(1); # enable NPH mode \& $q\->nph(0); # disable NPH mode .Ve .PP The \fBnph()\fR method enables and disables NPH headers. See the NPH section. .SS "\fBall_parameters()\fP Get the names/values of all parameters" .IX Subsection "all_parameters() Get the names/values of all parameters" .Vb 1 \& @all_parameters = $q\->all_parameters(); .Ve .PP The \fBall_parameters()\fR method is an alias for \fBparam()\fR .SS "\fBcharset()\fP Get/set the current character set." .IX Subsection "charset() Get/set the current character set." .Vb 2 \& $charset = $q\->charset(); # get current charset \& $q\->charset(\*(Aqutf\-42\*(Aq); # set the charset .Ve .PP The \fBcharset()\fR method gets the current charset value if no argument is supplied or sets it if an argument is supplied. .SS "\fBcrlf()\fP Get the system specific line ending sequence" .IX Subsection "crlf() Get the system specific line ending sequence" .Vb 1 \& $crlf = $q\->crlf(); .Ve .PP The \fBcrlf()\fR method returns the system specific line ending sequence. .SS "\fBglobals()\fP Get/set the value of the remaining global variables" .IX Subsection "globals() Get/set the value of the remaining global variables" .Vb 2 \& $globals = $q\->globals(\*(AqFATAL\*(Aq); # get the current value of $FATAL \& $globals = $q\->globals(\*(AqFATAL\*(Aq, 1 ); # set croak mode on cgi_error() .Ve .PP The \fBglobals()\fR method gets/sets the values of the global variables after the script has been invoked. For globals like \f(CW$POST_MAX\fR and \f(CW$DISABLE_UPLOADS\fR this makes no difference as they must be set prior to calling the new constructor but there might be reason the change the value of others. .SS "\fBauth_type()\fP Get the current authorization/verification method" .IX Subsection "auth_type() Get the current authorization/verification method" .Vb 1 \& $auth_type = $q\->auth_type(); .Ve .PP The \fBauth_type()\fR method returns the value of \f(CW$ENV\fR{'AUTH_TYPE'} which should contain the authorization/verification method in use for this script, if any. .SS "\fBcontent_length()\fP Get the content length submitted in a POST" .IX Subsection "content_length() Get the content length submitted in a POST" .Vb 1 \& $content_length = $q\->content_length(); .Ve .PP The \fBcontent_length()\fR method returns the value of \f(CW$ENV\fR{'AUTH_TYPE'} .SS "\fBcontent_type()\fP Get the content_type of data submitted in a POST" .IX Subsection "content_type() Get the content_type of data submitted in a POST" .Vb 1 \& $content_type = $q\->content_type(); .Ve .PP The \fBcontent_type()\fR method returns the content_type of data submitted in a POST, generally 'multipart/form\-data' or \&'application/x\-www\-form\-urlencoded' as supplied in \f(CW$ENV\fR{'CONTENT_TYPE'} .SS "\fBdocument_root()\fP Get the document root" .IX Subsection "document_root() Get the document root" .Vb 1 \& $document_root = $q\->document_root(); .Ve .PP The \fBdocument_root()\fR method returns the value of \f(CW$ENV\fR{'DOCUMENT_ROOT'} .SS "\fBgateway_interface()\fP Get the gateway interface" .IX Subsection "gateway_interface() Get the gateway interface" .Vb 1 \& $gateway_interface = $q\->gateway_interface(); .Ve .PP The \fBgateway_interface()\fR method returns the value of \&\f(CW$ENV\fR{'GATEWAY_INTERFACE'} .SS "\fBpath_translated()\fP Get the value of path translated" .IX Subsection "path_translated() Get the value of path translated" .Vb 1 \& $path_translated = $q\->path_translated(); .Ve .PP The \fBpath_translated()\fR method returns the value of \f(CW$ENV\fR{'PATH_TRANSLATED'} .SS "\fBreferer()\fP Spy on your users" .IX Subsection "referer() Spy on your users" .Vb 1 \& $referer = $q\->referer(); .Ve .PP The \fBreferer()\fR method returns the value of \f(CW$ENV\fR{'REFERER'} This will return the URL of the page the browser was viewing prior to fetching your script. Not available for all browsers. .SS "\fBremote_addr()\fP Get the remote address" .IX Subsection "remote_addr() Get the remote address" .Vb 1 \& $remote_addr = $q\->remote_addr(); .Ve .PP The \fBremote_addr()\fR method returns the value of \f(CW$ENV\fR{'REMOTE_ADDR'} or 127.0.0.1 (localhost) if this is not defined. .SS "\fBremote_host()\fP Get a value for remote host" .IX Subsection "remote_host() Get a value for remote host" .Vb 1 \& $remote_host = $q\->remote_host(); .Ve .PP The \fBremote_host()\fR method returns the value of \f(CW$ENV\fR{'REMOTE_HOST'} if it is defined. If this is not defined it returns \f(CW$ENV\fR{'REMOTE_ADDR'} If this is not defined it returns 'localhost' .SS "\fBremote_ident()\fP Get the remote identity" .IX Subsection "remote_ident() Get the remote identity" .Vb 1 \& $remote_ident = $q\->remote_ident(); .Ve .PP The \fBremote_ident()\fR method returns the value of \f(CW$ENV\fR{'REMOTE_IDENT'} .SS "\fBremote_user()\fP Get the remote user" .IX Subsection "remote_user() Get the remote user" .Vb 1 \& $remote_user = $q\->remote_user(); .Ve .PP The \fBremote_user()\fR method returns the authorization/verification name used for user verification, if this script is protected. The value comes from \&\f(CW$ENV\fR{'REMOTE_USER'} .SS "\fBrequest_method()\fP Get the request method" .IX Subsection "request_method() Get the request method" .Vb 1 \& $request_method = $q\->request_method(); .Ve .PP The \fBrequest_method()\fR method returns the method used to access your script, usually one of 'POST', 'GET' or 'HEAD' as supplied by \&\f(CW$ENV\fR{'REQUEST_METHOD'} .SS "\fBscript_name()\fP Get the script name" .IX Subsection "script_name() Get the script name" .Vb 1 \& $script_name = $q\->script_name(); .Ve .PP The \fBscript_name()\fR method returns the value of \f(CW$ENV\fR{'SCRIPT_NAME'} if it is defined. Otherwise it returns Perl's script name from \f(CW$0\fR. Failing this it returns a null string '' .SS "\fBserver_name()\fP Get the server name" .IX Subsection "server_name() Get the server name" .Vb 1 \& $server_name = $q\->server_name(); .Ve .PP The \fBserver_name()\fR method returns the value of \f(CW$ENV\fR{'SERVER_NAME'} if defined or 'localhost' otherwise .SS "\fBserver_port()\fP Get the port the server is listening on" .IX Subsection "server_port() Get the port the server is listening on" .Vb 1 \& $server_port = $q\->server_port(); .Ve .PP The \fBserver_port()\fR method returns the value \f(CW$ENV\fR{'SERVER_PORT'} if defined or 80 if not. .SS "\fBserver_protocol()\fP Get the current server protocol" .IX Subsection "server_protocol() Get the current server protocol" .Vb 1 \& $server_protocol = $q\->server_protocol(); .Ve .PP The \fBserver_protocol()\fR method returns the value of \f(CW$ENV\fR{'SERVER_PROTOCOL'} if defined or 'HTTP/1.0' otherwise .SS "\fBserver_software()\fP Get the server software" .IX Subsection "server_software() Get the server software" .Vb 1 \& $server_software = $q\->server_software(); .Ve .PP The \fBserver_software()\fR method returns the value \f(CW$ENV\fR{'SERVER_SOFTWARE'} or \&'cmdline' If the server software is IIS it formats your hard drive, installs Linux, FTPs to www.apache.org, installs Apache, and then restores your system from tape. Well maybe not, but it's a nice thought. .SS "\fBuser_name()\fP Get a value for the user name." .IX Subsection "user_name() Get a value for the user name." .Vb 1 \& $user_name = $q\->user_name(); .Ve .PP Attempt to obtain the remote user's name, using a variety of different techniques. This only works with older browsers such as Mosaic. Newer browsers do not report the user name for privacy reasons! .PP Technically the \fBuser_name()\fR method returns the value of \f(CW$ENV\fR{'HTTP_FROM'} or failing that \f(CW$ENV\fR{'REMOTE_IDENT'} or as a last choice \f(CW$ENV\fR{'REMOTE_USER'} .SS "\fBuser_agent()\fP Get the users browser type" .IX Subsection "user_agent() Get the users browser type" .Vb 2 \& $ua = $q\->user_agent(); # return the user agent \& $ok = $q\->user_agent(\*(Aqmozilla\*(Aq); # return true if user agent \*(Aqmozilla\*(Aq .Ve .PP The \fBuser_agent()\fR method returns the value of \f(CW$ENV\fR{'HTTP_USER_AGENT'} when called without an argument or true or false if the \f(CW$ENV\fR{'HTTP_USER_AGENT'} matches the passed argument. The matching is case insensitive and partial. .SS "\fBvirtual_host()\fP Get the virtual host" .IX Subsection "virtual_host() Get the virtual host" .Vb 1 \& $virtual_host = $q\->virtual_host(); .Ve .PP The \fBvirtual_host()\fR method returns the value of \f(CW$ENV\fR{'HTTP_HOST'} if defined or \f(CW$ENV\fR{'SERVER_NAME'} as a default. Port numbers are removed. .SS "\fBpath_info()\fP Get any extra path info set to the script" .IX Subsection "path_info() Get any extra path info set to the script" .Vb 1 \& $path_info = $q\->path_info(); .Ve .PP The \fBpath_info()\fR method returns additional path information from the script URL. E.G. fetching /cgi\-bin/your_script/additional/stuff will result in \&\f(CW$q\fR\->\fBpath_info()\fR returning "/additional/stuff". .PP NOTE: The Microsoft Internet Information Server is broken with respect to additional path information. If you use the Perl DLL library, the IIS server will attempt to execute the additional path information as a Perl script. If you use the ordinary file associations mapping, the path information will be present in the environment, but incorrect. The best thing to do is to avoid using additional path information in CGI scripts destined for use with IIS. .SS "\fBAccept()\fP Get the browser MIME types" .IX Subsection "Accept() Get the browser MIME types" .Vb 1 \& $Accept = $q\->Accept(); .Ve .PP The \fBAccept()\fR method returns a list of MIME types that the remote browser accepts. If you give this method a single argument corresponding to a MIME type, as in \f(CW$q\fR\->Accept('text/html'), it will return a floating point value corresponding to the browser's preference for this type from 0.0 (don't want) to 1.0. Glob types (e.g. text/*) in the browser's accept list are handled correctly. .SS "\fBaccept()\fP Alias for \fBAccept()\fP" .IX Subsection "accept() Alias for Accept()" .Vb 1 \& $accept = $q\->accept(); .Ve .PP The \fBaccept()\fR Method is an alias for \fBAccept()\fR .SS "\fBhttp()\fP Get a range of HTTP related information" .IX Subsection "http() Get a range of HTTP related information" .Vb 1 \& $http = $q\->http(); .Ve .PP Called with no arguments the \fBhttp()\fR method returns the list of HTTP or HTTPS environment variables, including such things as HTTP_USER_AGENT, HTTP_ACCEPT_LANGUAGE, and HTTP_ACCEPT_CHARSET, corresponding to the like-named HTTP header fields in the request. Called with the name of an HTTP header field, returns its value. Capitalization and the use of hyphens versus underscores are not significant. .PP For example, all three of these examples are equivalent: .PP .Vb 3 \& $requested_language = $q\->http(\*(AqAccept\-language\*(Aq); \& $requested_language = $q\->http(\*(AqAccept_language\*(Aq); \& $requested_language = $q\->http(\*(AqHTTP_ACCEPT_LANGUAGE\*(Aq); .Ve .SS "\fBhttps()\fP Get a range of HTTPS related information" .IX Subsection "https() Get a range of HTTPS related information" .Vb 1 \& $https = $q\->https(); .Ve .PP The \fBhttps()\fR method is similar to the \fBhttp()\fR method except that when called without an argument it returns the value of \f(CW$ENV\fR{'HTTPS'} which will be true if a HTTPS connection is in use and false otherwise. .SS "\fBprotocol()\fP Get the current protocol" .IX Subsection "protocol() Get the current protocol" .Vb 1 \& $protocol = $q\->protocol(); .Ve .PP The \fBprotocol()\fR method returns 'https' if a HTTPS connection is in use or the \&\fBserver_protocol()\fR minus version numbers ('http') otherwise. .SS "\fBurl()\fP Return the script's URL in several formats" .IX Subsection "url() Return the script's URL in several formats" .Vb 7 \& $full_url = $q\->url(); \& $full_url = $q\->url(\-full=>1); \& $relative_url = $q\->url(\-relative=>1); \& $absolute_url = $q\->url(\-absolute=>1); \& $url_with_path = $q\->url(\-path_info=>1); \& $url_with_path_and_query = $q\->url(\-path_info=>1,\-query=>1); \& $netloc = $q\->url(\-base => 1); .Ve .PP \&\fBurl()\fR returns the script's URL in a variety of formats. Called without any arguments, it returns the full form of the URL, including host name and port number .PP .Vb 1 \& http://your.host.com/path/to/script.cgi .Ve .PP You can modify this format with the following named arguments: .IP \fB\-absolute\fR 4 .IX Item "-absolute" If true, produce an absolute URL, e.g. .Sp .Vb 1 \& /path/to/script.cgi .Ve .IP \fB\-relative\fR 4 .IX Item "-relative" Produce a relative URL. This is useful if you want to reinvoke your script with different parameters. For example: .Sp .Vb 1 \& script.cgi .Ve .IP \fB\-full\fR 4 .IX Item "-full" Produce the full URL, exactly as if called without any arguments. This overrides the \-relative and \-absolute arguments. .IP "\fB\-path\fR (\fB\-path_info\fR)" 4 .IX Item "-path (-path_info)" Append the additional path information to the URL. This can be combined with \fB\-full\fR, \fB\-absolute\fR or \fB\-relative\fR. \fB\-path_info\fR is provided as a synonym. .IP "\fB\-query\fR (\fB\-query_string\fR)" 4 .IX Item "-query (-query_string)" Append the query string to the URL. This can be combined with \&\fB\-full\fR, \fB\-absolute\fR or \fB\-relative\fR. \fB\-query_string\fR is provided as a synonym. .IP \fB\-base\fR 4 .IX Item "-base" Generate just the protocol and net location, as in http://www.foo.com:8000 .SS "\fBself_url()\fP Get the scripts complete URL" .IX Subsection "self_url() Get the scripts complete URL" .Vb 1 \& $self_url = $q\->self_url(); .Ve .PP The \fBself_url()\fR method returns the value of: .PP .Vb 1 \& $self\->url( \*(Aq\-path_info\*(Aq=>1, \*(Aq\-query\*(Aq=>1, \*(Aq\-full\*(Aq=>1 ); .Ve .SS "\fBstate()\fP Alias for \fBself_url()\fP" .IX Subsection "state() Alias for self_url()" .Vb 1 \& $state = $q\->state(); .Ve .PP The \fBstate()\fR method is an alias for \fBself_url()\fR .SH "COMPATIBILITY WITH cgi\-lib.pl 2.18" .IX Header "COMPATIBILITY WITH cgi-lib.pl 2.18" To make it easier to port existing programs that use cgi\-lib.pl all the subs within cgi\-lib.pl are available in CGI::Simple. Using the functional interface of CGI::Simple::Standard porting is as easy as: .PP .Vb 4 \& OLD VERSION \& require "cgi\-lib.pl"; \& &ReadParse; \& print "The value of the antique is $in{\*(Aqantique\*(Aq}.\en"; \& \& NEW VERSION \& use CGI::Simple::Standard qw(:cgi\-lib); \& &ReadParse; \& print "The value of the antique is $in{\*(Aqantique\*(Aq}.\en"; .Ve .PP CGI:Simple's \fBReadParse()\fR routine creates a variable named \f(CW%in\fR, which can be accessed to obtain the query variables. Like ReadParse, you can also provide your own variable via a glob. Infrequently used features of \fBReadParse()\fR, such as the creation of \f(CW@in\fR and \f(CW$in\fR variables, are not supported. .PP You can also use the OO interface of CGI::Simple and call \fBReadParse()\fR and other cgi\-lib.pl functions like this: .PP .Vb 1 \& &CGI::Simple::ReadParse; # get hash values in %in \& \& my $q = CGI::Simple\->new; \& $q\->ReadParse(); # same thing \& \& CGI::Simple::ReadParse(*field); # get hash values in %field function style \& \& my $q = CGI::Simple\->new; \& $q\->ReadParse(*field); # same thing .Ve .PP Once you use \fBReadParse()\fR under the functional interface , you can retrieve the query object itself this way if needed: .PP .Vb 1 \& $q = $in{\*(AqCGI\*(Aq}; .Ve .PP Either way it allows you to start using the more interesting features of CGI.pm without rewriting your old scripts from scratch. .PP Unlike CGI.pm all the cgi\-lib.pl functions from Version 2.18 are supported: .PP .Vb 10 \& ReadParse() \& SplitParam() \& MethGet() \& MethPost() \& MyBaseUrl() \& MyURL() \& MyFullUrl() \& PrintHeader() \& HtmlTop() \& HtmlBot() \& PrintVariables() \& PrintEnv() \& CgiDie() \& CgiError() .Ve .SH "COMPATIBILITY WITH CGI.pm" .IX Header "COMPATIBILITY WITH CGI.pm" I has long been suggested that the CGI and HTML parts of CGI.pm should be split into separate modules (even the author suggests this!), CGI::Simple represents the realization of this and contains the complete CGI side of CGI.pm. Code-wise it weighs in at a little under 30% of the size of CGI.pm at a little under 1000 lines. .PP A great deal of care has been taken to ensure that the interface remains unchanged although a few tweaks have been made. The test suite is extensive and includes all the CGI.pm test scripts as well as a series of new test scripts. You may like to have a look at /t/concur.t which makes 160 tests of CGI::Simple and CGI in parallel and compares the results to ensure they are identical. This is the case as of CGI.pm 2.78. .PP You can't make an omelet without breaking eggs. A large number of methods and global variables have been deleted as detailed below. Some pragmas are also gone. In the tarball there is a script \fB/misc/check.pl\fR that will check if a script seems to be using any of these now non existent methods, globals or pragmas. You call it like this: .PP .Vb 1 \& perl check.pl.Ve .PP If it finds any likely candidates it will print a line with the line number, problem method/global and the complete line. For example here is some output from running the script on CGI.pm: .PP .Vb 4 \& ... \& 3162: Problem:\*(Aq$CGI::OS\*(Aq local($CRLF) = "\e015\e012" if $CGI::OS eq \*(AqVMS\*(Aq; \& 3165: Problem:\*(AqfillBuffer\*(Aq $self\->fillBuffer($FILLUNIT); \& .... .Ve .SH "DIFFERENCES FROM CGI.pm" .IX Header "DIFFERENCES FROM CGI.pm" CGI::Simple is strict and warnings compliant. .PP There are 4 modules in this distribution: .PP .Vb 4 \& CGI/Simple.pm supplies all the core code. \& CGI/Simple/Cookie.pm supplies the cookie handling functions. \& CGI/Simple/Util.pm supplies a variety of utility functions \& CGI/Simple/Standard.pm supplies a functional interface for Simple.pm .Ve .PP Simple.pm is the core module that provide all the essential functionality. Cookie.pm is a shortened rehash of the CGI.pm module of the same name which supplies the required cookie functionality. Util.pm has been recoded to use an internal object for data storage and supplies rarely needed non core functions and/or functions needed for the HTML side of things. Standard.pm is a wrapper module that supplies a complete functional interface to the OO back end supplied by CGI::Simple. .PP Although a serious attempt has been made to keep the interface identical, some minor changes and tweaks have been made. They will likely be insignificant to most users but here are the gory details. .SS "Globals Variables" .IX Subsection "Globals Variables" The list of global variables has been pruned by 75%. Here is the complete list of the global variables used: .PP .Vb 10 \& $VERSION = "0.01"; \& # set this to 1 to use CGI.pm default global settings \& $USE_CGI_PM_DEFAULTS = 0 unless defined $USE_CGI_PM_DEFAULTS; \& # see if user wants old CGI.pm defaults \& do{ _use_cgi_pm_global_settings(); return } if $USE_CGI_PM_DEFAULTS; \& # no file uploads by default, set to 0 to enable uploads \& $DISABLE_UPLOADS = 1 unless defined $DISABLE_UPLOADS; \& # use a post max of 100K, set to \-1 for no limits \& $POST_MAX = 102_400 unless defined $POST_MAX; \& # do not include undefined params parsed from query string \& $NO_UNDEF_PARAMS = 0 unless defined $NO_UNDEF_PARAMS; \& # separate the name=value pairs with ; rather than & \& $USE_PARAM_SEMICOLONS = 0 unless defined $USE_PARAM_SEMICOLONS; \& # only print headers once \& $HEADERS_ONCE = 0 unless defined $HEADERS_ONCE; \& # Set this to 1 to enable NPH scripts \& $NPH = 0 unless defined $NPH; \& # 0 => no debug, 1 => from @ARGV, 2 => from STDIN \& $DEBUG = 0 unless defined $DEBUG; \& # filter out null bytes in param \- value pairs \& $NO_NULL = 1 unless defined $NO_NULL; \& # set behavior when cgi_err() called \-1 => silent, 0 => carp, 1 => croak \& $FATAL = \-1 unless defined $FATAL; .Ve .PP Four of the default values of the old CGI.pm variables have been changed. Unlike CGI.pm which by default allows unlimited POST data and file uploads by default CGI::Simple limits POST data size to 100kB and denies file uploads by default. \f(CW$USE_PARAM_SEMICOLONS\fR is set to 0 by default so we use (old style) & rather than ; as the pair separator for query strings. Debugging is disabled by default. .PP There are three new global variables. If \f(CW$NO_NULL\fR is true (the default) then CGI::Simple will strip null bytes out of names, values and keywords. Null bytes can do interesting things to C based code like Perl. Uploaded files are not touched. \f(CW$FATAL\fR controls the behavior when \fBcgi_error()\fR is called. The default value of \-1 makes errors silent. \f(CW$USE_CGI_PM_DEFAULTS\fR reverts the defaults to the CGI.pm standard values ie unlimited file uploads via POST for DNS attacks. You can also get the defaults back by using the '\-default' pragma in the use: .PP .Vb 2 \& use CGI::Simple qw(\-default); \& use CGI::Simple::Standard qw(\-default); .Ve .PP The values of the global variables are stored in the CGI::Simple object and can be referenced and changed using the \fBglobals()\fR method like this: .PP .Vb 2 \& my $value = $q\->globals( \*(AqVARNAME\*(Aq ); # get \& $q\->globals( \*(AqVARNAME\*(Aq, \*(Aqsome value\*(Aq ); # set .Ve .PP As with many CGI.pm methods if you pass the optional value that will be set. .PP The \f(CW$CGI::Simple::VARNAME\fR = 'N' syntax is only useful prior to calling the \&\fBnew()\fR constructor. After that all reference is to the values stored in the CGI::Simple object so you must change these using the \fBglobals()\fR method. .PP \&\f(CW$DISABLE_UPLOADS\fR and \f(CW$POST_MAX\fR *must* be set prior to calling the constructor if you want the changes to have any effect as they control behavior during initialization. This is the same a CGI.pm although some people seem to miss this rather important point and set these after calling the constructor which does nothing. .PP The following globals are no longer relevant and have all been deleted: .PP .Vb 10 \& $AUTOLOADED_ROUTINES \& $AUTOLOAD_DEBUG \& $BEEN_THERE \& $CRLF \& $DEFAULT_DTD \& $EBCDIC \& $FH \& $FILLUNIT \& $IIS \& $IN \& $INITIAL_FILLUNIT \& $JSCRIPT \& $MAC \& $MAXTRIES \& $MOD_PERL \& $NOSTICKY \& $OS \& $PERLEX \& $PRIVATE_TEMPFILES \& $Q \& $QUERY_CHARSET \& $QUERY_PARAM \& $SCRATCH \& $SL \& $SPIN_LOOP_MAX \& $TIMEOUT \& $TMPDIRECTORY \& $XHTML \& %EXPORT \& %EXPORT_OK \& %EXPORT_TAGS \& %OVERLOAD \& %QUERY_FIELDNAMES \& %SUBS \& @QUERY_PARAM \& @TEMP .Ve .PP Notes: CGI::Simple uses IO::File\->new_tmpfile to get tempfile filehandles. These are private by default so \f(CW$PRIVATE_TEMPFILES\fR is no longer required nor is \f(CW$TMPDIRECTORY\fR. The value that were stored in \f(CW$OS\fR, \f(CW$CRLF\fR, \f(CW$QUERY_CHARSET\fR and \f(CW$EBCDIC\fR are now stored in the CGI::Simple::Util object where they find most of their use. The \f(CW$MOD_PERL\fR and \f(CW$PERLEX\fR values are now stored in our CGI::Simple object. \f(CW$IIS\fR was only used once in \fBpath_info()\fR. \f(CW$SL\fR the system specific / \e : path delimiter is not required as we let IO::File handle our tempfile requirements. The rest of the globals are HTML related, export related, hand rolled autoload related or serve obscure purposes in CGI.pm .SS "Changes to pragmas" .IX Subsection "Changes to pragmas" There are some new pragmas available. See the pragmas section for details. The following CGI.pm pragmas are not available: .PP .Vb 5 \& \-any \& \-compile \& \-nosticky \& \-no_xhtml \& \-private_tempfiles .Ve .SS Filehandles .IX Subsection "Filehandles" Unlike CGI.pm which tries to accept all filehandle like objects only \e*FH and \f(CW$fh\fR are accepted by CGI::Simple as file accessors for \fBnew()\fR and \fBsave()\fR. IO::File objects work fine. .SS "Hash interface" .IX Subsection "Hash interface" .Vb 2 \& %hash = $q\->Vars(); # pack values with "\e0"; \& %hash = $q\->Vars(","); # comma separate values .Ve .PP You may optionally pass \fBVars()\fR a string that will be used to separate multiple values when they are packed into the single hash value. If no value is supplied the default "\e0" (null byte) will be used. Null bytes are dangerous things for C based code (ie Perl). .SS cgi\-lib.pl .IX Subsection "cgi-lib.pl" All the cgi\-lib.pl 2.18 routines are supported. Unlike CGI.pm all the subroutines from cgi\-lib.pl are included. They have been GOLFED down to 25 lines but they all work pretty much the same as the originals. .SH "CGI::Simple COMPLETE METHOD LIST" .IX Header "CGI::Simple COMPLETE METHOD LIST" Here is a complete list of all the CGI::Simple methods. .SS "Guts (hands off, except of course for new)" .IX Subsection "Guts (hands off, except of course for new)" .Vb 10 \& _initialize_globals \& _use_cgi_pm_global_settings \& _store_globals \& import \& _reset_globals \& new \& _initialize \& _read_parse \& _parse_params \& _add_param \& _parse_keywordlist \& _parse_multipart \& _save_tmpfile \& _read_data .Ve .SS "Core Methods" .IX Subsection "Core Methods" .Vb 10 \& param \& add_param \& param_fetch \& url_param \& keywords \& Vars \& append \& delete \& Delete \& delete_all \& Delete_all \& upload \& upload_info \& query_string \& parse_query_string \& parse_keywordlist .Ve .SS "Save and Restore from File Methods" .IX Subsection "Save and Restore from File Methods" .Vb 3 \& _init_from_file \& save \& save_parameters .Ve .SS "Miscellaneous Methods" .IX Subsection "Miscellaneous Methods" .Vb 6 \& url_decode \& url_encode \& escapeHTML \& unescapeHTML \& put \& print .Ve .SS "Cookie Methods" .IX Subsection "Cookie Methods" .Vb 2 \& cookie \& raw_cookie .Ve .SS "Header Methods" .IX Subsection "Header Methods" .Vb 4 \& header \& cache \& no_cache \& redirect .Ve .SS "Server Push Methods" .IX Subsection "Server Push Methods" .Vb 4 \& multipart_init \& multipart_start \& multipart_end \& multipart_final .Ve .SS "Debugging Methods" .IX Subsection "Debugging Methods" .Vb 4 \& read_from_cmdline \& Dump \& as_string \& cgi_error .Ve .SS "cgi\-lib.pl Compatibility Routines \- all 2.18 functions available" .IX Subsection "cgi-lib.pl Compatibility Routines - all 2.18 functions available" .Vb 10 \& _shift_if_ref \& ReadParse \& SplitParam \& MethGet \& MethPost \& MyBaseUrl \& MyURL \& MyFullUrl \& PrintHeader \& HtmlTop \& HtmlBot \& PrintVariables \& PrintEnv \& CgiDie \& CgiError .Ve .SS "Accessor Methods" .IX Subsection "Accessor Methods" .Vb 10 \& version \& nph \& all_parameters \& charset \& crlf # new, returns OS specific CRLF sequence \& globals # get/set global variables \& auth_type \& content_length \& content_type \& document_root \& gateway_interface \& path_translated \& referer \& remote_addr \& remote_host \& remote_ident \& remote_user \& request_method \& script_name \& server_name \& server_port \& server_protocol \& server_software \& user_name \& user_agent \& virtual_host \& path_info \& Accept \& accept \& http \& https \& protocol \& url \& self_url \& state .Ve .SH "NEW METHODS IN CGI::Simple" .IX Header "NEW METHODS IN CGI::Simple" There are a few new methods in CGI::Simple as listed below. The highlights are the \fBparse_query_string()\fR method to add the QUERY_STRING data to your object if the method was POST. The \fBno_cache()\fR method adds an expires now directive and the Pragma: no-cache directive to the header to encourage some browsers to do the right thing. \fBPrintEnv()\fR from the cgi\-lib.pl routines will dump an HTML friendly list of the \f(CW%ENV\fR and makes a handy addition to \fBDump()\fR for use in debugging. The upload method now accepts a filepath as an optional second argument as shown in the synopsis. If this is supplied the uploaded file will be written to there automagically. .SS "Internal Routines" .IX Subsection "Internal Routines" .Vb 12 \& _initialize_globals() \& _use_cgi_pm_global_settings() \& _store_globals() \& _initialize() \& _init_from_file() \& _read_parse() \& _parse_params() \& _add_param() \& _parse_keywordlist() \& _parse_multipart() \& _save_tmpfile() \& _read_data() .Ve .SS "New Public Methods" .IX Subsection "New Public Methods" .Vb 7 \& add_param() # adds a param/value(s) pair +/\- overwrite \& upload_info() # uploaded files MIME type and size \& url_decode() # decode s url encoded string \& url_encode() # url encode a string \& parse_query_string() # add QUERY_STRING data to $q object if \*(AqPOST\*(Aq \& no_cache() # add both the Pragma: no\-cache \& # and Expires/Date => \*(Aqnow\*(Aq to header .Ve .SS "cgi\-lib.pl methods added for completeness" .IX Subsection "cgi-lib.pl methods added for completeness" .Vb 8 \& _shift_if_ref() # internal hack reminiscent of self_or_default :\-) \& MyBaseUrl() \& MyURL() \& MyFullUrl() \& PrintVariables() \& PrintEnv() \& CgiDie() \& CgiError() .Ve .SS "New Accessors" .IX Subsection "New Accessors" .Vb 5 \& crlf() # returns CRLF sequence \& globals() # global vars now stored in $q object \- get/set \& content_length() # returns $ENV{\*(AqCONTENT_LENGTH\*(Aq} \& document_root() # returns $ENV{\*(AqDOCUMENT_ROOT\*(Aq} \& gateway_interface() # returns $ENV{\*(AqGATEWAY_INTERFACE\*(Aq} .Ve .SH "METHODS IN CGI.pm NOT IN CGI::Simple" .IX Header "METHODS IN CGI.pm NOT IN CGI::Simple" Here is a complete list of what is not included in CGI::Simple. Basically all the HTML related stuff plus large redundant chunks of the guts. The check.pl script in the /misc dir will check to see if a script is using any of these. .SS "Guts \- rearranged, recoded, renamed and hacked out of existence" .IX Subsection "Guts - rearranged, recoded, renamed and hacked out of existence" .Vb 10 \& initialize_globals() \& compile() \& expand_tags() \& self_or_default() \& self_or_CGI() \& init() \& to_filehandle() \& save_request() \& parse_params() \& add_parameter() \& binmode() \& _make_tag_func() \& AUTOLOAD() \& _compile() \& _setup_symbols() \& new_MultipartBuffer() \& read_from_client() \& import_names() # I dislike this and left it out, so shoot me. .Ve .SS "HTML Related" .IX Subsection "HTML Related" .Vb 10 \& autoEscape() \& URL_ENCODED() \& MULTIPART() \& SERVER_PUSH() \& start_html() \& _style() \& _script() \& end_html() \& isindex() \& startform() \& start_form() \& end_multipart_form() \& start_multipart_form() \& endform() \& end_form() \& _textfield() \& textfield() \& filefield() \& password_field() \& textarea() \& button() \& submit() \& reset() \& defaults() \& comment() \& checkbox() \& checkbox_group() \& _tableize() \& radio_group() \& popup_menu() \& scrolling_list() \& hidden() \& image_button() \& nosticky() \& default_dtd() .Ve .SS "Upload Related" .IX Subsection "Upload Related" CGI::Simple uses anonymous tempfiles supplied by IO::File to spool uploaded files to. .PP .Vb 3 \& private_tempfiles() # automatic in CGI::Simple \& tmpFileName() # all upload files are anonymous \& uploadInfo() # relied on FH access, replaced with upload_info() .Ve .SS "Really Private Subs (marked as so)" .IX Subsection "Really Private Subs (marked as so)" .Vb 7 \& previous_or_default() \& register_parameter() \& get_fields() \& _set_values_and_labels() \& _compile_all() \& asString() \& compare() .Ve .SS "Internal Multipart Parsing Routines" .IX Subsection "Internal Multipart Parsing Routines" .Vb 6 \& read_multipart() \& readHeader() \& readBody() \& read() \& fillBuffer() \& eof() .Ve .SH EXPORT .IX Header "EXPORT" Nothing. .SH "AUTHOR INFORMATION" .IX Header "AUTHOR INFORMATION" Originally copyright 2001 Dr James Freeman This release by Andy Armstrong .PP This package is free software and is provided "as is" without express or implied warranty. It may be used, redistributed and/or modified under the terms of the Perl Artistic License (see http://www.perl.com/perl/misc/Artistic.html) .PP Address bug reports and comments to: andy@hexten.net. When sending bug reports, please provide the version of CGI::Simple, the version of Perl, the name and version of your Web server, and the name and version of the operating system you are using. If the problem is even remotely browser dependent, please provide information about the affected browsers as well. .PP Address bug reports and comments to: andy@hexten.net .SH CREDITS .IX Header "CREDITS" Lincoln D. Stein (lstein@cshl.org) and everyone else who worked on the original CGI.pm upon which this module is heavily based .PP Brandon Black for some heavy duty testing and bug fixes .PP John D Robinson and Jeroen Latour for helping solve some interesting test failures as well as Perlmonks: tommyw, grinder, Jaap, vek, erasei, jlongino and strider_corinth .PP Thanks for patches to: .PP Ewan Edwards, Joshua N Pritikin, Mike Barry, Michael Nachbaur, Chris Williams, Mark Stosberg, Krasimir Berov, Yamada Masahiro .SH "LICENCE AND COPYRIGHT" .IX Header "LICENCE AND COPYRIGHT" Copyright (c) 2007, Andy Armstrong \f(CW\*(C` \*(C'\fR. All rights reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBCGI\fR, CGI::Simple::Standard, CGI::Simple::Cookie, CGI::Simple::Util, CGI::Minimal