ncgi(n)

📦
version 2.0 · 2 versions
, in fedora 43, fedora 44, nixos 26.05, nixpkgs unstable

💖 ncgi(n) — CGI Support 💖

okay bestie, welcome to the manual page for ncgi, section n. This is part 1 of 2, so buckle up. ✨

🌸 NAME 🌸

ncgi — the queen of procedures to manipulate CGI values. periodt. 💅

✨ SYNOPSIS ✨

here's the lineup, no cap:

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 🦋

The <pink>ncgi</pink> package is literally serving 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. obsessed. 💖

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

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 finds 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. lowkey useful.

The complete set of procedures is described below. let's gooo. 💅

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. multiple cookies? it's giving polyamory but for cookies. 🍪

::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. decoding queen. ✨

::ncgi::empty name

Returns 1 if the CGI variable name is not present or has the empty string as its value. vibe check: empty? 1. 🙈

::ncgi::exists name

The return value is a boolean. It returns 0 if the CGI variable name is not present, and 1 otherwise. existence check, slay. 🔥

::ncgi::encode string

Encode string into www-url-encoded format. encode era. 💅

::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". header game strong. 👑

::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). import that. 🫶

::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. import all the things. 🌈

::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. file upload detective. 🕵️‍♀️

  • -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.
bestie, don't forget: the caller is responsible for deleting this file after use. it's giving messy. 🧹

::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. input era. 💜

::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. multipart magic. ✨

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. name-value list realness. 💅

::ncgi::names

This returns all names found in the query data, as a list. ::ncgi::multipart. (weird flex but ok. 👀)

::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. parse it bestie. 🌸

::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. mime decode queen. 👑

::ncgi::query

This returns the raw query data. raw and unfiltered. 🔥

::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. redirect era. 💫

::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. reset button energy. 🎀

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

cookie setting, but timing is everything. ⏰

::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. default value vibes. ✨

::ncgi::setDefaultValueList key defvaluelist

Like ::ncgi::setDefaultValue except that the value already has list structure to represent multiple checkboxes or a multi-selection. list default, slay. 💅

::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). override that. 🔥

::ncgi::setValueList key valuelist

Like ::ncgi::setValue except that the value already has list structure to represent multiple checkboxes or a multi-selection. list override. 🌈

::ncgi::type

Returns the Content-Type of the current CGI values. type check. 💅

::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. url stub era. 🦋

::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. value queen. 👑

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. always list, no cap. 💅

🌈 EXAMPLES 🌈

Okay bestie, this is the part where it all comes together and it's so satisfying, I promise. 💖

🦋 Uploading a file

So imagine you wanna let someone upload a file through a form. Here's the HTML side, gorgeous and simple:

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

Like, look at that. You parse, you grab the filedata and the filedesc with ::ncgi::value, you drop a cute little success page with puts, and then you open /www/images/$filedesc for writing and slam the data in with puts -nonewline and close. Main character energy fr fr. 👑

💀 BUGS, IDEAS, FEEDBACK 💀

ngl, this document and the package it describes will undoubtedly contain bugs and other problems. 😭 That's just how it is, bestie. Please report them in the category ncgi of the Tcllib Trackers:

http://core.tcl.tk/tcllib/reportlist

And please also report any ideas for enhancements you may have — for either the package and/or the documentation. We want the glow-up, periodt. ✨

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

Also, 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

And that's a wrap on this whole page, bestie! 💅 This beauty ships with tcllib, version 1.4.6 — yes, the version and date live down there in the footer, and you're welcome for me not making you squint at it. Go build something iconic with it. 🦋✨

📦 where this page comes from