Perl CGI web-related module

This documentation

Table of contents of this page

Usage

use CGI qw/-pragma/; # -pragma can be any of the following:
-compile (indicated autoloaded methods will be compiled up front, rather than deferred to later.)
-no_debug or -debug
-private_tempfiles
my $query = new CGI;
Returns $ new CGI object containing parameters from the specified optional parameter: input file, file handle reference, hash, URL-escaped query string, previously existing CGI object, empty string, or empty hash.
result = $query->function ...;
where function is one of the functions listed below.
$error = $q->cgi_error;
When an error occurs, methods return an empty parameter list.
So, use this function to return error messages formatted as HTTP status codes.
Use error with header(-status=>$error);
$CGI::POST_MAX
Maximum number of bytes allowed in POSTings before exiting with an error message.
Limits the maximum size of file uploads.
$CGI::DISABLE_UPLOADS
If set to a non-zero value, this will disable file uploads completely.

use CGI::Carp (error reporting)

Replaces the standard functions that report fatal errors (die, croak, confess) and warnings (warn, carp, cluck) with ones that write out nicely time-stamped messages to the HTTP server error log.

The following functions are not exported by default. Placement in a BEGIN block is suggested.

carpout(filehandle);
To direct error messages other than to the default STDERR, the server's error log for most HTTPD servers.
filehandle is a reference to an open filehandle for writing errors.
use CGI::Carp qw(fatalsToBrowser);
To echo fatal (die, croak, confess) errors to the browser as well as to the log.
set_message($message or \&subroutine);
Changes the default message that follows the error message, or replace both with your own code which will be sent the error message.
warningsToBrowser(0|1);
make non-fatal errors appear as HTML comments.

Parameter Query Strings and URI

function returns parameters
param @ parameter names as a list none
@ or $: value(s) of parameter $parameter
sets the value for the parameter to an array of values [-name=>]$parameter, [-value[s]=>]@values
append adds value(s) to the parameter -name=>$parameter, -values=>@values
url_param parameters in URL created when a form specifies GET none
import_names for each parameter, creates a variable in the namespace $spacename
delete removes the parameter $parameter
delete_all clears the CGI object completely none
param_fetch an array reference to the parameter's values. [-name=>]$parameter
Vars parameters as a tied hash reference ($ context) or a hash (% context) none
save writes the current state of the form to the filehandle FILEHANDLE
self_url a URL for this script with all its state information intact none
query_string unprocessed query string none
url URL with protocol, host, path, and port fields as specified named arguments hash (see table below)
-oldstyle_urls separate name=value pairs with ampersands rather than semicolons none

url method's named arguments hash (use a true value, ex "-full=>1")

Key Parts of URL to return
-full all fields (default)
-relative relative path only
-absolute absolute path only
-path_info path information appended
-path
-query query string appended
-query_string
-base only protocol, host, and port

HTTP Header

function returns parameters
-nph or nph(1) produce a no-parsed header none
redirect redirect browser to URL [-uri=>]$uri, [-nph=>1]
header returns a header type, status (or hash below)

header()'s hash parameter keys, all optional

Key Description of value (scalar) Label
-type media type (default is 'text/html') Content-Type
-status status code and human-readable message (ex, '402 Payment required') Status
-nph no-parse-header? (0|1) ?
-expires absolute date/time or relative (now|{+|-}#{m|h|d|M|y}) interval Expires, Date
-cookie cookie info Set-Cookie
-charset character set (default is 'ISO-8859-1') (also sets charset() method) charset=
-anything anything (internal underscores will be turned into hyphens) same as key

HTML characteristics

Code Purpose Parameter
-no_xhtml don't use XHTML syntax none
use CGI::Pretty produce nicely formatted HTML code none
local($") character, if any, to put between elements none
charset get $charset or set the current character set [$charset]
escapeHTML get string with HTML format characters escaped unescaped string

HTML tags

comment(string);
Returns an HTML comment (<!-- string --<)
start_html
Returns an HTML header and opening <body> tag, below
end_html
Return end of HTML document: </body></html> tags
start_form and end_form functions
HTML form element, below
tagname
If you provide no arguments, you get a single tag.
If you provide one or more string arguments, they are concatenated together with spaces and placed between opening and closing tags.
If the first argument is an associative array reference, then the keys (with optional dashes as prefix) and values of the associative array become the HTML tag's attributes.
If you provide as an argument, a reference to a list, the tag will be distributed across each element of the list.
-any
Any method that the query object doesn't recognize will be interpreted as a new HTML tag.
Tr, Delete, Sub
Because of conflicts with built-in Perl functions, these functions begin with initial capital
use CGI '*tagname' 'start_tagname' 'end_tagname';
Recognize these tagnames as functions returning a tag of that tagname.
*tagname enables use of start_tagname and end_tagname functions.

Returns a canned HTML header and the opening body tag. All parameters are optional. The first three parameters listed here are the old-style positional parameters with any additional parameters included in the <body> tag. The recognized named parameters are as follows.

Key Value Tag Attribute
-title title title none
-author author's e-mail address link rev="made"
-base 'true' base none
-xbase uri base href
-target target frame for links link target
-dtd ? !DOCTYPE ?
-lang language code (default is 'en-US') HTML language
-meta reference to an associative array meta name, content
-style see below style see below
-head string, or array of strings any any
-script see below script see below
-noScript HTML when browser ignores scripts noscript none
-other hash array of attribute/value pairs body any

The cascading stylesheet key (-style) values may be:

The Link function begins with an initial capital because of conflict with a built-in Perl function.

The -script key's values may be:

HTML form element

$flag = autoEscape([$flag]);
Get or set the value of the autoescape flag. By default, all text and labels for form elements by form-generating functions is passed through a function called escapeHTML()
-override (alias -force) parameter
Forces the default value to be used, regardless of the previous value.
start_form()
Return a <FORM> tag
&CGI::URL_ENCODED
application/x-www-form-urlencoded
start_multipart_form()
&CGI::MULTIPART
multipart/form-data
endform()
Returns the closing </FORM> tag
-nosticky
Hidden fields .submit and .cgifields are not generated.
Select
"S" is uppercase to avoid conflict.

Topics not described here

Links to information on the Internet

[web] [home] [about] [contact] This page last changed April 30, 2002.