Generated: Monday, November 14, 2011, 09:16:23 Copyright © 2011 , Kurt NÝrmark The local LAML software home page

Reference Manual of the CGI library

Kurt NÝrmark © normark@cs.aau.dk Department of Computer Science, Aalborg University, Denmark.

LAML Source file: lib/cgi.scm

This is a collection of Scheme functions used for CGI programming purposes. We use the so-called POST method, according to which input to a CGI program is read from standard input.

The function extract-form-input reads the necessary amounts of input (as determined by the environment variable CONTENT_LENGT) and returns a Lisp association list.

The function extract-url-parameters returns and decodes the url parameters. The url parameters are the part of an URL found after the question mark. Using the CGI interface, these are passed via the environment variable QUERY_STRING. Like extract-form-input, the result of this function is also a Lisp association list.

The input functions (extract-form-input and extract-url-parameters) take a parameter, which is used for testing purposes in the situation where we are not connected to a WWW server. The global variable cgi-testing controls whether this parameter is used. The variable cgi-testing must be defined in the context of this library.

The function time-extend extends an association list with time and date information. This time stamping is quite useful when we extract data from an input form.

On the output side, the function write-page writes a page to standard output. If cgi-testing, the page is written to a local test-file.

The variable test-file must be defined in the context of this library.

The function make-url-parameters produces and encodes url paramters. This is used if we make an URL which passes parameters to another CGI program. The function make-url makes and returns an URL.

The CGI library depends on the accompanying URL encode and decode library.

There exists a simple tutorial CGI example in elucidative style.

Table of Contents:
1. CGI output functions. 3. Other CGI functions.
2. CGI input functions. 4. Multipart input.

Alphabetic index:
cgi-url-input (cgi-url-input . the-input) Return the url input (a string) also known as the query string.
cgi-write (cgi-write output) Write output (a text or a LAML AST) to standard output, or if cgi-testing, to test-file.
end (end) Ends and exit the CGI program.
extract-form-input (extract-form-input . testfile) Extract form input from std input, and return the decoded data as an association list.
extract-multipart-form-input (extract-multipart-form-input cur-time . testfile) Extract form input from std input, and return the decoded data as an association list.
extract-url-parameters (extract-url-parameters . the-input) Return a decoded URL input, as taken from the QUERY_STRING and decoded appropritely to an association list.
length-of-std-input (length-of-std-input) Return the number of chars on standard input
make-url (make-url url-prefix cgi-program key-list val-list) Return an URL from the parameters.
make-url-parameters (make-url-parameters key-list val-list) Make the last part of an url - the part after the question mark.
make-url-parameters-and-encode (make-url-parameters-and-encode key-list val-list) Make the last part of an url - the part after the question mark.
read-std-input (read-std-input n) Read n chars from standard input and return as string.
save-registrations (save-registrations a-list f g) A special purpose function which saves the a-list in two files f and g.
split-file-name (split-file-name filename) Return a list of the file name components separated by underscore.
time-extend (time-extend a-list second-count) Extend the the a-list with date, time and second-cound fields (all strings).
write-page (write-page title body . color-list) Writes an HTML page to standard output.
writeln (writeln . args) Writes a newline on standard output


1 CGI output functions.

cgi-write
Form (cgi-write output)
Description Write output (a text or a LAML AST) to standard output, or if cgi-testing, to test-file.
Parameters output The text to be written to std output (a string) or the LAML AST to be linearized to standard output.
See also Scheme source file cgi-write

write-page
Form (write-page title body . color-list)
Description Writes an HTML page to standard output. The page is described in terms of title, body, and an optional color-list. These three parameters are passed through the HTML function page. If cgi-testing is true, write the page to test-file (a global variable) instead of to standard output.
See also Scheme source file write-page

writeln
Form (writeln . args)
Description Writes a newline on standard output
See also Scheme source file writeln

end
Form (end)
Description Ends and exit the CGI program. Normally issued as the last command in a cgi program. When we are cgi-testing, this is the empty command.
See also Scheme source file end


2 CGI input functions.

read-std-input
Form (read-std-input n)
Description Read n chars from standard input and return as string.
See also Scheme source file read-std-input

length-of-std-input
Form (length-of-std-input)
Description Return the number of chars on standard input
See also Scheme source file length-of-std-input

cgi-url-input
Form (cgi-url-input . the-input)
Description Return the url input (a string) also known as the query string. This functions does not kind of decoding. If testing, a parameter is required; the parameter plays the role of the input source (an URL encoded string).
See also Scheme source file cgi-url-input

extract-form-input
Form (extract-form-input . testfile)
Description Extract form input from std input, and return the decoded data as an association list. Assumes that the input is application/x-www-form-urlencoded (which is the default encoding of an HTML form). The optional parameter must be supplied if testing. In that case input is taken from the file instead of std input. The file must contain an a-list.
See also Scheme source file extract-form-input

time-extend
Form (time-extend a-list second-count)
Description Extend the the a-list with date, time and second-cound fields (all strings).
See also Scheme source file time-extend


3 Other CGI functions.

make-url-parameters-and-encode
Form (make-url-parameters-and-encode key-list val-list)
Description Make the last part of an url - the part after the question mark. The partial url is made from a list of keys and a list of values. They are expected to be of the same length. Make and encode the keys and values in key-list and val-list, respectively. Returns a string. This is the original version used before August 23, 2011.
See also Scheme source file make-url-parameters-and-encode

make-url-parameters
Form (make-url-parameters key-list val-list)
Description Make the last part of an url - the part after the question mark. The partial url is made from a list of keys and a list of values. They are expected to be of the same length. A variant which does not URL encode keys and values. Returns a string. New as of August 23, 2011.
See also Scheme source file make-url-parameters

extract-url-parameters
Form (extract-url-parameters . the-input)
Description Return a decoded URL input, as taken from the QUERY_STRING and decoded appropritely to an association list. The optional parameter the-input is used in case of cgi-testing, namely as the encoded url parameter. If not testing, the function is called without parameters. In that case, the parameters are taken from an environment variable, QUERY_STRING.
See also Scheme source file extract-url-parameters

make-url
Form (make-url url-prefix cgi-program key-list val-list)
Description Return an URL from the parameters. The URL includes URL parameters (the part which follows the question mark). The two last parameters are passed into make-url-parameters after a question mark
See also Scheme source file make-url

save-registrations
Form (save-registrations a-list f g)
Description A special purpose function which saves the a-list in two files f and g. The a-list is the registered data. Save this structure in file f, appart from the contents field with key 'contributin' of a-list, which is to be saved in file g. No file deletion nor directory updating is done in this function.
See also Scheme source file save-registrations

split-file-name
Form (split-file-name filename)
Description Return a list of the file name components separated by underscore. This function is useful in case we save various kinds of transactions on a file whose name represents part of the file contents. The components of the file name is separated by the underscore character.
See also Scheme source file split-file-name


4 Multipart input.

extract-multipart-form-input
Form (extract-multipart-form-input cur-time . testfile)
Description Extract form input from std input, and return the decoded data as an association list. Assumes that the input is multipart/form-data, which is the encoding that provides for file uploading. The parameter cur-time is used as part of the file name of uploaded files - in order to ensure unique naming. The optional parameter must be supplied if testing. In that case input is taken from the file instead of std input. The file is assumed to contain the raw textual contents.
See also Scheme source file extract-multipart-form-input

Generated: Monday, November 14, 2011, 09:16:23
Generated by LAML SchemeDoc using LAML Version 38.0 (November 14, 2011, full)