Provided by: tcllib_1.19-dfsg-2_all bug

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.

       When proposing code changes, please provide unified diffs, i.e the output of diff -u.

       Note further that attachments are strongly preferred over inlined patches. Attachments can
       be  made  by going to the Edit form of the ticket immediately after its creation, and then
       using the left-most button in the secondary navigation bar.

SEE ALSO

       html

KEYWORDS

       CGI, cookie, form, html

CATEGORY

       CGI programming