Generated: April 2, 2002, 11:01:03Copyright ©2002, Kurt NørmarkThe local LAML software home page

Reference Manual of the Encode and Decode Library

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

Master index
Source file: lib/encode-decode.scm
LAML Version 17.00 (April 2, 2002) full

URLs are encoded in order to avoid special characters causing problems in an Internet adresss. This library provides functions to encode and decode parts of an URL. The main functions are encode-a-list and string-decode (also known as extract-attributes). The library also supports decoding of the multipart/form-data format, which can be used for file uploading. The main function in this area is multipart-decode. Encode-a-list takes an association list and encodes it to a string with '=' and '&' representation. string-decode (extract-attributes) takes a string, such as produced by encode-a-list, and returns an association list. Thus, each of the two functions are inverse version of the other function.

This library requires the general and the hex library to be loaded. In case multipart-decode is used, also the collect-skip library is required.

Table of Contents:
1. Encoding stuff.2. Decoding stuff.3. Multipart form decoding (file uploading).

Alphabetic index:
encode-a-list(encode-a-list a-list)Encode an a-list (both keys and values).
encode-string(encode-string str)Encode the string str, thus protecting a number of special characters.
encode-vectorencode-vectorA vector which controls the working of encode-string and encode-a-list (and others).
extract-attributesextract-attributesDecodes and extract the attributes from str and return an association list.
multipart-decode(multipart-decode cur-time)Return the association list of decoded keyword value pairs from a multipart encoded standard input.
string-decode(string-decode str-a-list)Decodes and extract the attributes from str and return an association list.
upload-target-filename(upload-target-filename proper-name extension cur-time)This function determines the proper name and extension of a downloaded file (no initial path information must be given) as represented in the server's file system.

 

1.   ENCODING STUFF.



encode-vector



Form
encode-vector

Description
A vector which controls the working of encode-string and encode-a-list (and others). The vector contains 128 entries. Entry n contains the encoding of character n. All % encodings must be strings of lenght exactly 3. Chars outside the range (chars between 128 and 255) are intended always to be encoded.


encode-string



Form
(encode-string str)

Description
Encode the string str, thus protecting a number of special characters. The encoding is controlled by the list encode-vector.


encode-a-list



Form
(encode-a-list a-list)

Description
Encode an a-list (both keys and values). Return a string in whichs the encoded keys and values are puted together as:
 key1 = val1 & key2 = val2 
.


 

2.   DECODING STUFF.
Because spaces and certain special characters may not appear in URLs, an encoding scheme is used when it is necessary to generate a URL that includes them: Each space is converted to a plus sign, and each special character is replaced by a triplet of characters consisting of a percent sign and two hexadecimal digits, which together identify the ASCII code for the character.


string-decode



Form
(string-decode str-a-list)

Description
Decodes and extract the attributes from str and return an association list. Assume that str-a-list is url encoded (application/x-www-form-urlencoded). In CGI programming, a query string consists of a sequence of equations separated by ampersands, with the name of some attribute on the left-hand side of each equation and the value of that attribute on the right-hand side. This function returns an association list from the string str-a-list, which represents an association list. In the string, the character '=' separates keys and values. Similarly, the character '&' separate key-value pairs. In addition, the '+' character represents a blank space.


extract-attributes



Form
extract-attributes

Description
Decodes and extract the attributes from str and return an association list. Just and alias of string-decode.


 

3.   MULTIPART FORM DECODING (FILE UPLOADING).
The main function in this part is multipart-decode, which is able to extract keyword value pairs, as done by string-decode. In addition, multipart-decode will save uploaded files in a particular directory on the server. The directory is given as a hidden field of the accompanying HTML form, called multipart-form.


multipart-decode



Form
(multipart-decode cur-time)

Description
Return the association list of decoded keyword value pairs from a multipart encoded standard input. As a side effect, write uploaded files into the servers file system. Information about the uploaded file is stored in a four-tuple (list of length 4) under a keyname corresponding to the parameter called name in the file-upload form. The four-tuple is (file-path-at-client file-path-at-server contents-type server-directory-url). file-path-at-client is the full file path of the file on the client. file-path-at-server is the full file path of the file on the server. The function upload-target-filename can be redefined in order to determine the exact name on the server. From file-path-at-server the file name proper on the server can easily be extracted. The constituent contents-type is the contents type, such as 'image/bmp'. Finally, server-directory-url is the URL prefix of the directory in which the uploaded files reside. This information is useful if you are going to link to the uploaded file. cur-time is the current time (an integer second count) used to unique naming of the target file in the servers file system together with initial path, which is passed in a hidden field.

See also
accompanying functionmultipart-form
accompanying functionfile-upload
accompanying functionfile-upload
determination of file name on serverupload-target-filename    


upload-target-filename



Form
(upload-target-filename proper-name extension cur-time)

Description
This function determines the proper name and extension of a downloaded file (no initial path information must be given) as represented in the server's file system. It is essential in most situations to ensure uniqueness of the file on the server. Therefore it is recommended that cur-time (the current time in seconds elapsed since January 1, 1970) is used in the file file. This function can be redefined if you want to define the upload target filename in a special way. The default is (string-append proper-name "-" cur-time "." extension), or if the extension is empty, (string-append proper-name "-" cur-time).


Generated: April 2, 2002, 11:01:03
This documentation has been extracted automatically from the Scheme source file by means of the Schemedoc tool