Ubuntu Manpage: ncgi - Procedures to manipulate CGI values.

NAME

       ncgi - Procedures to manipulate CGI values.

SYNOPSIS

       package require Tcl  8.4

       package require ncgi  ?1.4.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?

_________________________________________________________________________________________________

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 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:

-name name

-value value

-expires date

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

EXAMPLES

       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

BUGS, IDEAS, FEEDBACK

       This  document,  and  the  package  it  describes, will undoubtedly contain bugs and other
       problems.   Please  report  such  in  the   category   ncgi   of   the   Tcllib   Trackers
       [http://core.tcl.tk/tcllib/reportlist].  Please also report any ideas for enhancements you
       may have for either package and/or documentation.

KEYWORDS

       CGI, cookie, form, html