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.

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.

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.
list varname
Returns the value of variable varname as a list, if there are multiple values.
exists varname
Returns 1 if varname exists, 0 if it doesn't.
number
Returns the number of variables.
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.

channel uploadname
When given the name of a file upload uploadname, returns a Tcl channel that can be used to access the uploaded file.
save uploadname filename
Saves the uploadname in the file filename.
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.
size uploadname
Returns the size of the file uploaded.
type
If the Content-type is set, it is returned, otherwise, an empty string.
filename uploadname
Returns the filename on the remote host that uploaded the file.
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.

set headername value
Set arbitrary header names and values.
redirect uri
Redirect from the current page to a new URI. Must be done in the first block of TCL code.
add headername value
Add text to header headername.
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.
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.