Rivet Tcl Commands and Variables

var - get the value of a form variable.
upload - handle a file uploaded by a client.
load_response - load form variables into an array.
load_headers - get client request's headers.
load_cookies - get any cookie variables sent by the client.
load_env - get the request's environment variables.
env - Loads a single "environmental variable" into a Tcl variable.
include - includes a file into the output stream without modification.
parse - parses a Rivet template file.
headers - set and parse HTTP headers.
makeurl - construct url's based on hostname, port.
cookie - get and set cookies.
clock_to_rfc850_gmt - create a rfc850 time from [clock seconds].
html - construct html tagged text.
incr0 - increment a variable or set it to 1 if nonexistant.
parray - Tcl's parray with html formatting.
abort_page - Stops outputing data to web page, similar in purpose to PHP's die command.
no_body - Prevents Rivet from sending any content.
escape_string - convert a string into escaped characters.
escape_sgml_chars - escape special SGML characters in a string.
escape_shell_command - escape shell metacharacters in a string.
unescape_string - unescape escaped characters in a string.

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.