ncgi(3tcl)

✨ NAME ✨

ncgi — bestie, these are the procedures that let you manipulate CGI values. That's the whole vibe. 💅

---

🎀 SYNOPSIS 🎀

package require Tcl 8.5 9

package require ncgi ?1.4.6?

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

Okay so the ncgi package hands you a whole toolkit of commands that manipulate CGI values. And what are CGI values, you ask? They're the values that show up from Web forms and get processed either by CGI scripts or by web pages with embedded Tcl code. That's it, that's the whole thing. You use the ncgi package to query those values, to set and get cookies, and to encode and decode www-url-encoded values. Iconic. 👑

In the most basic-basic case, a CGI script first calls ::ncgi::parse and then calls ::ncgi::value to grab the different form values. But listen — if a CGI value is repeated, you should use ::ncgi::valueList to get back the complete list of values. Don't skip that part, bestie. 🫶

There's also an alternative to ::ncgi::parse, and it's called ::ncgi::input. It has semantics that are similar to Don Libes' cgi_input procedure. Here's the tea though: ::ncgi::input restricts repeated CGI values to have names that end with "List". When that's the case, ::ncgi::value will return the complete list of values, and ::ncgi::input will raise errors if it finds repeated form elements without the right name. So like, it's picky and it's valid for being picky. 💅

And then there's ::ncgi::reset, which you can use in test suites and Web servers to initialize the source of the CGI values. Otherwise? The values just get read in from the CGI environment like normal. Periodt.

The complete set of procedures is described below. Sit down, get comfy, we're going through all of them. 🍓

---

🦋 ::ncgi::cookie cookie

Return a list of values for cookie, if any. It's possible that more than one cookie with the same name can be present, so this procedure returns a list. Yes, a list. Not a single value. Respect the multiplicity. 💖

🦋 ::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. So it un-garbles the garbled stuff. Slay. ✨

🦋 ::ncgi::empty name

Returns 1 if the CGI variable name is not present or has the empty string as its value. Otherwise, you know the drill. 🌸

🦋 ::ncgi::exists name

The return value is a boolean. It returns 0 if the CGI variable name is not present, and 1 otherwise. Simple. Clean. No notes. ✅

🦋 ::ncgi::encode string

Encode string into www-url-encoded format. The reverse-girlboss move of ::ncgi::decode. 🔥

🦋 ::ncgi::header ?type? args

Output the CGI header to standard output. This emits a Content-Type: header plus additional headers based on args, which is a list of header names and header values. The type defaults to "text/html". So if you don't specify, you get HTML vibes by default. 💅

🦋 ::ncgi::import cginame ?tclname?

This creates a variable in the current scope with the value of the CGI variable cginame. The name of that variable is tclname, or cginame if tclname is empty (which is the default). Cute, right? 🎀

🦋 ::ncgi::importAll args

This imports several CGI variables as Tcl variables. If args is empty, then every single CGI value is imported. Otherwise, each CGI variable listed in args is imported. Go big or go specific, your call. 🌈

🦋 ::ncgi::importFile cmd cginame ?filename?

This one gives you information about an uploaded file from a form input field of type file with name cginame. The cmd can be one of -server, -client, -type or -data. Let's break it down:

• -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 to filename if you supplied one) and returns the name of the file. The caller is responsible for deleting this file after use.

⚠️ Bestie, that last one is on you. The caller — that's you — is responsible for deleting the file after use. Don't leave temp files just lying around, it's not the vibe. 😭

🦋 ::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. Yep, "later" — it's a whole two-step situation. 🫶

🦋 ::ncgi::multipart type query

This procedure parses a multipart/form-data query. It's used by ::ncgi::nvlist and is not normally called directly — so like, you can, but the cool kids don't. It returns an alternating list of names and structured values. Each structured value is in turn a list of two elements:

1. The first element is meta-data from the multipart/form-data structure.
2. The second element is the form value.

So if you use ::ncgi::value, you just get the form value. But if you use ::ncgi::valueList, you get the structured value with meta data and the value. Choose your fighter. 💅

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 a list of header names and values that describe the content. Nested lists, nested lore. 🪆

