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

Reference Manual of the URL Encode and Decode Library

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

LAML Source file: lib/encode-decode.scm

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 color library to be loaded (not for coloring purpose, but in order to get access to the the function that convert hexadecimal numbers to decimal numbers). In case multipart-decode is used, also the collect-skip library is required.

This library is used by the accompanying CGI library.

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-vector encode-vector A vector which controls the working of encode-string and encode-a-list (and others).
extract-attributes (extract-attributes str-a-list) Decodes and extract the attributes from the string str-a-list 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 the string str-a-list 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.
See also Scheme source file encode-vector

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.
See also Scheme source file encode-string

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 
.
See also Scheme source file encode-a-list


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 the string str-a-list 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.
Parameters str-a-list The part a URL that follows the question mark.
See also Scheme source file string-decode
alias function extract-attributes

extract-attributes
Form (extract-attributes str-a-list)
Description Decodes and extract the attributes from the string str-a-list and return an association list. Just and alias of string-decode.
Parameters str-a-list The part a URL that follows the question mark.
See also Scheme source file extract-attributes
alias function 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 Scheme source file multipart-decode
accompanying function multipart-form
accompanying function file-upload
accompanying function file-upload
determination of file name on server upload-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).
See also Scheme source file upload-target-filename

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