CGI.pm Reference (Perl in a Nutshell, 2nd Edition)

accept

$query->accept(['content_type'])

Returns a list of media types that the browser accepts.

content_type: If specified, returns instead the browser's preference for the specified content type, between 0.0 and 1.0

append

$query->append(-name=>'name',-values=>'value')

Appends a value or list of values to the named parameter.

-name=>'name': The parameter to append.
-values=>'value': The value to append. Multiple values can be specified as a reference to an anonymous array.

auth_type

auth_type(  )

Returns the authorization method.

autoEscape

$query->autoEscape(undef)

Turns off autoescaping of form elements.

button

print $query->button('name','function')

Generates a JavaScript button.

name: The name of the button.
function: The function to execute when the button is clicked. Using named parameters, the syntax is:

print $query->button(-name=>'name', -value=>'label', -onClick=>"function");

-value=>'label'

The label to display for the button

checkbox

print $query->checkbox('name' [,'checked','value','label'])

Generates a single checkbox.

name: The name to assign the input to (required).
checked: Checkbox should be checked initially.
value: The value to return when checked (default is on).
label: The label to use for the checkbox (default is the name of the checkbox). Using named parameters, the syntax is:

print $query->checkbox(-name=>'name', -checked=>'checked', -value=>'value', -label=>'label', -onClick=>function);

-onClick=>function

Browser should execute function when the user clicks on any checkbox in the group

checkbox_group

print $query->checkbox_group('name', \@list [, selected,'true',\%labelhash ])

Generates a list of checkbox elements.

name: The name to assign the input to (required).
\@list: An array reference with the list items. You can also use an anonymous array reference.
selected: The menu item(s) to be initially selected (default is that nothing is selected). This can be a single value or a reference to an array of values.
'true': Insert newlines between the checkboxes.
\%labelhash: A hash reference listing labels for each list item. Default is the list text itself. See popup_menu for an example. Using named parameters, the syntax is:

print $query->checkbox_group(-name=>'name', -values=>\@list, -default=>selected, -linebreak=>'true', -labels=>\%labelhash, -columns=>n, -columnheader=>'string', -rows=>m, -rowheader=>'string', -onClick=>function);

-columns=>n

The number of columns to use.

-columnheader=>'string'

A header for the column.

-rows=m

The number of rows to use. If omitted, and -columns is specified, the rows will be calculated for you.

-rowheader=>'string'

A header for the row.

-onClick=>function

Browser should execute function when the user clicks on any checkbox in the group.

cookie

$cookie=$query->cookie('name')

Defines or retrieves a cookie. See also header.

name: Name of the cookie (required). Using named parameters, the syntax is:

$cookie = $query->cookie(-name=>'name', -value=>'value', -expires=>'expcode', -path=>'partial_url', -domain=>'domain_name', -secure=>1); print $query->header(-cookie=>$cookie);

-value=>'value'

A value to assign to the cookie. You can supply a scalar value, or a reference to an array or hash. If omitted, a cookie will be retrieved rather than defined.

-expires=>expcode

Specifies an expiration timestamp (such as +3d for three days). Values for expcode are:

ns

n seconds

nm

n minutes

nh

n hours

nd

n days

nM

n months

ny

n years

day_of_week, dd-MMM-YY hh:mm:ss GMT

At the specified time.

now

Expires immediately.

-path=>'partial_url'

The partial URL for which the cookie is valid. Default is the current URL.

-domain=>'domain_name'

The domain for which the cookie is valid.

-secure=>1

Use this cookie only for a secure session.

defaults

print $query->defaults('label')

Generates a button that resets the form to its defaults. See also reset.

'label': The label to use for the button. If omitted, the label is Defaults.

delete

$query->delete('parameter')

Deletes a parameter.

'parameter': The parameter to delete

delete_all

$query->delete_all(  )

Deletes the entire CGI object.

dump

print $query->dump([true])

Dumps all name/value pairs as an HTML list.

true: If specified, prints as plain text

header

print $query->header([content_type ,status ,headers])

Generates the HTTP header for the document.

