The (www cgi)
module provides procedures to support painlessly
writing Common Gateway Interface scripts to process interactive forms.
These scripts typically follow the following steps: initialization and
discovery, data transfer in, data transfer out.
(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.
uploads-lazy
- This controls how uploaded files, as per
cgi:uploads
andcgi:upload
, are represented.Unrecognized options are ignored.
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 ordera b c d e
.
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-type
- server-software-version
- server-hostname
- gateway-interface
- server-protocol-name
- server-protocol-version
- server-port (integer)
- request-method
- path-info
- path-translated
- script-name
- query-string
- remote-host
- remote-addr
- authentication-type
- remote-user
- remote-ident
- content-type
- content-length (integer, possibly 0)
- http-accept-types (list, possibly empty, of strings)
- http-user-agent
- http-cookie
Keys not listed above result in an "unrecognized key" error.
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.
Fetch only the car from
(cgi:values
name)
. Convenient for when you are certain that name is associated with only one value.
Return a list of file contents associated with name, or
#f
if no files are available.Uploaded files are parsed by
parse-form
(see form-2-form). If theuploads-lazy
option is specified tocgi:init
, then the file contents are those directly returned byform-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 (tocgi: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.
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.
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
.
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.