cgi: Common Gateway Interface

This module implements the Common Gateway Interface (CGI). CGI scripts are called in response to HTTP requests by a web server. They can access the request parameters and HTTP headers, perform any computation and generate a reply in HTML or in any other data format supported by HTTP.

The Request class can be used for processing form parameters and other information related to the HTTP request. This module also includes a number of useful helper functions.

A CGI script writes to the standard output stream the following data:

  1. some HTTP headers (at least Content-Type), each on a separate line
  2. an empty line
  3. the response data, in the content type specified by the headers.

Here is a minimal CGI script:

def Main()
  WriteLn("Content-Type: text/plain")
  WriteLn()
  WriteLn("response data...")
end

Refer to the CGI specification (RFC 3875) for a detailed description of CGI.

The Request class

class Request()
Construct an object that holds form parameter information, file uploads, HTTP headers and other miscellaneous data related to a HTTP request.

Request objects support the Map interface and additional operations. Refer to the Map documentation for additional supported operations and methods.

Request operations

request[name]
Return the first value for the named form control. Raise IndexError if no such control is defined.

Request methods

hasKey(name)
Return a boolean indicating whether there are any values for the named form control.
valueList(name)
Return an array containing all the values for the named form control. The array may empty.
hasUpload(name)
Return a boolean indicating whether there is at least a single uploaded file for the named control.
uploadList(name)
Return a list of UploadInfo objects related to the named form control.
uploads()
Return an array of names of controls that have at least a single file upload associated with them.

Request constants

method
The method of the HTTP request. Valid values include "GET", "POST" and "HEAD".
contentType
The HTTP content type of a post request, or nil if undefined.
contentLength
The content length of a post request, in bytes, or nil if undefined.
pathInfo
Additional path information provided after the base URL of the CGI script, or nil if exactly the base URL was used.

For example, if the base URL for the script is http://host/script.cgi and the actual URL is http://host/script.cgi/path, pathInfo contains "/path".

userAgent
The value of the User-Agent request header.
remoteAddr
The IP address of the remote host as a string, or nil if it is undefined.
remoteHost
The hostname of the remote host as a string, or nil if it is undefined.

Functions

HtmlEncode(str)
Return the input string encoded as HTML. HTML special characters <, >, & and " are replaced with the corresponding character entities.
HtmlEncodeQuotes(str)
Return the input string encoded as HTML. Like HtmlEncode, but also replace the single quote ' with a character entity.
SetMaxPostSize(n)
Set the maximum post size (in bytes). Raise RuntimeError when constructing a Request object if the value of the Content-Length header is larger than this limit. Set the limit to -1 to enable an unlimited post size.

Note: The default maximum post size is 10 megabytes.

ParseQuery(query)
Parse an URL encoded query string into an array of key/value pairs. Example:
ParseQuery("foo=1&bar=x+y")   -- Result: ["foo" : "1", "bar" : "x y"]
DumpEnv()
Write the contents of all defined environment variables to standard output formatted in HTML. This can be useful when debugging CGI scripts.

The UploadInfo class

Instances of UploadInfo represent uploaded files and contain the the following constant members:

fileName
The original file name of the uploaded file, provided by the client.
contentType
The value of the Content-Type header for the uploaded file, or nil if undefined.
data
A narrow binary string containing the contents of the uploaded file.