NAME
::ncgi - Procedures to manipulate CGI values.
SYNOPSIS
_________________________________________________________________
ncgi::cookie cookie
ncgi::decode str
ncgi::empty name
ncgi::encode string
ncgi::header {type text/html} args
ncgi::import cginame {tclname {}}
ncgi::importAll args
ncgi::input {fakeinput {}} {fakecookie {}}
ncgi::multipart type query
ncgi::nvlist
ncgi::parse
ncgi::parseMimeValue value
ncgi::query
ncgi::redirect url
ncgi::reset args
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 {}}
_________________________________________________________________
DESCRIPTION
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 repre
sents 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.
Encode string into www-url-encoded format.
ncgi::header {type text/html} 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.
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.
ncgi::importAll args
This imports several CGI variables as Tcl vari
ables. If args is empty, then every CGI vale is
imported. Otherwise each CGI variable listed in
args is imported.
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 val
ues are obtained later with the ncgi::value proce
dure.
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 ele
ment 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.
This returns all the query data as a name, value
list. In the case of multipart/form-data, the val
ues are structured as described in 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 head
ers 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 environ
ment 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:
-name name
-value value
-path path restriction
-domain domain restriction
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. 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,
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.
SEE ALSO
html
KEYWORDS
CGI, form, html, cookie
Man(1) output converted with
man2html