🦋 ::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. That's the whole thing. ✨

🦋 ::ncgi::names

This returns all names found in the query data, as a list. ::ncgi::multipart.

💀 And yes, the original page literally just says ::ncgi::multipart. right there at the end of that sentence. No cap. That's it, that's the whole thing. I'm not making this up, I'm just the messenger. 🙈

🦋 ::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. You've heard this before, and you'll hear it again, because it's true. 🌸

🦋 ::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. So like, "text/html; charset=utf-8" walks in and two clean pieces walk out. 🧚

🦋 ::ncgi::query

This returns the raw query data. Raw. Unfiltered. The whole thing. 🔥

🦋 ::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. And here's the detail — the URL will be qualified with the current server and current directory, if necessary, to convert it into a full URL. So it fills in the blanks for you. Helpful queen behavior. 👑

🦋 ::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 nor type are specified, then the ncgi module will look in the standard CGI environment for its data. It's the "actually, I'll provide my own data thanks" button. 💅

🦋 ::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. Timing is everything, bestie, this is not a drill. ⏰

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 exist. 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. So it only fills the gap, it never stomps on what's already there. Gentle. 🫶

🦋 ::ncgi::setDefaultValueList key defvaluelist

Like ::ncgi::setDefaultValue, except that the value already has list structure to represent multiple checkboxes or a multi-selection. Because sometimes one value is not enough and you need the whole roster. 🎀

🦋 ::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). Main character energy: it walks in and takes over. 💅

🦋 ::ncgi::setValueList key valuelist

Like ::ncgi::setValue, except that the value already has list structure to represent multiple checkboxes or a multi-selection. Same energy, more entries. ✨

🦋 ::ncgi::type

Returns the Content-Type of the current CGI values. Short, sweet, factual. 💖

🦋 ::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. So it remembers. It's giving memory. 🧠✨

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

Now, if the form value key is repeated, 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. That's your girl for the extra info. 🦋

🦋 ::ncgi::valueList key ?default?

Like ::ncgi::value, but this always returns a list of values (even if there is only one value). Consistency, we love her. 💅

In the case of multipart/form-data, this procedure returns a list of two elements:

1. The first element is meta-data in the form of a parameter, value list.
2. The second element is the form value.

And that's where we're leaving it for now, because there's more coming. Don't go anywhere. 💖

✨ EXAMPLES ✨

ok bestie this is the part where it all comes together, like the montage scene in a movie but it's Tcl 🎬

---

💖 Uploading a file 💖

okay so picture this: somebody out there on the internet wants to send you a file. here's the HTML that does it, and here's the Tcl that catches it. iconic behavior, honestly 🫶

The form side of things — this is your <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>

and here's the Tcl side, the script living at 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

so like, you ::ncgi::parse, you grab filedata and filedesc with ::ncgi::value, you tell the world it's up, then you open /www/images/$filedesc, write $filedata into it with puts -nonewline, and close that file handle. done. slay. 💅

---

💀 BUGS, IDEAS, FEEDBACK 💀

ngl, this document and the package it describes are absolutely gonna have bugs and other problems in them. that's just how it is, no cap. please report them in the category ncgi of the Tcllib Trackers over at [http://core.tcl.tk/tcllib/reportlist]. and hey — if you have ideas for enhancements for either the package and/or the documentation, report those too. we wanna hear it, fr fr 🙈

when you're proposing code changes, please provide unified diffs, i.e. the output of diff -u.

also, heads up bestie: attachments are strongly preferred over inlined patches. to attach something, go to the Edit form of the ticket right after you create it, and then use the left-most button in the secondary navigation bar. iykyk 🌸

---

🦋 SEE ALSO 🦋

• html

---

👑 KEYWORDS 👑

CGI, cookie, form, html

---

🌈 CATEGORY 🌈

CGI programming

---

and that's the whole page, bestie 🎀 this one came from tcllib, version 1.4.6, and you're reading the ncgi(3tcl) manual page. go forth and CGI responsibly ✨💜🦋