Generated: August 27, 2003, 22:48:00Copyright ©2003, Kurt NørmarkThe local LAML software home page

Reference Manual of the CGI library

Kurt Nørmark ©    normark@cs.auc.dk    Department of Computer Science    Aalborg University    Denmark    

Master index
Source file: lib/cgi.scm
LAML Version 21.00 (August 27, 2003, PP edition)

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.
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
outputThe text to be written to std output (a string) or the LAML AST to be linearized to standard output.


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.


writeln


Form
(writeln . args)

Description
Writes a newline on standard output


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.


 

2.   CGI INPUT FUNCTIONS.


read-std-input


Form
(read-std-input n)

Description
Read n chars from standard input and return as string.


length-of-std-input


Form
(length-of-std-input)

Description
Return the number of chars on standard 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).


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.


time-extend


Form
(time-extend a-list second-count)

Description
Extend the the a-list with date, time and second-cound fields (all strings).


 

3.   OTHER CGI FUNCTIONS.


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. Make and encode the keys and values in key-list and val-list, respectively. Returns a string.


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.


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


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.


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.


 

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.


Generated: August 27, 2003, 22:48:00
This documentation has been extracted automatically from the Scheme source file by means of the Schemedoc tool