@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:
- some HTTP headers (at least Content-Type), each on a separate line
- an empty line
- 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