11.24 www.cgi - CGI utility

Module: www.cgi

Provides a few basic functions useful to write a CGI script.

In order to write CGI script easily, you may want to use other modules, such as rfc.uri (See section 11.14 rfc.uri - URI parsing and construction), text.html-lite (See section 11.17 text.html-lite - Simple HTML document construction) and text.tree (See section 11.20 text.tree - Lazy text construction).

Note: it seems that there is no active formal specification for CGI. See http://w3c.org/CGI/ for more information.

Function: cgi-parse-parameters &keyword :query-string :merge-cookies

Parses query string and returns associative list of parameters. When a keyword argument query-string is given, it is used as a source query string. Otherwise, the function checks the environment variable REQUEST_METHOD and obtain the query string depending on the value (either from stdin or from the environment variable QUERY_STRING). If such an environment variable is not defined and the current input port is a terminal, the function prompts the user to type parameters; useful for interactive debugging.

When a true value is given to merge-cookies, the cookie values obtained from the environment variable HTTP_COOKIE are appended to the result.

Note that the query parameter may have multiple values, so cdr of each element in the result is a list, not an atom. If no value is given to the parameter, #t is placed as its value. See the following example:

(cgi-parse-parameters :query-string "foo=123&bar=%22%3f%3f%22&bar=zz&buzz") => (("foo" "123") ("bar "\"??\"" "zz") ("buzz #t))

Function: cgi-get-parameter name params &keyword :default :list :convert

A convenient function to obtain a value of the parameter name from parsed query string params, which is the value cgi-parse-parameters returns.

Unless true value is given to list, the returned value is a scalar value. If more than one value is associated to name, only the first value is returned. If list is true, the returned value is always a list, even name has only one value.

After the value is retrieved, you can apply a procedure to convert the string value to the appropriate type by giving a procedure to the convert argument. The procedure must take one string argument. If list is true, the convert procedure is applied to each values.

If no value is defined for name, a value given to the keyword argument default is returned; the default value of default is #f if list is false, or () otherwise.

Function: cgi-header &keyword content-type location cookies

Creates a text tree (See section 11.20 text.tree - Lazy text construction) for the HTTP header of the reply message. The most simple form is like this:

(tree->string (cgi-header)) => "Content-type: text/html\r\n\r\n"

You can specify alternative content-type by the keyword argument content-type. If you want to set cookies to the client, specify a list of cookie strings to the keyword argument cookies. You can use construct-cookie-string (See section 11.11 rfc.cookie - HTTP cookie handling) to build such a list of cookie strings.

The keyword argument location may be used to generate a Location: header to redirect the client to the specified URI.

Function: cgi-main proc &keyword on-error merge-cookies

A convenient wrapper function for CGI script. This function calls cgi-parse-parameters, then calls proc with the result of cgi-parse-parameters. The keyword argument merge-cookies is passed to cgi-parse-parameters.

proc has to return a tree of strings (See section 11.20 text.tree - Lazy text construction), including the HTTP header. cgi-main outputs the returned tree to the current output port by write-tree, then returns zero.

If an error is signalled in proc, it is caught and an HTML page reporting the error is generated. You can customize the error page by providing a procedure to the on-error keyword argument. The procedure takes an <exception> object (See section 6.16.3 Exception object), and has to return a tree of string for the error reporting HTML page, including an HTTP header.

The following example shows the parameters given to the CGI program.

#!/usr/local/bin/gosh (use text.html-lite) (use www.cgi) (define (main args) (cgi-main (lambda (params) `(,(cgi-header) ,(html-doctype) ,(html:html (html:head (html:title "Example")) (html:body (html:table :border 1 (html:tr (html:th "Name") (html:th "Value")) (map (lambda (p) (html:tr (html:td (html-escape-string (car p))) (html:td (html-escape-string (x->string (cdr p)))))) params)))) ))))