@head @module cgi @title 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 @ref{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: @example WriteLn("Content-Type: text/plain") WriteLn() WriteLn("response data...") @end

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

Class Request

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

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

Request operations

@op request[name] @optype{Request[Str] -> Str} @desc Return the first value for the named form control. Raise @ref{IndexError} if no such control is defined. @end

Request methods

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

Request constants

@var method as Str @desc The method of the HTTP request. Valid values include "GET", "POST" and "HEAD". @end @var contentType as Str @desc The HTTP content type of a post request, or nil if undefined. @end @var contentLength as Int @desc The content length of a post request, in bytes, or nil if undefined. @end @var pathInfo as Str @desc 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". @end @var userAgent as Str @desc The value of the User-Agent request header. @end @var remoteAddr as Str @desc The IP address of the remote host as a string, or nil if it is undefined. @end @var remoteHost as Str @desc The hostname of the remote host as a string, or nil if it is undefined. @end @end-class

Functions

@fun Html(str as Str) as Str @desc Return the input string encoded as HTML. HTML special characters <, >, & and " are replaced with the corresponding character entities. If the argument is nil, return nil. @end @fun HtmlQuot(str as Str) as Str @desc Return the input string encoded as HTML. Like Html, but also replace the single quote ' with a character entity. If the argument is nil, return nil. @end @fun SetMaxPostSize(n as Int) @desc Set the maximum post size (in bytes). Raise @ref{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. @end @end @fun ParseQuery(query as Str) as Array> @desc Parse an URL encoded query string into an array of key/value pairs. Example: @example ParseQuery("foo=1&bar=x+y") -- Result: ["foo" : "1", "bar" : "x y"] @end @end @fun DumpEnv() @desc Write the contents of all defined environment variables to standard output formatted in HTML. This can be useful when debugging CGI scripts. @end

Class UploadInfo

@class-hidden UploadInfo

Instances of UploadInfo represent uploaded files and contain the the following constant members: @var fileName as Str @desc The original file name of the uploaded file, provided by the client. @end @var contentType as Str @desc The value of the Content-Type header for the uploaded file, or nil if undefined. @end @var data as Str @desc A narrow binary string containing the contents of the uploaded file. @end