content_type: The content type to return. Default is text/html.
status: The HTTP status code and description to return. Default is 200 OK.
headers: Additional headers to include, such as Content-Length: 123. Using named parameters, the syntax is:

print $query->header(-type=>'content_type', -nph=>1, -status=>'status_code', -expires=>'expcode', -cookie=>'cookie', -target=>'frame', -header=>'value');

-type=>content_type

Specifies the content type.

-nph=>1

Uses headers for a no-parse-header script.

-status=>status_code

Specifies the status code.

-expires=>expcode

Specifies an expiration timestamp (such as +3d for three days). Values for expcode are:

ns

n seconds

nm

n minutes

nh

n hours

nd

n days

nM

n months

ny

n years

day_of_week, dd-MMM-YY hh:mm:ss GMT

At the specified time

now

Expires immediately

-cookie=>cookie

Specifies a cookie. The cookie may be a scalar value or an array reference.

-header=>value

Specifies any HTTP header.

-target=>frame

Writes to specified frame.

hidden

print $query->hidden('name', 'value' [,'value'... ])

Generates a hidden text field.

name: The name to give the value (required).
value: The value to assign to name. Multiple values can be specified. Using named parameters, the syntax is:

print $query->hidden(-name=>'name', -default=>'value');

With named parameters, the value can also be represented as a reference to an array, such as:

print $query->hidden(-name=>'name', -default=>['value1', 'value2', ... ]);

image_button

print $query->image_button('name','url' [,'align'])

Generates a clickable image map.

name: The name to use. When clicked, the x,yposition is returned as name.xand name.y, respectively.
url: The URL of the image for the image map.
align: The alignment type. May be TOP, BOTTOM, or MIDDLE. Using named parameters, the syntax is:

print $query->image_button(-name=>'name', -src=>'url', -align=>'align', -onClick=>function);

-onClick=>function

Browser should execute function when the user clicks on the image

import_names

$query->import_names('package')

Creates variables in the specified package. Called import in older versions of CGI.pm.

package: The package to import names into

isindex

print $query->isindex([action])

Generates an <ISINDEX> tag.

action: The URL of the index script. Default is the current URL. Using named parameters, the syntax is:

print $query->isindex(-action=>$action);

nph

nph(1)

Treats a CGI script as a no-parsed-header (NPH) script.

param

@name = $query->param([parameter [newvalue1, newvalue2, ...] ])

Gets or sets parameter names.

@name: The array that will contain the parameter names.
parameter: An optional single parameter to fetch. When used with no arguments, param returns a list of all known parameter names.
newvalue1, newvalue2, ...: The optional new values to assign to the parameter. Using named parameters, the syntax is:

$query->param(-name=>'parameter', -value=>'newvalue');

or:

$query->param(-name=>'parameter', -values=>'newvalue1', 'newvalue2', ...);

password_field

print $query->password_field('name' [,'value',size,maxlength ])

Generates a password input field.

name: The name to assign the input to (required).
value: The default password to place in the password field.
size: The size of the password field (in characters).
maxlength: The maximum length of the password field (in characters). Using named parameters, the syntax is:

print $query->password_field(-name=>'name', -default=>'value', -size=>size, -maxlength=>maxlength, -override=>1, -onChange=>function, -onFocus=>function, -onBlur=>function, -onSelect=>function);

-override=>1

Text field should not inherit its value from a previous invocation of the script

-onChange=>function

Browser should execute function when the user changes the text field

-onFocus=>function

Browser should execute function when the focus is on the text field

-onBlur=>function

Browser should execute function when the focus leaves the text field

-onSelect=>function

Browser should execute function when the user changes a selected portion of the text field

path_info

path_info(  )

Returns extra path information.

path_translated

path_translated(  )

Returns translated extra path information.

popup_menu

print $query->popup_menu('name', \@array [,'selected', \%labelhash])

Generates a popup menu.

name: The name to assign the input to (required).
\@array: An array reference listing the menu items. You can also use an anonymous array reference (see example below).
selected: The menu item to be initially selected (default is first menu item or the item selected in previous queries).
\%labelhash: A hash reference listing labels for each menu item. Default is menu item text. For example:

