CGI

CGI is a large class, providing several categories
of methods, many of which are mixed in from other modules. Some of the
documentation is in this class, some in the modules CGI::QueryExtension and CGI::HtmlExtension. See CGI::Cookie for specific information on handling
cookies, and cgi/session.rb (CGI::Session) for information on sessions.

The method params() returns a hash of all parameters in the request as
name/value-list pairs, where the value-list is an Array of one or more
values. The CGI object itself also behaves as a
hash of parameter names to values, but only returns a single value (as a
String) for each parameter name.

For instance, suppose the request contains the parameter
“favourite_colours” with the multiple values “blue” and “green”. The
following behaviour would occur:

If a request’s method is POST and its content type is multipart/form-data,
then it may contain uploaded files. These are stored by the QueryExtension module in the parameters
of the request. The parameter name is the name attribute of the file input
field, as usual. However, the value is not a string, but an IO object,
either an IOString for small files, or a Tempfile for larger ones. This
object also has the additional singleton methods:

The CGI class provides methods for sending header
and content output to the HTTP client, and mixes in methods for
programmatic HTML generation from CGI::HtmlExtension and CGI::TagMaker
modules. The precise version of HTML to use for HTML generation is
specified at object creation time.

The simplest way to send output to the HTTP client is using the out() method. This takes the HTTP headers
as a hash parameter, and the body content via a block. The headers can be
generated as a string using the header() method. The output stream can
be written directly to using the print() method.

Each HTML element has a corresponding method for generating that element as
a String. The name of this method is the same as that of the element, all
lowercase. The attributes of the element are passed in as a hash, and the
body as a no-argument block that evaluates to a String. The HTML
generation module knows which elements are always empty, and silently drops
any passed-in body. It also knows which elements require matching closing
tags and which don’t. However, it does not know what attributes are legal
for which elements.

There are also some additional HTML generation methods mixed in from the CGI::HtmlExtension module. These include
individual methods for the different types of form inputs, and methods for
elements that commonly take particular attributes where the attributes can
be directly specified as arguments, rather than via a hash.

Takes an element or elements or array of elements. Each element is
specified by the name of the element, without angle brackets. This matches
both the start and the end tag of that element. The attribute list of the
open tag will also be escaped (for instance, the double-quotes surrounding
attribute values).

type specifies which version of HTML to load the HTML
generation methods for. The following versions of HTML are supported:

html3

HTML 3.x

html4

HTML 4.0

html4Tr

HTML 4.0 Transitional

html4Fr

HTML 4.0 with Framesets

If not specified, no HTML generation methods will be loaded.

If the CGI object is not created in a standard CGI call environment (that is, it can’t locate
REQUEST_METHOD in its environment), then it will run in “offline” mode. In
this mode, it reads its parameters from the command line or (failing that)
from standard input. Otherwise, cookies and other parameters are parsed
automatically from the standard CGI locations, which
varies according to the REQUEST_METHOD.

Public Instance Methods

options can be a string specifying the Content-Type (defaults
to text/html), or a hash of header key/value pairs. The following header
keys are recognized:

type

the Content-Type header. Defaults to “text/html”

charset

the charset of the body, appended to the Content-Type header.

nph

a boolean value. If true, prepend protocol string and status code, and
date; and sets default values for “server” and “connection” if not
explicitly set.

status

the HTTP status code, returned as the Status header. See the list of
available status codes below.

server

the server software, returned as the Server header.

connection

the connection type, returned as the Connection header (for instance,
“close”.

length

the length of the content that will be sent, returned as the Content-Length
header.

language

the language of the content, returned as the Content-Language header.

expires

the time on which the current content expires, as a Time
object, returned as the Expires header.

cookie

a cookie or cookies, returned as one or more Set-Cookie headers. The value
can be the literal string of the cookie; a CGI::Cookie object; an Array of literal cookie
strings or Cookie objects; or a hash all of
whose values are literal cookie strings or Cookie objects. These cookies are in addition to
the cookies held in the @output_cookies field.