Script Library: 1238 scripts
  • Home
  • Script library
  • AltME Archive
  • Mailing list
  • Articles Index
  • Site search
View scriptLicenseDownload documentation as: HTML or editable
Download scriptHistoryOther scripts by: sunanda

Documentation for: safe-cgi-data-read.r

     Author: Sunanda
    Version: 0.1
       date: 21-may-2006

1. Getting CGI data safely

This Library function is designed to avoid all the limitations and gotchas associated with getting CGI input data. It will return the input data in a safe, and repeatable manner.

There is an associated article on this issue here. 

2. Usage

    do %safe-cgi-data-read.r
    my-cgi-object: safe-cgi-data-read 

my-cgi-object now contains an object with all the CGI input data keywords.

3. Refinements

3.1. /template

Supplies an object with default field values, eg:

    defaults: make object! [
         a: "yes"
         b: "99"
         c: none
    my-cgi-object: safe-cgi-data-read/template defaults 

a, b, and c will have those default values in my-cgi-object if they were not found in the CGI input data.

3.2. /no-trim

Do not remove excessive whitespace from CGI input fields. By default, we apply a trim/lines to each input field.

That is usually a good thing, especially if a user has entered the data on a form by cutting and pasting -- the field may contain leading and trailing spaces, tabs, or newline characters.

But, if you want the data as supplied -- perhaps multiple spaces are meaningful to you, use the /no-trim refinement.

3.3. /keep-blocks

A quirk of some versions of decode-cgi is that it will sometimes supply a block value instead of a string value. That usually happens if a keyword is repeated in a URL.

safe-cgi-data-read will, by default, concatenate the multiple values into a single string. Use /keep-blocks to stop it doing that.

Assuming the CGI input data is "a=12&b=34a=56":

    probe safe-cgi-data-read
    === make object! [
         a: "12 56"
         b: "34"

    probe safe-cgi-data-read/keep-blocks
    === make object! [
         a: ["12" "56"]
         b: "34"

3.4. /refresh

By default, safe-cgi-data-read caches its data. That means multiple calls to safe-cgi-data-read will return the same values, even if the CGI input data was supplied via POST.

There may be times when you do not want that. For example, one CGI program may decide that it has to pass control to another CGI program, and that other CGI program needs different CGI input data.

If that is your case, then the calling CGI program should have code along these lines:

    system/options/cgi/request-method: "GET"
    system/options/cgi/query-string: "a=123&b=456"
    do %other-cgi-program.r 

The first two lines fake the CGI method as GET, and replace whatever the original user-supplied CGI input data is with a new set of values.

The third line calls safe-cgi-data-read and tells it to disregard whatever data it previously stored. That will return a new object, but we can just discard it.

The fourth line calls our other CGI program. It will issue it's own safe-cgi-data-read, and be given the new values rather than the original user-supplied data.

Last updated: 21-May-2006