Documention for: safe-cgi-data-read.r
Created by: sunanda
 on: 21-May-2006
Format: text/editable
Downloaded on: 16-Apr-2024

[numbering-on
[contents

[asis
    Author: Sunanda
   Version: 0.1
      date: 21-may-2006
asis]

[h2 Getting CGI data safely

[p 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.

[p There is an associated

[link/class/fsl http://www.rebol.org/cgi-bin/cgiwrap/rebol/art-display-article.r?article=x60w "article on this issue here."

[h2 Usage

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

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

[h2 Refinements

[h3 /template

[p Supplies an **object** with default field values, eg:

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

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

[h3 /no-trim

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

[p 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.

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

[h3 /keep-blocks

[p 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. 

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

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

[asis
   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"
      ] asis]

[h3 /refresh

[p 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.

[p 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.

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

[asis
   system/options/cgi/request-method: "GET"
   system/options/cgi/query-string: "a=123&b=456"
   safe-cgi-data-read/refresh
   do %other-cgi-program.r asis]

[p 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.

[p 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.

[p 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.

[p [date