3.1 Initialization and Discovery

Procedure: cgi:init [opts…] ¶

(Re-)initialize internal data structures. This must be called before calling any other ‘cgi:foo’ procedure. For FastCGI, call this “inside the loop” (that is, for each CGI invocation).

opts are zero or more symbols that configure the module.

u8-qs

This causes parsing of query-string and form data posted with MIME type application/x-www-form-urlencoded to return an alist with u8vector keys and values.

uploads-lazy

This controls how uploaded files, as per cgi:uploads and cgi:upload, are represented.

move

This is like uploads-lazy but additionally affects all parameters in a form with MIME type multipart/form-data. If both uploads-lazy and move are specified, then move takes precedence.

move-simple-text/plain

This simplifies the value of form parameters with MIME type text/plain to a string, discarding other MIME information. It is only meaningful in conjunction with move.

cookies-split-on-semicolon

This causes cookies parsing to use #\; (semicolon), instead of the default #\, (comma), for splitting multiple cookies. This is necessary, for example, if the server is configured to provide “Netscape style” (i.e., old and deprecated) cookies.

Unrecognized options are ignored.

Procedure: cgi:form-data? ¶

Return #t iff there is form data available.

Procedure: cgi:names ¶

Return a list of variable names in the form. The order of the list is the same as that found in the form for the first occurance of each variable and each variable appears at most once. For example, if the form has variables ordered a b a c d b e, then the returned list would have order a b c d e.

Procedure: cgi:cookie-names ¶

Return a list of cookie names.

3.2 Data Transfer In

Procedure: cgi:getenv key ¶

Return the value of the environment variable associated with key, a symbol. Unless otherwise specified below, the return value is a (possibly massaged, possibly empty) string. The following keys are recognized:

server-software
server-software-type     ; part of server-software before "/"
server-software-version  ; part of server-software after "/"
server-name
server-hostname          ; alias for server-name
gateway-interface
server-protocol
server-protocol-name     ; part of server-protocol before "/"
server-protocol-version  ; part of server-protocol after "/"
server-port (integer)
request-method
path-info
path-translated
script-name
query-string
remote-host
remote-addr
auth-type
authentication-type      ; alias for auth-type
remote-user
remote-ident
content-type
content-length (integer, possibly 0)
http-accept (list, possibly empty, of strings)
http-accept-types        ; alias for http-accept-types
http-user-agent
http-cookie

Keys not listed above result in an "unrecognized key" error.

Procedure: cgi:values name ¶

Fetch any values associated with name found in the form data. Return a list, even if it contains only one element. A value is either a string, or #f. When there are multiple values, the order is the same as that found in the form.

Procedure: cgi:value name ¶

Fetch only the CAR from (cgi:values name). Convenient for when you are certain that name is associated with only one value.

Procedure: cgi:uploads name ¶

Return a list of file contents associated with name, or #f if no files are available.

If the move option is specified to cgi:init, each file contents element has the form:

(FILENAME MOVE LENGTH TYPE)

where filename is a string, length is an integer, type is a “MIME type form” [[[TODO: this is really a PITA to document piecemeal — might as well redirect the effort towards making (www mime-headers) public.]]], and move is either a sub-list (from a sub-multipart part), or, more typically the case a procedure that takes one arg to:

port

Send the part contents to port.

#t

Return a u8vector of the part contents.

#f

Discard the part contents and return #f.

NB: move-simple-text/plain does not apply to file contents, even for file with MIME type text/plain.

If move is not specified to cgi:init, read on.

Uploaded files are parsed by parse-form (see (www server-utils form-2-form)). If the uploads-lazy option is specified to cgi:init, then the file contents are those directly returned by form-2-form. If unspecified, the file contents are strings with the object property #:guile-www-cgi whose value is an alist with the following keys:

#:name

identical to name (sanity check)

#:filename

original/suggested filename for this bunch of bits

#:mime-type

something like "image/jpeg"

#:raw-mime-headers

the MIME headers before parsing

Note that the string’s object property and the keys are all keywords. The associated values are strings.

Unless uploads-lazy is specified (to cgi:init), cgi:uploads can only be called once per particular name. Subsequent calls return #f. Caller had better hang onto the information, lest the garbage man whisk it away for good. This is done to minimize the amount of time the file is resident in memory.

Procedure: cgi:upload name ¶

Fetch the first file associated with form var name. Can only be called once per name, so the caller had better be sure that there is only one file associated with name. Use cgi:uploads if you are unsure.

Procedure: cgi:cookies name ¶

Fetch any cookie values associated with name. Return a list of values in the order they were found in the HTTP header, which should be the order of most specific to least specific path associated with the cookie. If no cookies are associated with name, return #f.

Procedure: cgi:cookie name ¶

Fetch the first cookie value associated with name.

3.3 Uncollated Form Data

With cgi:values, when a name occurs more than once, its associated values are collated, thus losing information about the relative order of different and intermingled names. For this, you can use cgi:nv-pairs to access the uncollated (albeit ordered) form data.

Procedure: cgi:nv-pairs ¶

Fetch the list of (name . value), in the same order as found in the form data. A name may appear more than once. A value is either a string, or #f.