1ncgi(n) CGI Support ncgi(n)
2______________________________________________________________________________
6
8 ncgi - Procedures to manipulate CGI values.
9
11 package require Tcl 8.4
12 package require ncgi ?1.4.3?
14 ::ncgi::cookie cookie
16 ::ncgi::decode str
18 ::ncgi::empty name
20 ::ncgi::exists name
22 ::ncgi::encode string
24 ::ncgi::header ?type? args
26 ::ncgi::import cginame ?tclname?
28 ::ncgi::importAll args
30 ::ncgi::importFile cmd cginame ?filename?
32 ::ncgi::input ?fakeinput? ?fakecookie?
34 ::ncgi::multipart type query
36 ::ncgi::nvlist
38 ::ncgi::names
40 ::ncgi::parse
42 ::ncgi::parseMimeValue value
44 ::ncgi::query
46 ::ncgi::redirect url
48 ::ncgi::reset query type
50 ::ncgi::setCookie args
52 ::ncgi::setDefaultValue key defvalue
54 ::ncgi::setDefaultValueList key defvaluelist
56 ::ncgi::setValue key value
58 ::ncgi::setValueList key valuelist
60 ::ncgi::type
62 ::ncgi::urlStub ?url?
64 ::ncgi::value key ?default?
66 ::ncgi::valueList key ?default?
68______________________________________________________________________________
70
72 The ncgi package provides commands that manipulate CGI values. These
73 are values that come from Web forms and are processed either by CGI
74 scripts or web pages with embedded Tcl code. Use the ncgi package to
75 query these values, set and get cookies, and encode and decode www-url-
76 encoded values.
77 In the simplest case, a CGI script first calls ::ncgi::parse and then
79 calls ::ncgi::value to get different form values. If a CGI value is
80 repeated, you should use ::ncgi::valueList to get back the complete
81 list of values.
82 An alternative to ::ncgi::parse is ::ncgi::input, which has semantics
84 similar to Don Libes' cgi_input procedure. ::ncgi::input restricts
85 repeated CGI values to have names that end with "List". In this case,
86 ::ncgi::value will return the complete list of values, and
87 ::ncgi::input will raise errors if it find repeated form elements with‐
88 out the right name.
89 The ::ncgi::reset procedure can be used in test suites and Web servers
91 to initialize the source of the CGI values. Otherwise the values are
92 read in from the CGI environment.
93 The complete set of procedures is described below.
95 ::ncgi::cookie cookie
97 Return a list of values for cookie, if any. It is possible that
98 more than one cookie with the same name can be present, so this
99 procedure returns a list.
100 ::ncgi::decode str
102 Decode strings in www-url-encoding, which represents special
103 characters with a %xx sequence, where xx is the character code
104 in hex.
105 ::ncgi::empty name
107 Returns 1 if the CGI variable name is not present or has the
108 empty string as its value.
109 ::ncgi::exists name
111 The return value is a boolean. It returns 0 if the CGI variable
112 name is not present, and 1 otherwise.
113 ::ncgi::encode string
115 Encode string into www-url-encoded format.
116 ::ncgi::header ?type? args
118 Output the CGI header to standard output. This emits a Content-
119 Type: header and additional headers based on args, which is a
120 list of header names and header values. The type defaults to
121 "text/html".
122 ::ncgi::import cginame ?tclname?
124 This creates a variable in the current scope with the value of
125 the CGI variable cginame. The name of the variable is tclname,
126 or cginame if tclname is empty (default).
127 ::ncgi::importAll args
129 This imports several CGI variables as Tcl variables. If args is
130 empty, then every CGI value is imported. Otherwise each CGI
131 variable listed in args is imported.
132 ::ncgi::importFile cmd cginame ?filename?
134 This provides information about an uploaded file from a form
135 input field of type file with name cginame. cmd can be one of
136 -server -client, -type or -data.
137 -client cginame
139 returns the filename as sent by the client.
140 -type cginame
142 returns the mime type of the uploaded file.
143 -data cginame
145 returns the contents of the file.
146 -server cginame filename
148 writes the file contents to a local temporary file (or
149 filename if supplied) and returns the name of the file.
150 The caller is responsible for deleting this file after
151 use.
152 ::ncgi::input ?fakeinput? ?fakecookie?
154 This reads and decodes the CGI values from the environment. It
155 restricts repeated form values to have a trailing "List" in
156 their name. The CGI values are obtained later with the
157 ::ncgi::value procedure.
158 ::ncgi::multipart type query
160 This procedure parses a multipart/form-data query. This is used
161 by ::ncgi::nvlist and not normally called directly. It returns
162 an alternating list of names and structured values. Each struc‐
163 ture value is in turn a list of two elements. The first element
164 is meta-data from the multipart/form-data structure. The second
165 element is the form value. If you use ::ncgi::value you just
166 get the form value. If you use ::ncgi::valueList you get the
167 structured value with meta data and the value.
168 The type is the whole Content-Type, including the parameters
170 like boundary. This returns a list of names and values that
171 describe the multipart data. The values are a nested list
172 structure that has some descriptive information first, and the
173 actual form value second. The descriptive information is list
174 of header names and values that describe the content.
175 ::ncgi::nvlist
177 This returns all the query data as a name, value list. In the
178 case of multipart/form-data, the values are structured as
179 described in ::ncgi::multipart.
180 ::ncgi::names
182 This returns all names found in the query data, as a list.
183 ::ncgi::multipart.
184 ::ncgi::parse
186 This reads and decodes the CGI values from the environment. The
187 CGI values are obtained later with the ::ncgi::value procedure.
188 IF a CGI value is repeated, then you should use ::ncgi::val‐
189 ueList to get the complete list of values.
190 ::ncgi::parseMimeValue value
192 This decodes the Content-Type and other MIME headers that have
193 the form of "primary value; param=val; p2=v2" It returns a list,
194 where the first element is the primary value, and the second
195 element is a list of parameter names and values.
196 ::ncgi::query
198 This returns the raw query data.
199 ::ncgi::redirect url
201 Generate a response that causes a 302 redirect by the Web
202 server. The url is the new URL that is the target of the redi‐
203 rect. The URL will be qualified with the current server and
204 current directory, if necessary, to convert it into a full URL.
205 ::ncgi::reset query type
207 Set the query data and Content-Type for the current CGI session.
208 This is used by the test suite and by Web servers to initialize
209 the ncgi module so it does not try to read standard input or use
210 environment variables to get its data. If neither query or type
211 are specified, then the ncgi module will look in the standard
212 CGI environment for its data.
213 ::ncgi::setCookie args
215 Set a cookie value that will be returned as part of the reply.
216 This must be done before ::ncgi::header or ::ncgi::redirect is
217 called in order for the cookie to be returned properly. The
218 args are a set of flags and values:
219 -name name
221 -value value
223 -expires date
225 -path path restriction
227 -domain domain restriction
229 ::ncgi::setDefaultValue key defvalue
231 Set a CGI value if it does not already exists. This affects
232 future calls to ::ncgi::value (but not future calls to
233 ::ncgi::nvlist). If the CGI value already is present, then this
234 procedure has no side effects.
235 ::ncgi::setDefaultValueList key defvaluelist
237 Like ::ncgi::setDefaultValue except that the value already has
238 list structure to represent multiple checkboxes or a multi-
239 selection.
240 ::ncgi::setValue key value
242 Set a CGI value, overriding whatever was present in the CGI
243 environment already. This affects future calls to ::ncgi::value
244 (but not future calls to ::ncgi::nvlist).
245 ::ncgi::setValueList key valuelist
247 Like ::ncgi::setValue except that the value already has list
248 structure to represent multiple checkboxes or a multi-selection.
249 ::ncgi::type
251 Returns the Content-Type of the current CGI values.
252 ::ncgi::urlStub ?url?
254 Returns the current URL, but without the protocol, server, and
255 port. If url is specified, then it defines the URL for the cur‐
256 rent session. That value will be returned by future calls to
257 ::ncgi::urlStub
258 ::ncgi::value key ?default?
260 Return the CGI value identified by key. If the CGI value is not
261 present, then the default value is returned instead. This value
262 defaults to the empty string.
263 If the form value key is repeated, then there are two cases: if
265 ::ncgi::parse was called, then ::ncgi::value only returns the
266 first value associated with key. If ::ncgi::input was called,
267 then ::ncgi::value returns a Tcl list value and key must end in
268 "List" (e.g., "skuList"). In the case of multipart/form-data,
269 this procedure just returns the value of the form element. If
270 you want the meta-data associated with each form value, then use
271 ::ncgi::valueList.
272 ::ncgi::valueList key ?default?
274 Like ::ncgi::value, but this always returns a list of values
275 (even if there is only one value). In the case of multi‐
276 part/form-data, this procedure returns a list of two elements.
277 The first element is meta-data in the form of a parameter, value
278 list. The second element is the form value.
279
281 Uploading a file
282 HTML:
285 <html>
286 <form action="/cgi-bin/upload.cgi" method="POST" enctype="multipart/form-data">
287 Path: <input type="file" name="filedata"><br>
288 Name: <input type="text" name="filedesc"><br>
289 <input type="submit">
290 </form>
291 </html>
292 TCL: upload.cgi
294 #!/usr/local/bin/tclsh
295 ::ncgi::parse
297 set filedata [::ncgi::value filedata]
298 set filedesc [::ncgi::value filedesc]
299 puts "<html> File uploaded at <a href=\"/images/$filedesc\">$filedesc</a> </html>"
301 set filename /www/images/$filedesc
303 set fh [open $filename w]
305 puts -nonewline $fh $filedata
306 close $fh
307
310 This document, and the package it describes, will undoubtedly contain
311 bugs and other problems. Please report such in the category ncgi of
312 the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
313 also report any ideas for enhancements you may have for either package
314 and/or documentation.
315 When proposing code changes, please provide unified diffs, i.e the out‐
317 put of diff -u.
318 Note further that attachments are strongly preferred over inlined
320 patches. Attachments can be made by going to the Edit form of the
321 ticket immediately after its creation, and then using the left-most
322 button in the secondary navigation bar.
323
325 html
326
328 CGI, cookie, form, html
329
331 CGI programming
332tcllib 1.4.3 ncgi(n)