%labels = ('UPS'=>'United Parcel Service (UPS)', 'FedExO'=>'Federal Express Overnight - 10AM delivery', 'FedExS'=>'Federal Express Standard - 2PM delivery', 'FedEx2'=>'Federal Express 2nd Day Delivery'); print $query->popup_menu('delivery_method', ['UPS', 'FedExO', 'FedExS', 'FedEx2'], 'FedExO', \%labels);

Using named parameters, the syntax is:

print $query->popup_menu(-name=>'name', -values=>\@array, -default=>'selected', -labels=>\%labelhash, -onChange=>function, -onFocus=>function, -onBlur=>function);

-onChange=>function

Browser should execute function when the user changes the text field

-onFocus=>function

Browser should execute function when the focus is on on the text field

-onBlur=>function

Browser should execute function when the focus leaves the text field

radio_group

print $query->radio_group('name', \@list [, selected, 'true', \%label ])

Generates a set of radio buttons.

name: The name to assign the input to (required).
\@list: An array reference with the list items. You can also use an anonymous array reference.
selected: The menu item to be initially selected.
'true': Inserts newlines between radio buttons.
\%label: A hash reference listing labels for each list item. Default is the list text itself. (See popup_menu for an example.) Using named parameters, the syntax is:

print $query->radio_group(-name=>'name', -values=>\@list, -default=>'selected', -linebreak=>'true', -labels=>\%labelhash, -columns=>n, -columnheader=>'string', -rows=>m, -rowheader=>'string');

-columns=>n

The number of columns to use.

-columnheader=>'string'

A header for the column.

-rows=m

The number of rows to use. If omitted, and -columns is specified, the rows will be calculated for you.

-rowheader=>'string'

A header for the row.

raw_cookie

raw_cookie(  )

Returns the value of the HTTP_COOKIE header.

ReadParse

ReadParse(  )

Creates a hash named %in containing query information. Used for backwards compatibility with the Perl4 cgi-lib.pl.

redirect

print $query->redirect('url')

Generates a header for redirecting the browser.

url: The absolute URL to redirect to. Using named parameters, the syntax is:

print $query->redirect(-uri=>'url', -nph=>1);

referer

referer(  )

Returns the referring URL.

remote_host

remote_host(  )

Returns the remote hostname or IP address, depending on the configuration of the server.

remote_user

remote_user(  )

Returns the username supplied for authorization.

request_method

request_method(  )

Returns the request method.

reset

print $query->reset

Generates a button that resets the form to its initial values. See also defaults.

save

$query->save(filehandle)

Saves the form to the specified filehandle, to be read back with the new constructor.

filehandle: The filehandle to save the file to

script_name

script_name(  )

Returns the current partial URL.

scrolling_list

print 
$query->scrolling_list('name',\@list[,selected,size,'true',\%labelhash]);

Generates a scrolling list.

name: The name to assign the input to (required).
\@list: An array reference with the list items. You can also use an anonymous array reference.
selected: The menu item(s) to be initially selected (default is that nothing is selected). This can be a single value or a reference to a list of values.
size: The number of elements to display in the list box.
'true': Allows multiple selections.
\%labelhash: A hash reference listing labels for each list item. Default is the list text itself. (See popup_menu for an example.) Using named parameters, the syntax is:

print $query->scrolling_list(-name=>'name', -values=>\@listarray, -default=>selected, -size=>size, -multiple=>'true', -labels=>\%labelhash, -onChange=>function, -onFocus=>function, -onBlur=>function);

-onChange=>function

Browser should execute function when the user changes the text field

-onFocus=>function

Browser should execute function when the focus is on on the text field

-onBlur=>function

Browser should execute function when the focus leaves the text field

self_url

$url = $query->self_url

Returns the URL of the current script with all its state information intact.

start_html

print $query->start_html(['title', 'email', 'base', attribute='value'])

Generates <HTML> and <BODY> tags.

title: The title of the page.
email: The author's email address.
base: Whether to use a <BASE> tag in the header.
attribute='value': Specifies an attribute to the <BODY> tag. Using named parameters, the syntax is:

print $query->start_html(-title=>'title', -author=>'email_address', -base=>'true', -xbase=>'url', -meta=>{'metatag1'=>'value1', 'metatag2'=> 'value2'}, -script=>'$script', -onLoad=>'$function', -onUnload=>'$function', -attribute=>'value');

-title=>'title'

Specifies the title of the page.

-author=>'email_address'

Specifies the author's email address.

-xbase=>'url'

Provides an HREF for the <BASE> tag. Default is the current location.

-meta=>{'metatag1'=>'value1', ... }

Adds arbitrary meta information to the header as a reference to a hash. Valid tags are:

keywords

Keywords for this document

copyright

Copyright for this document description

description

Description for this document

attribute=>'value'

Specifies an attribute to the <BODY> tag
-script=>'$script': Specifies a JavaScript script to be embedded within a <SCRIPT> block.
-onLoad=>'$function': Browser should execute specified function upon entering page.
-onUnload=>'$function': Browser should execute specified function upon leaving page.

startform

print $query->startform([method, action, encoding])

Generates a <FORM> tag.

method: The request method for the form. Values are:

POST

Use the POST method (default).

GET

Use the GET method.
action: The URL of the CGI script. Default is the current URL.
encoding: The encoding scheme. Possible values are application/x-www-form-urlencoded and multipart/form-data. Using named parameters, the syntax is:

print $query->startform(-method=>$method, -action=>$action, -encoding=>$encoding, -name=>$name, -target=>frame, -onSubmit=>function);

-name=>name

Names the form for identification by JavaScript functions

-target=>frame

Writes to the specified frame

-onSubmit=>function

A JavaScript function that the browser should execute upon submitting the form

start_multipart_form

print $query->start_multipart_form([method, action])

Generates <HTML> and <BODY> tags. Same as startform, but assumes multipart/form-data encoding as the default.

submit

print $query->submit([ 'label','value' ])

Generates a Submit button.

label: The label to use for the button.
value: The value to return when the form is submitted. Using named parameters, the syntax is:

print $query->submit(-name=>'name', -value=>'value', -onClick=>function);

-onClick=>function

Browser should execute function when the user clicks on the image

textarea

print $query->textarea('name' [,'value',rows,columns ])

Generates a large multiline text input box.

name: The name to assign the input to (required).
value: The initial value to place into the text input box.
rows: The number of rows to display.
columns: The number of columns to display. Using named parameters, the syntax is:

print $query->textarea(-name=>'name', -default=>'value', -rows=>rows, -columns=>columns, -override=>1, -onChange=>function, -onFocus=>function, -onBlur=>function, -onSelect=>function);

-override=>1

Text field should not inherit its value from a previous invocation of the script

-onChange=>function

Browser should execute function when the user changes the text field

-onFocus=>function

Browser should execute function when the focus is on the text field

-onBlur=>function

Browser should execute function when the focus leaves the text field

-onSelect=>function

Browser should execute function when the user changes a selected portion of the text field

textfield

print $query->textfield('name' [,'value', size, maxlength])

Generates a text input field.

name: The name to assign the input to (required).
value: The initial value to place in the text field.
size: The size of the text field (in characters).
maxlength: The maximum length of the text field (in characters). Using named parameters, the syntax is:

print $query->textfield(-name=>'name', -default=>'value', -size=>size, -maxlength=>maxlength, -override=>1, -onChange=>function, -onFocus=>function, -onBlur=>function, -onSelect=>function);

-override=>1

Text field should not inherit its value from a previous invocation of the script

-onChange=>function

Browser should execute function when the user changes the text field

-onFocus=>function

Browser should execute function when the focus is on the text field

-onBlur=>function

Browser should execute function when the focus leaves the text field

-onSelect=>function

Browser should execute function when the user changes a selected portion of the text field

url

$url = $query->url

Returns a URL of the current script without query information.

use_named_parameters

use_named_parameters(  )

Specifies that functions should take named parameters.

user_agent

$query->user_agent( [string] )

Returns the value of the HTTP_USER_AGENT header.

string: If specified, returns only headers matching the specified string

user_name

user_name(  )

Returns the remote user's login name; unreliable.

10.7. CGI.pm Reference