ncgi - Procedures to manipulate CGI values.
package require Tcl 8.2
package require ncgi ?1.3?
::ncgi::cookie cookie
::ncgi::decode str
::ncgi::empty name
::ncgi::exists name
::ncgi::encode string
::ncgi::header ?type? args
::ncgi::import cginame ?tclname?
::ncgi::importAll args
::ncgi::importFile cmd cginame
?filename?
::ncgi::input ?fakeinput? ?fakecookie?
::ncgi::multipart type query
::ncgi::nvlist
::ncgi::names
::ncgi::parse
::ncgi::parseMimeValue value
::ncgi::query
::ncgi::redirect url
::ncgi::reset query type
::ncgi::setCookie args
::ncgi::setDefaultValue key defvalue
::ncgi::setDefaultValueList key defvaluelist
::ncgi::setValue key value
::ncgi::setValueList key valuelist
::ncgi::type
::ncgi::urlStub ?url?
::ncgi::value key ?default?
::ncgi::valueList key ?default?
The ncgi package provides commands that manipulate CGI
values. These are values that come from Web forms and are processed either
by CGI scripts or web pages with embedded Tcl code. Use the ncgi
package to query these values, set and get cookies, and encode and decode
www-url-encoded values.
In the simplest case, a CGI script first calls
::ncgi::parse and then calls ::ncgi::value to get different
form values. If a CGI value is repeated, you should use
::ncgi::valueList to get back the complete list of values.
An alternative to ::ncgi::parse is ::ncgi::input,
which has semantics similar to Don Libes' cgi_input procedure.
::ncgi::input restricts repeated CGI values to have names that end
with "List". In this case, ::ncgi::value will return the
complete list of values, and ::ncgi::input will raise errors if it
find repeated form elements without the right name.
The ::ncgi::reset procedure can be used in test suites and
Web servers to initialize the source of the CGI values. Otherwise the values
are read in from the CGI environment.
The complete set of procedures is described below.
- ::ncgi::cookie cookie
- Return a list of values for cookie, if any. It is possible that
more than one cookie with the same name can be present, so this procedure
returns a list.
- ::ncgi::decode str
- Decode strings in www-url-encoding, which represents special characters
with a %xx sequence, where xx is the character code in hex.
- ::ncgi::empty name
- Returns 1 if the CGI variable name is not present or has the empty
string as its value.
- ::ncgi::exists name
- The return value is a boolean. It returns 0 if the CGI variable
name is not present, and 1 otherwise.
- ::ncgi::encode string
- Encode string into www-url-encoded format.
- ::ncgi::header ?type? args
- Output the CGI header to standard output. This emits a Content-Type:
header and additional headers based on args, which is a list of
header names and header values. The type defaults to
"text/html".
- ::ncgi::import cginame ?tclname?
- This creates a variable in the current scope with the value of the CGI
variable cginame. The name of the variable is tclname, or
cginame if tclname is empty (default).
- ::ncgi::importAll args
- This imports several CGI variables as Tcl variables. If args is
empty, then every CGI value is imported. Otherwise each CGI variable
listed in args is imported.
- ::ncgi::importFile cmd cginame ?filename?
- This provides information about an uploaded file from a form input field
of type file with name cginame. cmd can be one of
-server -client, -type or -data.
- -client
cginame
- returns the filename as sent by the client.
- -type
cginame
- returns the mime type of the uploaded file.
- -data
cginame
- returns the contents of the file.
- -server
cginame filename
- writes the file contents to a local temporary file (or filename if
supplied) and returns the name of the file. The caller is responsible for
deleting this file after use.
- ::ncgi::input ?fakeinput? ?fakecookie?
- This reads and decodes the CGI values from the environment. It restricts
repeated form values to have a trailing "List" in their name.
The CGI values are obtained later with the ::ncgi::value
procedure.
- ::ncgi::multipart type query
- This procedure parses a multipart/form-data query. This is used by
::ncgi::nvlist and not normally called directly. It returns an
alternating list of names and structured values. Each structure value is
in turn a list of two elements. The first element is meta-data from the
multipart/form-data structure. The second element is the form value. If
you use ::ncgi::value you just get the form value. If you use
::ncgi::valueList you get the structured value with meta data and
the value.
The type is the whole Content-Type, including the
parameters like boundary. This returns a list of names and values
that describe the multipart data. The values are a nested list structure
that has some descriptive information first, and the actual form value
second. The descriptive information is list of header names and values
that describe the content.
- ::ncgi::nvlist
- This returns all the query data as a name, value list. In the case of
multipart/form-data, the values are structured as described in
::ncgi::multipart.
- ::ncgi::names
- This returns all names found in the query data, as a list.
::ncgi::multipart.
- ::ncgi::parse
- This reads and decodes the CGI values from the environment. The CGI values
are obtained later with the ::ncgi::value procedure. IF a CGI value
is repeated, then you should use ::ncgi::valueList to get the
complete list of values.
- ::ncgi::parseMimeValue value
- This decodes the Content-Type and other MIME headers that have the form of
"primary value; param=val; p2=v2" It returns a list, where the
first element is the primary value, and the second element is a list of
parameter names and values.
- ::ncgi::query
- This returns the raw query data.
- ::ncgi::redirect url
- Generate a response that causes a 302 redirect by the Web server. The
url is the new URL that is the target of the redirect. The URL will
be qualified with the current server and current directory, if necessary,
to convert it into a full URL.
- ::ncgi::reset query type
- Set the query data and Content-Type for the current CGI session. This is
used by the test suite and by Web servers to initialize the ncgi module so
it does not try to read standard input or use environment variables to get
its data. If neither query or type are specified, then the
ncgi module will look in the standard CGI environment for its
data.
- ::ncgi::setCookie args
- Set a cookie value that will be returned as part of the reply. This must
be done before ::ncgi::header or ::ncgi::redirect is called
in order for the cookie to be returned properly. The args are a set
of flags and values:
- ::ncgi::setDefaultValue key defvalue
- Set a CGI value if it does not already exists. This affects future calls
to ::ncgi::value (but not future calls to ::ncgi::nvlist).
If the CGI value already is present, then this procedure has no side
effects.
- ::ncgi::setDefaultValueList key defvaluelist
- Like ::ncgi::setDefaultValue except that the value already has list
structure to represent multiple checkboxes or a multi-selection.
- ::ncgi::setValue key value
- Set a CGI value, overriding whatever was present in the CGI environment
already. This affects future calls to ::ncgi::value (but not future
calls to ::ncgi::nvlist).
- ::ncgi::setValueList key valuelist
- Like ::ncgi::setValue except that the value already has list
structure to represent multiple checkboxes or a multi-selection.
- ::ncgi::type
- Returns the Content-Type of the current CGI values.
- ::ncgi::urlStub ?url?
- Returns the current URL, but without the protocol, server, and port. If
url is specified, then it defines the URL for the current session.
That value will be returned by future calls to ::ncgi::urlStub
- ::ncgi::value key ?default?
- Return the CGI value identified by key. If the CGI value is not
present, then the default value is returned instead. This value
defaults to the empty string.
If the form value key is repeated, then there are two
cases: if ::ncgi::parse was called, then ::ncgi::value
only returns the first value associated with key. If
::ncgi::input was called, then ::ncgi::value returns a Tcl
list value and key must end in "List" (e.g.,
"skuList"). In the case of multipart/form-data, this procedure
just returns the value of the form element. If you want the meta-data
associated with each form value, then use ::ncgi::valueList.
- ::ncgi::valueList key ?default?
- Like ::ncgi::value, but this always returns a list of values (even
if there is only one value). In the case of multipart/form-data, this
procedure returns a list of two elements. The first element is meta-data
in the form of a parameter, value list. The second element is the form
value.
Uploading a file
HTML:
<html>
<form action="/cgi-bin/upload.cgi" method="POST" enctype="multipart/form-data">
Path: <input type="file" name="filedata"><br>
Name: <input type="text" name="filedesc"><br>
<input type="submit">
</form>
</html>
TCL: upload.cgi
#!/usr/local/bin/tclsh
::ncgi::parse
set filedata [::ncgi::value filedata]
set filedesc [::ncgi::value filedesc]
puts "<html> File uploaded at <a href=\"/images/$filedesc\">$filedesc</a> </html>"
set filename /www/images/$filedesc
set fh [open $filename w]
puts -nonewline $fh $filedata
close $fh
This document, and the package it describes, will undoubtedly
contain bugs and other problems. Please report such in the category
ncgi of the Tcllib SF Trackers
[http://sourceforge.net/tracker/?group_id=12883]. Please also report any
ideas for enhancements you may have for either package and/or
documentation.