Rivet Tcl Commands and Variables

## Rivet Tcl Commands and Variables

### Name

### var, var_qs, var_post — get the value of a form variable.

### Synopsis

var (get | list | exists | number | all)
var_qs (get | list | exists | number | all)
var_post (get | list | exists | number | all)

### Description

The var command retrieves information about GET or POST variables sent to the script via client request. It treats both GET and POST variables the same, regardless of their origin. Note that there are two additional forms of var: var_qs and var_post. These two restrict the retrieval of information to parameters arriving via the querystring (?foo=bar&bee=bop) or POSTing, respectively.

var get ?`varname`? ?`?default?`?
  Returns the value of variable `varname` as a string (even if there are multiple values). If the variable doesn't exist as a GET or POST variable, the `?default?` value is returned, otherwise "" - an empty string - is returned.
var list ?`varname`?
  Returns the value of variable `varname` as a list, if there are multiple values.
var exists ?`varname`?
  Returns 1 if `varname` exists, 0 if it doesn't.
var number
  Returns the number of variables.
var all
  Return a list of variable names and values.

See Example 3, “Variable Access”.

### Name

### upload — handle a file uploaded by a client.

### Synopsis

upload (channel | save | data | exists | size | type | filename)

### Description

The upload command is for file upload manipulation. See the relevant Apache Directives to further configure the behavior of this Rivet feature.

upload channel ?`uploadname`?
  When given the name of a file upload `uploadname`, returns a Tcl channel that can be used to access the uploaded file.
upload save ?`uploadname`? ?`filename`?
  Saves the `uploadname` in the file `filename`.
upload data ?`uploadname`?
  Returns data uploaded to the server. This is binary clean - in other words, it will work even with files like images, executables, compressed files, and so on.
upload size ?`uploadname`?
  Returns the size of the file uploaded.
upload type
  If the `Content-type` is set, it is returned, otherwise, an empty string.
upload filename ?`uploadname`?
  Returns the filename on the remote host that uploaded the file.
upload names
  Returns the variable names, as a list, of all the files uploaded.

See Example 4, “File Upload”.

### Name

### load_response — load form variables into an array.

### Synopsis

load_response ?`arrayName`?

### Description

Load any form variables passed to this page into an array.

### Name

### load_headers — get client request's headers.

### Synopsis

load_headers ?`array_name`?

### Description

Load the headers that come from a client request into the provided array name, or use headers if no name is provided.

### Name

### load_cookies — get any cookie variables sent by the client.

### Synopsis

load_cookies ?`array_name`?

### Description

Load the array of cookie variables into the specified array name. Uses array cookies by default.

### Name

### load_env — get the request's environment variables.

### Synopsis

load_env ?`array_name`?

### Description

Load the array of environment variables into the specified array name. Uses array ::request::env by default.

As Rivet pages are run in the ::request namespace, it isn't necessary to qualify the array name for most uses - it's ok to access it as env.

### Name

### env — Loads a single "environmental variable" into a Tcl variable.

### Synopsis

env ?`varName`?

### Description

If it is only necessary to load one environmental variable, this command may be used to avoid the overhead of loading and storing the entire array.

### Name

### include — includes a file into the output stream without modification.

### Synopsis

include ?`filename_name`?

### Description

Include a file without parsing it for processing tags <? and ?>. This is the best way to include an HTML file or any other static content.

### Name

### parse — parses a Rivet template file.

### Synopsis

parse ?`filename`?

### Description

Like the Tcl source command, but also parses for Rivet <? and ?> processing tags. Using this command, you can use one .rvt file from another.

### Name

### headers — set and parse HTTP headers.

### Synopsis

headers (set | redirect | add | type | numeric)

### Description

The headers command is for setting and parsing HTTP headers.

headers set ?`headername`? ?`value`?
  Set arbitrary header names and values.
headers redirect ?`uri`?
  Redirect from the current page to a new URI. Must be done in the first block of TCL code.
headers add ?`headername`? ?`value`?
  Add text to header `headername`.
headers type ?`content-type`?
  This command sets the `Content-type` header returned by the script, which is useful if you wish to send content other than HTML with Rivet - PNG or jpeg images, for example.
headers numeric ?`response code`?
  Set a numeric response code, such as 200, 404 or 500.

### Name

### makeurl — construct url's based on hostname, port.

### Synopsis

makeurl ?`filename`?

### Description

Create a self referencing URL from a filename. For example:

    makeurl /tclp.gif

returns `http://[hostname]:[port]/tclp.gif`. where hostname and port are the hostname and port of the server in question.

### Name

### cookie — get and set cookies.

### Synopsis

cookie ?set? ?`cookieName`? ?`?cookiValue?`? ?-days `expireInDays`? ?-hours `expireInHours`? ?-minutes `expireInMinutes`? ?-expires `Wdy, DD-Mon-YYYY HH:MM:SS GMT`? ?-path `uriPathCookieAppliesTo`? ?-secure `1/0`?
cookie ?get? ?`cookieName`?

### Description

cookie gets or sets a cookie. When you get a cookie, the command returns the value of the cookie, or an empty string if no cookie exists.

### Name

### clock_to_rfc850_gmt — create a rfc850 time from [clock seconds].

### Synopsis

clock_to_rfc850_gmt ?`seconds`?

### Description

Convert an integer-seconds-since-1970 click value to RFC850 format, with the additional requirement that it be GMT only.

### Name

### html — construct html tagged text.

### Synopsis

html ?`string`? ?`arg`...?

### Description

Print text with the added ability to pass HTML tags following the string. Example:

    html "Test" b i

produces: `<b><i>Test</i></b>`

### Name

### incr0 — increment a variable or set it to 1 if nonexistant.

### Synopsis

incr0 ?`varname`? ?`num`?

### Description

Increment a variable `varname` by `num`. If the variable doesn't exist, create it instead of returning an error.

### Name

### parray — Tcl's parray with html formatting.

### Synopsis

parray ?`arrayName`? ?`?pattern?`?

### Description

An html version of the standard Tcl parray command. Displays the entire contents of an array in a sorted, nicely-formatted way. Mostly used for debugging purposes.

### Name

### abort_page — Stops outputing data to web page, similar in purpose to PHP's die command.

### Synopsis

abort_page

### Description

This command flushes the output buffer and stops the Tcl script from sending any more data to the client. A normal Tcl script might use the exit command, but that cannot be used in Rivet without actually exiting the apache child process!

### Name

### no_body — Prevents Rivet from sending any content.

### Synopsis

no_body

### Description

This command is useful for situations where it is necessary to only return HTTP headers and no actual content. For instance, when returning a 304 redirect.

### Name

### escape_string — convert a string into escaped characters.

### Synopsis

escape_string ?string?

### Description

Scans through each character in the specified string looking for special characters, escaping them as needed, mapping special characters to a quoted hexadecimal equivalent, returning the result.

This is useful for quoting strings that are going to be part of a URL.

### Name

### escape_sgml_chars — escape special SGML characters in a string.

### Synopsis

escape_sgml_chars ?string?

### Description

Scans through each character in the specified string looking for any special (with respect to SGML, and hence HTML) characters from the specified string, and returns the result. For example, the right angle bracket is escaped to the corrected ampersand gt symbol.

### Name

### escape_shell_command — escape shell metacharacters in a string.

### Synopsis

escape_shell_command ?string?

### Description

Scans through each character in the specified string looking for any shell metacharacters, such as asterisk, less than and greater than, parens, square brackets, curly brackets, angle brackets, dollar signs, backslashes, semicolons, ampersands, vertical bars, etc.

For each metacharacter found, it is quoted in the result by prepending it with a backslash, returning the result.

### Name

### unescape_string — unescape escaped characters in a string.

### Synopsis

unescape_string ?string?

### Description

Scans through each character in the specified string looking for escaped character sequences (characters containing a percent sign and two hexadecimal characters, unescaping them back to their original character values, as needed, also mapping plus signs to spaces, and returning the result.

This is useful for unquoting strings that have been quoted to be part of a URL.

Rivet Apache Directives |  | var