You are viewing a plain text version of this content. The canonical link for it is here.
Posted to site-cvs@tcl.apache.org by mx...@apache.org on 2009/06/24 14:47:45 UTC
svn commit: r788000 [5/6] - in /tcl/site/rivet/manual: ./ images/
Added: tcl/site/rivet/manual/rivet.html
URL: http://svn.apache.org/viewvc/tcl/site/rivet/manual/rivet.html?rev=788000&view=auto
==============================================================================
--- tcl/site/rivet/manual/rivet.html (added)
+++ tcl/site/rivet/manual/rivet.html Wed Jun 24 12:47:44 2009
@@ -0,0 +1,2059 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Apache Rivet</title><link rel="stylesheet" href="rivet.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="article" title="Apache Rivet"><div class="titlepage"><div><div><h2 class="title"><a name="id450340"></a>Apache Rivet</h2></div><div><div class="author"><h3 class="author"><span class="firstname">The Rivet Team</span></h3><div class="affiliation"><span class="orgname">The Apache Software Foundation<br></span><div class="address"><p><br>
+ <code class="email"><<a class="email" href="mailto:rivet-dev@tcl.apache.org">rivet-dev@tcl.apache.org</a>></code><br>
+ </p></div></div></div></div><div><p class="copyright">Copyright © 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Apache Software Foundation</p></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#introduction">Introduction to Apache Rivet</a></span></dt><dt><span class="section"><a href="#installation">Apache Rivet Installation</a></span></dt><dt><span class="section"><a href="#directives">Rivet Apache Directives</a></span></dt><dt><span class="section"><a href="#commands">Rivet Tcl Commands and Variables</a></span></dt><dd><dl><dt><span class="refentrytitle"><a href="#var">var</a></span><span class="refpurpose"> — get the value of a form variable.</span></dt><dt><span class="refentrytitle"><a href="#upload">upload</a></span><span class="refpurpose"> — handle a file uploaded by a client.</span></dt><dt><span class="refentrytitle"><a href="#load_response">load_response</a></span><span class="refpurpose"> &
#8212; load form variables into an array.</span></dt><dt><span class="refentrytitle"><a href="#load_headers">load_headers</a></span><span class="refpurpose"> — get client request's headers.</span></dt><dt><span class="refentrytitle"><a href="#load_cookies">load_cookies</a></span><span class="refpurpose"> — get any cookie variables sent by the client.</span></dt><dt><span class="refentrytitle"><a href="#load_env">load_env</a></span><span class="refpurpose"> — get the request's environment variables.</span></dt><dt><span class="refentrytitle"><a href="#env">env</a></span><span class="refpurpose"> — Loads a single
+ "environmental variable" into a Tcl variable.</span></dt><dt><span class="refentrytitle"><a href="#include">include</a></span><span class="refpurpose"> — includes a file into the output stream without modification.</span></dt><dt><span class="refentrytitle"><a href="#parse">parse</a></span><span class="refpurpose"> — parses a Rivet template file.</span></dt><dt><span class="refentrytitle"><a href="#headers">headers</a></span><span class="refpurpose"> — set and parse HTTP headers.</span></dt><dt><span class="refentrytitle"><a href="#makeurl">makeurl</a></span><span class="refpurpose"> — construct url's based on hostname, port.</span></dt><dt><span class="refentrytitle"><a href="#cookie">cookie</a></span><span class="refpurpose"> — get and set cookies.</span></dt><dt><span class="refentrytitle"><a href="#clock_to_rfc">clock_to_rfc850_gmt</a></span><span class="refpurpose"> — create a rfc850 time from [clock seconds].</span></dt><dt><span cl
ass="refentrytitle"><a href="#html">html</a></span><span class="refpurpose"> — construct html tagged text.</span></dt><dt><span class="refentrytitle"><a href="#incr0">incr0</a></span><span class="refpurpose"> — increment a variable or set it to 1 if nonexistant.</span></dt><dt><span class="refentrytitle"><a href="#parray">parray</a></span><span class="refpurpose"> — Tcl's <span style="font-family:monospace"><span class="command"><strong>parray</strong></span></span> with html formatting.</span></dt><dt><span class="refentrytitle"><a href="#abort_page">abort_page</a></span><span class="refpurpose"> — Stops outputing data to web page, similar in
+ purpose to PHP's <span style="font-family:monospace"><span class="command"><strong>die</strong></span></span> command.</span></dt><dt><span class="refentrytitle"><a href="#no_body">no_body</a></span><span class="refpurpose"> — Prevents Rivet from sending any content.</span></dt><dt><span class="refentrytitle"><a href="#escape_string">escape_string</a></span><span class="refpurpose"> — convert a string into escaped characters.</span></dt><dt><span class="refentrytitle"><a href="#escape_sgml_chars">escape_sgml_chars</a></span><span class="refpurpose"> — escape special SGML characters in a string.</span></dt><dt><span class="refentrytitle"><a href="#escape_shell_command">escape_shell_command</a></span><span class="refpurpose"> — escape shell metacharacters in a string.</span></dt><dt><span class="refentrytitle"><a href="#unescape_string">unescape_string</a></span><span class="refpurpose"> — unescape escaped characters in a string.</span></dt></d
l></dd><dt><span class="section"><a href="#examples">Examples and Usage</a></span></dt><dt><span class="section"><a href="#tcl_packages">Rivet Tcl Packages</a></span></dt><dt><span class="section"><a href="#dio">DIO - Database Interface Objects</a></span></dt><dd><dl><dt><span class="refentrytitle"><a href="#dio_package">DIO</a></span><span class="refpurpose"> — Database Interface Objects</span></dt></dl></dd><dt><span class="section"><a href="#diodisplay">DIODisplay - Database Interface Objects Display Class</a></span></dt><dd><dl><dt><span class="refentrytitle"><a href="#diodisplay_package">DIODisplay</a></span><span class="refpurpose"> — Database Interface Objects Display Class</span></dt></dl></dd><dt><span class="section"><a href="#session_package">Session Package</a></span></dt><dd><dl><dt><span class="section"><a href="#id490862">Introduction</a></span></dt><dt><span class="section"><a href="#requirements">Requirements</a></span></dt><dt><span class="secti
on"><a href="#id491217">Preparing To Use It</a></span></dt><dt><span class="section"><a href="#id491262">Example Usage</a></span></dt><dt><span class="section"><a href="#id491318">Using Sessions From Your Code</a></span></dt><dt><span class="section"><a href="#id491516">Session Configuration Options</a></span></dt><dt><span class="section"><a href="#id491749">Session Methods</a></span></dt><dt><span class="section"><a href="#id491975">Getting Additional Randomness From The Entropy File</a></span></dt></dl></dd><dt><span class="section"><a href="#help">Resources - How to Get Help</a></span></dt><dd><dl><dt><span class="section"><a href="#id492588">Mailing Lists</a></span></dt><dt><span class="section"><a href="#id492929">Newsgroup</a></span></dt><dt><span class="section"><a href="#websites">Web Sites</a></span></dt><dt><span class="section"><a href="#id493008">Bug Tracking System</a></span></dt><dt><span class="section"><a href="#id493024">IRC</a></span></dt><dt><span class="
section"><a href="#id493035">Editing Rivet Template Files</a></span></dt></dl></dd><dt><span class="section"><a href="#internals">Rivet Internals</a></span></dt><dd><dl><dt><span class="section"><a href="#id492760">Initialization</a></span></dt><dt><span class="section"><a href="#id492823">RivetChan</a></span></dt><dt><span class="section"><a href="#id493364">The <span style="font-family:monospace"><span class="command"><strong>global</strong></span></span> Command</a></span></dt><dt><span class="section"><a href="#id493408">Page Parsing, Execution and Caching</a></span></dt><dt><span class="section"><a href="#id493450">Debugging Rivet and Apache</a></span></dt></dl></dd><dt><span class="section"><a href="#upgrading">Upgrading from mod_dtcl or NeoWebScript</a></span></dt><dd><dl><dt><span class="section"><a href="#id493578">mod_dtcl</a></span></dt><dt><span class="section"><a href="#id493589">NeoWebScript</a></span></dt></dl></dd></dl></div><div class="list-of-examples"><p><
b>List of Examples</b></p><dl><dt>1. <a href="#hello%20world">Hello World</a></dt><dt>2. <a href="#id478912">Generate a Table</a></dt><dt>3. <a href="#variable_access">Variable Access</a></dt><dt>4. <a href="#file_upload">File Upload</a></dt><dt>5. <a href="#file_download">File Download</a></dt><dt>6. <a href="#ajax_xml_messaging">XML Messages and Ajax</a></dt></dl></div><p style="width:90%">
+ Document revision: $Revision: 787687 $, last modified 2009-06-23 17:35:01+02:00$ by $Author: mxmanghi $.
+ </p><div class="section" title="Introduction to Apache Rivet"><div class="titlepage"><div><div><hr><h2 class="title" style="clear: both"><a name="introduction"></a>Introduction to Apache Rivet</h2></div></div></div><p style="width:90%">
+ Apache Rivet is a system for creating dynamic web content via a
+ programming language integrated with Apache Web Server. It is
+ designed to be fast, powerful and extensible, consume few system
+ resources, be easy to learn, and to provide the user with a
+ platform that can also be used for other programming tasks
+ outside the web (GUI's, system administration tasks, text
+ processing, database manipulation, XML, and so on). In order to
+ meet these goals, we have chosen the Tcl programming language to
+ combine with the Apache Web Server.
+ </p><p style="width:90%">
+ In this manual, we aim to help get you started, and then
+ writing productive code as quickly as possible, as well as
+ giving you ideas on how to best take advantage of Rivet's
+ architecture to create different styles of web site.
+ </p><p style="width:90%">
+ This documentation is a work in progress, and, like everything
+ else about Apache Rivet, it is Free Software. If you see
+ something that needs improving, and have ideas or suggestions,
+ don't hesitate to let us know. If you want to contribute
+ directly, better yet!
+ </p></div><div class="section" title="Apache Rivet Installation"><div class="titlepage"><div><div><hr><h2 class="title" style="clear: both"><a name="installation"></a>Apache Rivet Installation</h2></div></div></div><div class="procedure"><ol class="procedure" type="1"><li class="step" title="Check Dependencies"><p class="title"><b>Check Dependencies</b></p><p style="width:90%">
+ To install Rivet, you will need Tcl 8.4 or greater and
+ Apache 1.3.xx. It is known to run on Linux, FreeBSD,
+ OpenBSD, and Solaris and HPUX. Windows NT is also possible
+ - please see the directions in the distribution. Note that
+ Rivet does not currently work with Apache 2.
+ </p></li><li class="step" title="Get Rivet"><p class="title"><b>Get Rivet</b></p><p style="width:90%">
+ Download the sources at <a class="ulink" href="http://tcl.apache.org/rivet/download.html" target="_top">http://tcl.apache.org/rivet/download.html</a>. Currently
+ the only way to obtain Rivet. In the future, we hope to
+ have a FreeBSD port, Debian package, RPM's, and windows
+ binaries.
+ </p></li><li class="step" title="Install Tcl"><p class="title"><b>Install Tcl</b></p><p style="width:90%">
+ If you don't have Tcl already, you need it! If you already
+ have it, you should just be able to use your system Tcl as
+ long as it is recent. You can tell Rivet where Tcl is via
+ the -with-tclconfig option to
+ <span style="font-family:monospace"><span class="command"><strong>configure.tcl</strong></span></span> (see below).</p></li><li class="step" title="Get and Install Apache Sources"><p class="title"><b>Get and Install Apache Sources</b></p><p style="width:90%">
+ Rivet needs some Apache include (.h) files in order to
+ build. The easiest way to get them is to download the
+ source code of the Apache web server, although some systems
+ (Debian GNU/Linux for example) make it possible to install
+ only the headers and other development files. If you intend
+ to build Rivet statically (compiled into the Apache web
+ server instead of loaded dynamically), you definitely need
+ the sources. We recommend that you build Rivet as a
+ loadable shared library, for maximum flexibility, meaning
+ that you also build Apache to be able to load modules.
+ Other than that, the default Apache install is fine. We
+ will tell Rivet where it is located via the
+ -with-apxs option to
+ <span style="font-family:monospace"><span class="command"><strong>configure.tcl</strong></span></span> (see below).
+ </p><p style="width:90%">
+ The source code for the Apache web server may be found by
+ following the links here: <a class="ulink" href="http://httpd.apache.org/" target="_top">http://httpd.apache.org/</a>.
+ </p></li><li class="step" title="Uncompress Sources"><p class="title"><b>Uncompress Sources</b></p><p style="width:90%">
+ We will assume that you have Apache installed at this point.
+ You must uncompress the Rivet sources in the directory where you
+ wish to compile them.
+
+ </p><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting">gunzip tcl-rivet-X.X.X.tar.gz
+tar -xvf tcl-rivet-X.X.X.tar.gz</pre><p style="width:90%">
+
+ </p></li><li class="step" title="Building Rivet"><p class="title"><b>Building Rivet</b></p><ol type="a" class="substeps"><li class="step" title="Step 6.a"><p style="width:90%">
+ On Linux or Unix systems, Rivet uses the standard
+ ./configure ; make ; make install technique.
+ </p><p style="width:90%">
+ There are several options to configure that might be useful
+ or necessary:
+ </p><div class="variablelist"><dl><dt><span class="term">--with-tcl</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
+ This points to the directory where the
+ <code class="filename">tclConfig.sh</code> file is located.
+ </div></div></dd><dt><span class="term">--with-tclsh</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">This points to the location of the
+ <code class="filename">tclsh</code> executable.</div></div></dd><dt><span class="term">--with-apxs</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">The location of the <code class="filename">apxs</code>
+ program that provides information about the
+ configuration and compilation of Apache modules.</div></div></dd></dl></div><p style="width:90%">
+ </p><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting">cd src/
+./configure --with-tcl=/usr/lib/tcl8.4/ --with-tclsh=/usr/bin/tclsh8.4 \
+ --with-apxs=/usr/bin/apxs
+</pre></li><li class="step" title="Run make"><p class="title"><b>Run make</b></p><p style="width:90%">
+ At this point, you are ready to run make, which should
+ run to completion without any errors (a warning or two
+ is ok, generally).
+ </p></li><li class="step" title="Install"><p class="title"><b>Install</b></p><p style="width:90%">
+ Now, you are ready to run the <span style="font-family:monospace"><span class="command"><strong>make
+ install</strong></span></span> to install the resulting files.
+ This should copy the shared object (like
+ <code class="filename">mod_rivet.so</code>, if one was
+ successfully created, into Apache's
+ <code class="filename">libexec</code> directory, as well as
+ install some support scripts and various code.
+ </p></li></ol></li><li class="step" title="Apache Configuration Files"><p class="title"><b>Apache Configuration Files</b></p><p style="width:90%">
+ Rivet is relatively easy to configure - we start off by
+ adding the module itself:
+ </p><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting">LoadModule rivet_module
+ <em class="replaceable"><code>/usr/lib/apache/1.3/mod_rivet.so</code></em>
+ </pre><p style="width:90%">
+ This tells Apache to load the Rivet shared object, wherever
+ it happens to reside on your file system. Now we have to
+ tell Apache what kind of files are "Rivet" files and how to
+ process them:
+ </p><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting">AddType application/x-httpd-rivet .rvt
+AddType application/x-rivet-tcl .tcl</pre><p style="width:90%">
+ These tell Apache to process files with the
+ <code class="filename">.rvt</code> and <code class="filename">.tcl</code>
+ extensions as Rivet files.
+ </p><p style="width:90%">
+ The characters encoding can be changed using the <span style="font-family:monospace"><span class="command"><strong>header type</strong></span></span> command,
+ but if you want to change the default charset for the whole site or directory hierarchy
+ a new charset can be embedded in a AddType line in a way similar to the html pages encoding.
+ </p><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting">AddType 'application/x-httpd-rivet;charset=utf-8' rvt</pre><p style="width:90%">
+ Pages which this configuration applies to send back to the client
+ a <span style="font-family:monospace"><span class="command"><strong>Content-Type:'text/html;charset=utf-8'</strong></span></span> header.
+ </p><p style="width:90%">You may also wish to use Rivet files as index files for
+ directories. In that case, you would do the following:</p><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting">DirectoryIndex index.html index.htm index.shtml index.cgi index.tcl index.rvt</pre><p style="width:90%">
+ For other directives that Rivet provides for Apache
+ configuration, please see <a class="xref" href="#directives" title="Rivet Apache Directives">the section called “Rivet Apache Directives”</a>.
+ </p></li></ol></div></div><div class="section" title="Rivet Apache Directives"><div class="titlepage"><div><div><hr><h2 class="title" style="clear: both"><a name="directives"></a>Rivet Apache Directives</h2></div></div></div><p style="width:90%">
+ These directives are used within the Apache httpd server
+ configuration files to modify Apache Rivet's behavior. Their
+ precedence is as follows: <span style="font-family:monospace"><span class="command"><strong>RivetDirConf</strong></span></span>,
+ <span style="font-family:monospace"><span class="command"><strong>RivetUserConf</strong></span></span>,
+ <span style="font-family:monospace"><span class="command"><strong>RivetServerConf</strong></span></span>, meaning that DirConf will
+ override UserConf, which will in turn override ServerConf.
+ </p><div class="variablelist"><dl><dt><span class="term">
+ <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">RivetServerConf</span> (<span style="font-family:monospace; font-weight: bold;">CacheSize</span> | <span style="font-family:monospace; font-weight: bold;">GlobalInitScript</span> | <span style="font-family:monospace; font-weight: bold;">ChildInitScript</span> | <span style="font-family:monospace; font-weight: bold;">ChildExitScript</span> | <span style="font-family:monospace; font-weight: bold;">BeforeScript</span> | <span style="font-family:monospace; font-weight: bold;">AfterScript</span> | <span style="font-family:monospace; font-weight: bold;">ErrorScript</span> | <span style="font-family:monospace; font-weight: bold;">UploadDirectory</span> | <span style="font-family:monospace; font-weight: bold;">UploadMaxSize</span> | <span style="font-family:monospace; font-weight: b
old;">UploadFilesToVar</span> | <span style="font-family:monospace; font-weight: bold;">SeparateVirtualInterps</span> | <span style="font-family:monospace; font-weight: bold;">HonorHeaderOnlyRequests</span>)</div></div>
+ </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"><span style="font-family:monospace"><span class="command"><strong>RivetServerConf</strong></span></span> specifies a global
+ option that is valid for the whole server. If you have a
+ virtual host, in some cases, the option specified in the
+ virtualhost takes precedence over the 'global' version.
+ </div><div class="variablelist"><dl><dt><span class="term">
+ <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">CacheSize</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>size</code></em></span>?</div></div>
+ </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
+ Sets the size of the internal page cache, where
+ <em class="replaceable"><code>size</code></em> is
+ the number of byte-compiled pages to be cached for
+ future use. Default is
+ <span style="font-family:monospace"><span class="command"><strong>MaxRequestsPerChild</strong></span></span> / 5, or 50,
+ if <span style="font-family:monospace"><span class="command"><strong>MaxRequestsPerChild</strong></span></span> is 0.
+ </div><div style="margin-bottom:1.5ex ; padding .5ex">
+ This option is completely global, even when using
+ separate, per-virtual host interpreters.
+ </div></div></dd><dt><span class="term">
+ <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">GlobalInitScript</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>script</code></em></span>?</div></div>
+ </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
+ Tcl script that is run when each interpreter is
+ initialized. <em class="replaceable"><code>script</code></em>
+ is an actual Tcl script, so to run a file, you would
+ do:
+
+ <pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting">RivetServerConf GlobalInitScript "source /var/www/foobar.tcl"</pre>
+ </div><div style="margin-bottom:1.5ex ; padding .5ex">
+ This option is ignored in virtual hosts.
+ </div></div></dd><dt><span class="term">
+ <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">ChildInitScript</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>script</code></em></span>?</div></div>
+ </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
+ Script to be evaluated when each Apache child
+ process is initialized. This is the recommended
+ place to load modules, create global variables, open
+ connections to other facilities (such as databases)
+ and so on.
+ </div><div style="margin-bottom:1.5ex ; padding .5ex">
+ In virtual hosts, this script is run in addition to
+ any global childinitscript.
+ </div></div></dd><dt><span class="term">
+ <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">ChildExitScript</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>script</code></em></span>?</div></div>
+ </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
+ Script to be evaluated when each Apache child
+ process exits. This is the logical place to clean
+ up resources created in
+ ChildInitScript, if necessary.
+ </div><div style="margin-bottom:1.5ex ; padding .5ex">
+ In virtual hosts, this script is run in addition to
+ any global childexitscript.
+ </div></div></dd><dt><span class="term">
+ <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">BeforeScript</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>script</code></em></span>?</div></div>
+ </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
+ Script to be evaluated before each server parsed
+ (.rvt) page. This can be used to create a standard
+ header, for instance. It could also be used to load
+ code that you need for every page, if you don't want
+ to put it in a GlobalInitScript
+ ChildInitScript when you are first
+ developing a web site.
+ <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top">
+ This code is evaluated at the global level, not
+ inside the request namespace where pages are
+ evaluated.
+ </td></tr></table></div>
+ </div><div style="margin-bottom:1.5ex ; padding .5ex">
+ In virtual hosts, this option takes precedence over
+ the global setting.
+ </div></div></dd><dt><span class="term">
+ <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">AfterScript</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>script</code></em></span>?</div></div>
+ </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
+ Script to be called after each server parsed (.rvt) page.
+ </div><div style="margin-bottom:1.5ex ; padding .5ex">
+ In virtual hosts, this option takes precedence over
+ the global setting.
+ </div></div></dd><dt><span class="term">
+ <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">ErrorScript</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>script</code></em></span>?</div></div>
+ </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
+ When Rivet encounters an error in a script, it
+ constructs an HTML page with some information about
+ the error, and the script that was being
+ evaluated. If an ErrorScript is
+ specified, it is possible to create custom error
+ pages. This may be useful if you want to make sure
+ that users never view your source code.
+ </div><div style="margin-bottom:1.5ex ; padding .5ex">
+ In virtual hosts, this option takes precedence over
+ the global setting.
+ </div></div></dd><dt><span class="term">
+ <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">UploadDirectory</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>directory</code></em></span>?</div></div>
+ </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">Directory to place uploaded files.</div><div style="margin-bottom:1.5ex ; padding .5ex">
+ In virtual hosts, this option takes precedence over
+ the global setting.
+ </div></div></dd><dt><span class="term">
+ <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">UploadMaxSize</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>size</code></em></span>?</div></div>
+ </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">Maximum size for uploaded files.</div><div style="margin-bottom:1.5ex ; padding .5ex">
+ In virtual hosts, this option takes precedence over
+ the global setting.
+ </div></div></dd><dt><span class="term">
+ <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">UploadFilesToVar</span> (<span style="font-family:monospace; font-weight: bold;">yes</span> | <span style="font-family:monospace; font-weight: bold;">no</span>)</div></div>
+ </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
+ This option controls whether it is possible to
+ upload files to a Tcl variable. If you have a size
+ limit, and don't have to deal with large files, this
+ might be more convenient than sending the data to a
+ file on disk.
+ </div></div></dd><dt><span class="term">
+ <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">SeparateVirtualInterps</span> (<span style="font-family:monospace; font-weight: bold;">yes</span> | <span style="font-family:monospace; font-weight: bold;">no</span>)</div></div>
+ </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
+ If on, Rivet will create a separate Tcl interpreter
+ for each Apache virtual host. This is useful in an
+ ISP type situation where it is desirable to separate
+ clients into separate interpreters, so that they
+ don't accidentally interfere with one another.
+ </div><div style="margin-bottom:1.5ex ; padding .5ex">This option is, by nature, only available at the
+ global level.</div></div></dd><dt><span class="term">
+ <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">HonorHeaderOnlyRequests</span> (<span style="font-family:monospace; font-weight: bold;">yes</span> | <span style="font-family:monospace; font-weight: bold;">no</span>)</div></div>
+ </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
+ If a HEAD requests is issued by the client Rivet detects
+ this case and sends back to the client a standard header
+ response. If the real header has to be examined (e.g.
+ for debugging) you can turn on this options which
+ causes Rivet to parse and run the script the requests refers
+ to. In this case the real header is returned to the client.
+ </div><div style="margin-bottom:1.5ex ; padding .5ex">This option is, by nature, only available at the global level</div></div></dd></dl></div></div></dd><dt><span class="term">
+ <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">RivetDirConf</span> (<span style="font-family:monospace; font-weight: bold;">BeforeScript</span> | <span style="font-family:monospace; font-weight: bold;">AfterScript</span> | <span style="font-family:monospace; font-weight: bold;">ErrorScript</span> | <span style="font-family:monospace; font-weight: bold;">UploadDirectory</span>)</div></div>
+ </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
+ These options are the same as for
+ <span style="font-family:monospace"><span class="command"><strong>RivetServerConf</strong></span></span>, except that they are
+ only valid for the directory where they are specified, and
+ its subdirectories. It may be specified in
+ <span style="font-family:monospace"><span class="command"><strong>Directory</strong></span></span> sections.
+ </div></div></dd><dt><span class="term">
+ <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">RivetUserConf</span> (<span style="font-family:monospace; font-weight: bold;">BeforeScript</span> | <span style="font-family:monospace; font-weight: bold;">AfterScript</span> | <span style="font-family:monospace; font-weight: bold;">ErrorScript</span> | <span style="font-family:monospace; font-weight: bold;">UploadDirectory</span>)</div></div>
+ </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
+ These options are the same as for
+ <span style="font-family:monospace"><span class="command"><strong>RivetServerConf</strong></span></span>, except that they are
+ only valid for the directory where they are specified, and
+ its subdirectories.
+ </div></div></dd></dl></div></div><div class="section" title="Rivet Tcl Commands and Variables"><div class="titlepage"><div><div><hr><h2 class="title" style="clear: both"><a name="commands"></a>Rivet Tcl Commands and Variables</h2></div></div></div><div class="refentry" title="var"><a name="var"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>var, var_qs, var_post — get the value of a form variable.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">var</span> (<span style="font-family:monospace; font-weight: bold;">get</span> | <span style="font-family:monospace; font-weight: bold;">list</span> | <span style="font-family:monospace; font-weight: bold;">exists</span> | <span style="font-family:monospace; font-weight: bold;">n
umber</span> | <span style="font-family:monospace; font-weight: bold;">all</span>)</div></div><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">var_qs</span> (<span style="font-family:monospace; font-weight: bold;">get</span> | <span style="font-family:monospace; font-weight: bold;">list</span> | <span style="font-family:monospace; font-weight: bold;">exists</span> | <span style="font-family:monospace; font-weight: bold;">number</span> | <span style="font-family:monospace; font-weight: bold;">all</span>)</div></div><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">var_post</span> (<span style="font-family:monospace; font-weight: bold;">get</span> | <span style="font-family:monos
pace; font-weight: bold;">list</span> | <span style="font-family:monospace; font-weight: bold;">exists</span> | <span style="font-family:monospace; font-weight: bold;">number</span> | <span style="font-family:monospace; font-weight: bold;">all</span>)</div></div></div><div class="refsect1" title="Description"><a name="id474254"></a><h2>Description</h2><p style="width:90%">
+ The <span style="font-family:monospace"><span class="command"><strong>var</strong></span></span> 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 <span style="font-family:monospace"><span class="command"><strong>var</strong></span></span>:
+ <span style="font-family:monospace"><span class="command"><strong>var_qs</strong></span></span> and <span style="font-family:monospace"><span class="command"><strong>var_post</strong></span></span>.
+ These two restrict the retrieval of information to
+ parameters arriving via the querystring
+ (?foo=bar&bee=bop) or POSTing, respectively.
+ </p><div class="variablelist"><dl><dt><span class="term">
+ <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">var</span> <span style="font-family:monospace; font-weight: bold;">get</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>varname</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>?<span class="optional">default</span>?</code></em></span>?</div></div>
+ </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
+ Returns the value of variable
+ <em class="replaceable"><code>varname</code></em>
+ as a string (even if there are multiple values). If
+ the variable doesn't exist as a GET or POST
+ variable, the
+ <em class="replaceable"><code>?<span class="optional">default</span>?</code></em>
+ value is returned, otherwise "" - an empty string -
+ is returned.
+ </div></div></dd><dt><span class="term">
+ <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">var</span> <span style="font-family:monospace; font-weight: bold;">list</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>varname</code></em></span>?</div></div>
+ </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
+ Returns the value of variable
+ <em class="replaceable"><code>varname</code></em> as a
+ list, if there are multiple values.
+ </div></div></dd><dt><span class="term">
+ <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">var</span> <span style="font-family:monospace; font-weight: bold;">exists</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>varname</code></em></span>?</div></div>
+ </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
+ Returns 1 if
+ <em class="replaceable"><code>varname</code></em>
+ exists, 0 if it doesn't.
+ </div></div></dd><dt><span class="term">
+ <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">var</span> <span style="font-family:monospace; font-weight: bold;">number</span> </div></div>
+ </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
+ Returns the number of variables.
+ </div></div></dd><dt><span class="term">
+ <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">var</span> <span style="font-family:monospace; font-weight: bold;">all</span> </div></div>
+ </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
+ Return a list of variable names and values.
+ </div></div></dd></dl></div><p style="width:90%">
+ See <a class="xref" href="#variable_access" title="Example 3. Variable Access">Example 3, “Variable Access”</a>.
+ </p></div></div><div class="refentry" title="upload"><div class="refentry.separator"><hr></div><a name="upload"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>upload — handle a file uploaded by a client.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">upload</span> (<span style="font-family:monospace; font-weight: bold;">channel</span> | <span style="font-family:monospace; font-weight: bold;">save</span> | <span style="font-family:monospace; font-weight: bold;">data</span> | <span style="font-family:monospace; font-weight: bold;">exists</span> | <span style="font-family:monospace; font-weight: bold;">size</span> | <span style="font-family:monospace; font-weight: bold;">type</span> | <span style="font-family:monospace; font
-weight: bold;">filename</span>)</div></div></div><div class="refsect1" title="Description"><a name="id474593"></a><h2>Description</h2><p style="width:90%">The upload command is for file upload manipulation.
+ See the relevant Apache Directives to further configure the
+ behavior of this Rivet feature.
+ </p><div class="variablelist"><dl><dt><span class="term">
+ <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">upload</span> <span style="font-family:monospace; font-weight: bold;">channel</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>uploadname</code></em></span>?</div></div>
+ </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
+ When given the name of a file upload
+ <em class="replaceable"><code>uploadname</code></em>,
+ returns a Tcl channel that can be used to access the
+ uploaded file.
+ </div></div></dd><dt><span class="term">
+ <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">upload</span> <span style="font-family:monospace; font-weight: bold;">save</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>uploadname</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>filename</code></em></span>?</div></div>
+ </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
+ Saves the
+ <em class="replaceable"><code>uploadname</code></em> in
+ the file
+ <em class="replaceable"><code>filename</code></em>.
+ </div></div></dd><dt><span class="term">
+ <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">upload</span> <span style="font-family:monospace; font-weight: bold;">data</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>uploadname</code></em></span>?</div></div>
+ </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
+ 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.
+ </div></div></dd><dt><span class="term">
+ <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">upload</span> <span style="font-family:monospace; font-weight: bold;">exists</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>uploadname</code></em></span>?</div></div>
+ </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
+ Returns true if an upload named ?<span style="font-family:monospace; font-weight: bold;">uploadname</span>?
+ exists. This can be used in scripts that are meant to
+ be run by different forms that send over uploads that
+ might need specific processing.
+ </div></div></dd><dt><span class="term">
+ <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">upload</span> <span style="font-family:monospace; font-weight: bold;">size</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>uploadname</code></em></span>?</div></div>
+ </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
+ Returns the size of the file uploaded.
+ </div></div></dd><dt><span class="term">
+ <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">upload</span> <span style="font-family:monospace; font-weight: bold;">type</span> </div></div>
+ </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
+ If the <code class="varname">Content-type</code> is set, it is
+ returned, otherwise, an empty string.
+ </div></div></dd><dt><span class="term">
+ <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">upload</span> <span style="font-family:monospace; font-weight: bold;">filename</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>uploadname</code></em></span>?</div></div>
+ </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
+ Returns the filename on the remote host that uploaded the file.
+ </div></div></dd><dt><span class="term">
+ <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">upload</span> <span style="font-family:monospace; font-weight: bold;">tempname</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>uploadname</code></em></span>?</div></div>
+ </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
+ Returns the name of the temporary file on the local host that the file was uploaded into.
+ </div></div></dd><dt><span class="term">
+ <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">upload</span> <span style="font-family:monospace; font-weight: bold;">names</span> </div></div>
+ </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
+ Returns the variable names, as a list, of all the files
+ uploaded.
+ </div></div></dd></dl></div><p style="width:90%">
+ See <a class="xref" href="#upload" title="upload">upload</a>.
+ </p></div></div><div class="refentry" title="load_response"><div class="refentry.separator"><hr></div><a name="load_response"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>load_response — load form variables into an array.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">load_response</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>arrayName</code></em></span>?</div></div></div><div class="refsect1" title="Description"><a name="id475020"></a><h2>Description</h2>
+ Load any form variables passed to this page into an
+ array. If <span style="font-family:monospace"><span class="command"><strong>load_response</strong></span></span> is called without
+ arguments the array response is created in
+ the scope of the caller. If the variables var1,var2,var3...
+ having values val1,val2,val3... are passed to the page, the
+ resulting array will be a collection mapping var1,var2,var3...
+ to their corresponding values. <span style="font-family:monospace"><span class="command"><strong>load_response</strong></span></span>
+ was inspired by the same NeoWebScript procedure in the way
+ it deals with multiple assignments: if a variable
+ is assigned more than once the corresponding array element will be a
+ list of the values for the variable. This can be useful in the case
+ of forms with checkbox options that are given the same name.
+ Calling <span style="font-family:monospace"><span class="command"><strong>load_response</strong></span></span> several times for the same
+ array results in adding more values to the array at every call.
+ When needed it is left to the caller to empty the array between
+ two subsequent calls.
+ </div></div><div class="refentry" title="load_headers"><div class="refentry.separator"><hr></div><a name="load_headers"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>load_headers — get client request's headers.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">load_headers</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>array_name</code></em></span>?</div></div></div><div class="refsect1" title="Description"><a name="id475090"></a><h2>Description</h2><p style="width:90%">
+ Load the headers that come from a client request into the
+ provided array name, or use headers if no
+ name is provided.
+ </p></div></div><div class="refentry" title="load_cookies"><div class="refentry.separator"><hr></div><a name="load_cookies"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>load_cookies — get any cookie variables sent by the client.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">load_cookies</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>array_name</code></em></span>?</div></div></div><div class="refsect1" title="Description"><a name="id475140"></a><h2>Description</h2></div><p style="width:90%">
+ Load the array of cookie variables into the specified
+ array name. Uses array cookies by
+ default.
+ </p></div><div class="refentry" title="load_env"><div class="refentry.separator"><hr></div><a name="load_env"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>load_env — get the request's environment variables.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">load_env</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>array_name</code></em></span>?</div></div></div><div class="refsect1" title="Description"><a name="id475190"></a><h2>Description</h2><p style="width:90%">
+ Load the array of environment variables into the specified
+ array name. Uses array ::request::env by
+ default.
+ </p><p style="width:90%">
+ 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.
+ </p></div></div><div class="refentry" title="env"><div class="refentry.separator"><hr></div><a name="env"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>env — Loads a single
+ "environmental variable" into a Tcl variable.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">env</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>varName</code></em></span>?</div></div></div><div class="refsect1" title="Description"><a name="id475252"></a><h2>Description</h2><p style="width:90%">
+ 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.
+ </p></div></div><div class="refentry" title="include"><div class="refentry.separator"><hr></div><a name="include"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>include — includes a file into the output stream without modification.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">include</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>filename_name</code></em></span>?</div></div></div><div class="refsect1" title="Description"><a name="id475300"></a><h2>Description</h2><p style="width:90%">
+ 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.
+ </p></div></div><div class="refentry" title="parse"><div class="refentry.separator"><hr></div><a name="parse"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>parse — parses a Rivet template file.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">parse</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>filename</code></em></span>?</div></div></div><div class="refsect1" title="Description"><a name="id475350"></a><h2>Description</h2><p style="width:90%">
+ Like the Tcl <span style="font-family:monospace"><span class="command"><strong>source</strong></span></span> command, but also
+ parses for Rivet <? and ?> processing tags. Using
+ this command, you can use one .rvt file from another.
+ </p></div></div><div class="refentry" title="headers"><div class="refentry.separator"><hr></div><a name="headers"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>headers — set and parse HTTP headers.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">headers</span> (<span style="font-family:monospace; font-weight: bold;">set</span> | <span style="font-family:monospace; font-weight: bold;">redirect</span> | <span style="font-family:monospace; font-weight: bold;">add</span> | <span style="font-family:monospace; font-weight: bold;">type</span> | <span style="font-family:monospace; font-weight: bold;">numeric</span>)</div></div></div><div class="refsect1" title="Description"><a name="id475439"></a><h2>Description</h2><p style="wid
th:90%">
+ The <span style="font-family:monospace"><span class="command"><strong>headers</strong></span></span> command is for setting and
+ parsing HTTP headers.
+ </p><div class="variablelist"><dl><dt><span class="term"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">headers</span> <span style="font-family:monospace; font-weight: bold;">set</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>headername</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div>
+ </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
+ Set arbitrary header names and values.
+ </div></div></dd><dt><span class="term">
+ <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">headers</span> <span style="font-family:monospace; font-weight: bold;">redirect</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>uri</code></em></span>?</div></div>
+ </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
+ Redirect from the current page to a new
+ URI. <span class="emphasis"><em>Must</em></span> be done in the first block
+ of TCL code.
+ </div></div></dd><dt><span class="term">
+ <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">headers</span> <span style="font-family:monospace; font-weight: bold;">add</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>headername</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div>
+ </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">Add text to header
+ <code class="varname">headername</code>.</div></div></dd><dt><span class="term"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">headers</span> <span style="font-family:monospace; font-weight: bold;">type</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>content-type</code></em></span>?</div></div>
+ </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
+ This command sets the <code class="constant">Content-type</code>
+ 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.
+ </div></div></dd><dt><span class="term">
+ <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">headers</span> <span style="font-family:monospace; font-weight: bold;">numeric</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>response code</code></em></span>?</div></div>
+ </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">Set a numeric response code, such as 200, 404 or 500.
+ </div></div></dd></dl></div></div></div><div class="refentry" title="makeurl"><div class="refentry.separator"><hr></div><a name="makeurl"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>makeurl — construct url's based on hostname, port.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">makeurl</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>filename</code></em></span>?</div></div></div><div class="refsect1" title="Description"><a name="id475713"></a><h2>Description</h2><p style="width:90%">
+ Create a self referencing URL from a filename. For example:
+ </p><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting">makeurl /tclp.gif</pre><p style="width:90%">
+ returns
+ <code class="computeroutput">http://[hostname]:[port]/tclp.gif</code>.
+ where hostname and port are the hostname and port of the
+ server in question.
+ </p></div></div><div class="refentry" title="cookie"><div class="refentry.separator"><hr></div><a name="cookie"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>cookie — get and set cookies.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">cookie</span> ?<span style="font-family:monospace; font-weight: bold;">set</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>cookieName</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>?<span class="optional">cookiValue</span>?</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;">-days <em class="replaceable"><code>expireInDays</code></em></span>? ?<span style="font
-family:monospace; font-weight: bold;">-hours <em class="replaceable"><code>expireInHours</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;">-minutes <em class="replaceable"><code>expireInMinutes</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;">-expires <em class="replaceable"><code>Wdy, DD-Mon-YYYY HH:MM:SS GMT</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;">-path <em class="replaceable"><code>uriPathCookieAppliesTo</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;">-secure <em class="replaceable"><code>1/0</code></em></span>?</div></div><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">cookie</span> ?<span style="font-family:monospace; font-weight: bold;">get</span>? ?<span style="font-family:monospace; font-weight: b
old;"><em class="replaceable"><code>cookieName</code></em></span>?</div></div></div><div class="refsect1" title="Description"><a name="id475870"></a><h2>Description</h2><p style="width:90%">
+ <span style="font-family:monospace"><span class="command"><strong>cookie</strong></span></span> 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.
+ </p></div></div><div class="refentry" title="clock_to_rfc850_gmt"><div class="refentry.separator"><hr></div><a name="clock_to_rfc"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>clock_to_rfc850_gmt — create a rfc850 time from [clock seconds].</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">clock_to_rfc850_gmt</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>seconds</code></em></span>?</div></div></div><div class="refsect1" title="Description"><a name="id475923"></a><h2>Description</h2><p style="width:90%">
+ Convert an integer-seconds-since-1970 click value to
+ RFC850 format, with the additional requirement that it be
+ GMT only.
+ </p></div></div><div class="refentry" title="html"><div class="refentry.separator"><hr></div><a name="html"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>html — construct html tagged text.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">html</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>string</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>arg</code></em></span>...?</div></div></div><div class="refsect1" title="Description"><a name="id475978"></a><h2>Description</h2><p style="width:90%">
+ Print text with the added ability to pass HTML tags
+ following the string. Example:
+ </p><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting">html "Test" b i</pre><p style="width:90%">
+ produces: <code class="computeroutput"><b><i>Test</i></b></code>
+ </p></div></div><div class="refentry" title="incr0"><div class="refentry.separator"><hr></div><a name="incr0"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>incr0 — increment a variable or set it to 1 if nonexistant.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">incr0</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>varname</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>num</code></em></span>?</div></div></div><div class="refsect1" title="Description"><a name="id476044"></a><h2>Description</h2><p style="width:90%">
+ Increment a variable
+ <em class="replaceable"><code>varname</code></em> by
+ <em class="replaceable"><code>num</code></em>. If the
+ variable doesn't exist, create it instead of returning an
+ error.
+ </p></div></div><div class="refentry" title="parray"><div class="refentry.separator"><hr></div><a name="parray"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>parray — Tcl's <span style="font-family:monospace"><span class="command"><strong>parray</strong></span></span> with html formatting.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">parray</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>arrayName</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>?<span class="optional">pattern</span>?</code></em></span>?</div></div></div><div class="refsect1" title="Description"><a name="id476114"></a><h2>Description</h2><p style="wi
dth:90%">
+ An html version of the standard Tcl
+ <span style="font-family:monospace"><span class="command"><strong>parray</strong></span></span> command. Displays the entire
+ contents of an array in a sorted, nicely-formatted way.
+ Mostly used for debugging purposes.
+ </p></div></div><div class="refentry" title="abort_page"><div class="refentry.separator"><hr></div><a name="abort_page"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>abort_page — Stops outputing data to web page, similar in
+ purpose to PHP's <span style="font-family:monospace"><span class="command"><strong>die</strong></span></span> command.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">abort_page</span> </div></div></div><div class="refsect1" title="Description"><a name="id476165"></a><h2>Description</h2><p style="width:90%">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
+ <span style="font-family:monospace"><span class="command"><strong>exit</strong></span></span> command, but that cannot be used in
+ Rivet without actually exiting the apache child
+ process!</p></div></div><div class="refentry" title="no_body"><div class="refentry.separator"><hr></div><a name="no_body"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>no_body — Prevents Rivet from sending any content.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">no_body</span> </div></div></div><div class="refsect1" title="Description"><a name="id476210"></a><h2>Description</h2><p style="width:90%">
+ 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.
+ </p></div></div><div class="refentry" title="escape_string"><div class="refentry.separator"><hr></div><a name="escape_string"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>escape_string — convert a string into escaped characters.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">escape_string</span> ?<span style="font-family:monospace; font-weight: bold;">string</span>?</div></div></div><div class="refsect1" title="Description"><a name="id476257"></a><h2>Description</h2><p style="width:90%">
+ 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.
+ </p><p style="width:90%">
+ This is useful for quoting strings that are going to be
+ part of a URL.
+ </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top">
+ You must require the Rivet package in order to gain access to this command
+ </td></tr></table></div></div></div><div class="refentry" title="escape_sgml_chars"><div class="refentry.separator"><hr></div><a name="escape_sgml_chars"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>escape_sgml_chars — escape special SGML characters in a string.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">escape_sgml_chars</span> ?<span style="font-family:monospace; font-weight: bold;">string</span>?</div></div></div><div class="refsect1" title="Description"><a name="id476312"></a><h2>Description</h2><p style="width:90%">
+ 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.
+ </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top">
+ You must require the Rivet package in order to gain access to this command
+ </td></tr></table></div></div></div><div class="refentry" title="escape_shell_command"><div class="refentry.separator"><hr></div><a name="escape_shell_command"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>escape_shell_command — escape shell metacharacters in a string.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">escape_shell_command</span> ?<span style="font-family:monospace; font-weight: bold;">string</span>?</div></div></div><div class="refsect1" title="Description"><a name="id476364"></a><h2>Description</h2><p style="width:90%">
+ 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.
+ </p><p style="width:90%">
+ For each metacharacter found, it is quoted in the result by
+ prepending it with a backslash, returning the result.
+ </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top">
+ You must require the Rivet package in order to gain access to this command
+ </td></tr></table></div></div></div><div class="refentry" title="unescape_string"><div class="refentry.separator"><hr></div><a name="unescape_string"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>unescape_string — unescape escaped characters in a string.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">unescape_string</span> ?<span style="font-family:monospace; font-weight: bold;">string</span>?</div></div></div><div class="refsect1" title="Description"><a name="id476420"></a><h2>Description</h2><p style="width:90%">
+ 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.
+ </p><p style="width:90%">
+ This is useful for unquoting strings that have been quoted to
+ be part of a URL.
+ </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top">
+ You must require the Rivet package in order to gain access to this command
+ </td></tr></table></div></div></div></div><div class="section" title="Examples and Usage"><div class="titlepage"><div><div><hr><h2 class="title" style="clear: both"><a name="examples"></a>Examples and Usage</h2></div></div></div><p style="width:90%">
+ Some examples of Rivet usage follow. Some prior Tcl knowledge
+ is assumed. If you don't know much Tcl, don't worry, it's easy,
+ and there are some good resources available on the web that will
+ get you up to speed quickly. Go to the <a class="link" href="#websites" title="Web Sites">web sites</a> section and have a look.
+ </p><div class="example"><a name="hello%20world"></a><p class="title"><b>Example 1. Hello World</b></p><div class="example-contents"><p style="width:90%">
+ As with any tool, it's always nice to see something work, so
+ let's create a small "Hello World" page.</p><p style="width:90%">
+ Assuming you have Apache configured correctly, create a file
+ called <code class="filename">hello.rvt</code> where Apache can find
+ it, with the following content:
+ </p><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting"><?
+puts "Hello World"
+?>
+</pre><p style="width:90%">
+ If you then access it with your browser, you should see a
+ blank page with the text "Hello World" (without the quotes) on
+ it.
+ </p></div></div><br class="example-break"><div class="example"><a name="id478912"></a><p class="title"><b>Example 2. Generate a Table</b></p><div class="example-contents"><p style="width:90%">
+ In another simple example, we dynamically generate a table:
+ </p><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting"><? puts "<table>\n"
+for {set i 1} { $i <= 8 } {incr i} {
+ puts "<tr>\n"
+ for {set j 1} {$j <= 8} {incr j} {
+ set num [ expr $i * $j * 4 - 1]
+ puts [ format "<td bgcolor=\"%02x%02x%02x\" > $num $num $num </td>\n" \
+ $num $num $num ]
+ }
+ puts "</tr>\n"
+}
+puts "</table>\n" ?>
+</pre><p style="width:90%">
+ If you read the code, you can see that this is pure Tcl. We
+ could take the same code, run it outside of Rivet, and it
+ would generate the same HTML!
+ </p><p style="width:90%">
+ The result should look something like this:
+ </p><div><img src="table.png"></div></div></div><br class="example-break"><div class="example"><a name="variable_access"></a><p class="title"><b>Example 3. Variable Access</b></p><div class="example-contents"><p style="width:90%">
+ Here, we demonstrate how to access variables set by GET or
+ POST operations.
+ </p><p style="width:90%">
+ Given an HTML form like the following:
+ </p><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting"> <form action="vars.rvt">
+ <table>
+ <tbody>
+ <tr>
+ <td><b>Title:</b></td>
+ <td><input name="title"></td>
+ </tr>
+ <tr>
+ <td><b>Salary:</b></td>
+ <td><input name="salary"></td>
+ </tr>
+ <tr>
+ <td><b>Boss:</b></td>
+ <td><input name="boss"></td></tr>
+ <tr>
+ <td><b>Skills:</b></td>
+ <td>
+ <select name="skills" multiple="multiple">
+ <option>c</option>
+ <option>java</option>
+ <option>Tcl</option>
+ <option>Perl</option>
+ </select>
+ </td>
+ </tr>
+ <tr>
+ <td><input type="submit"></td>
+ </tr>
+ </tbody>
+ </table>
+ </form>
+</pre><p style="width:90%">
+ We can use this Rivet script to get the variable values:
+ </p><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting"><?
+set errlist {}
+if { [var exists title] } {
+ set title [var get title]
+} else {
+ set errlist "You need to enter a title"
+}
+
+if { [var exists salary] } {
+ set salary [var get salary]
+ if { ! [string is digit $salary] } {
+ lappend errlist "Salary must be a number"
+ }
+} else {
+ lappend errlist "You need to enter a salary"
+}
+
+if { [var exists boss] } {
+ set boss [var get boss]
+} else {
+ set boss "Mr. Burns"
+}
+
+if { [var exists skills] } {
+ set skills [var list skills]
+} else {
+ lappend errlist "You need to enter some skills"
+}
+
+if { [llength $errlist] != 0 } {
+ foreach err $errlist {
+ puts "<b> $err </b>"
+ }
+} else {
+ puts "Thanks for the information!"
+ ?>
+ <table>
+ <tbody>
+ <tr>
+ <td><b>Title:</b></td>
+ <td><? puts $title ?></td>
+ </tr>
+ <tr>
+ <td><b>Boss:</b></td>
+ <td><? puts $boss ?></td>
+ </tr>
+ <tr>
+ <td><b>Salary:</b></td>
+ <td><? puts $salary ?></td>
+ </tr>
+ <tr>
+ <td><b>Skills:</b></td>
+ <td><? puts $skills ?></td>
+ </tr>
+ </tbody>
+ </table>
+ <?
+}
+?>
+</pre><p style="width:90%">
+ The first statement checks to make sure that the
+ <code class="varname">boss</code> variable has been passed to the
+ script, and then does something with that information. If
+ it's not present, an error is added to the list of errors.
+ </p><p style="width:90%">
+ In the second block of code, the variable
+ <code class="varname">salary</code> is fetched, with one more error
+ check - because it's a number, it needs to be composed of
+ digits.
+ </p><p style="width:90%">
+ The <code class="varname">boss</code> variable isn't required to have
+ been sent - we set it to "Mr. Burns" if it isn't among the
+ information we received.
+ </p><p style="width:90%">
+ The last bit of variable handing code is a bit trickier.
+ Because <code class="varname">skills</code> is a listbox, and can
+ potentially have multiple values, we opt to receive them as a
+ list, so that at some point, we could iterate over them.
+ </p><p style="width:90%">
+ The script then checks to make sure that
+ <code class="varname">errlist</code> is empty and outputting a thankyou
+ message. If <code class="varname">errlist</code> is not empty, the list
+ of errors it contains is printed.
+ </p></div></div><br class="example-break"><div class="example"><a name="file_upload"></a><p class="title"><b>Example 4. File Upload</b></p><div class="example-contents"><p style="width:90%">
+ The <span style="font-family:monospace"><span class="command"><strong>upload</strong></span></span> command endows Rivet with an
+ interface to access files transferred over http as parts of a
+ multipart form. The following HTML in one file, say,
+ <code class="filename">upload.html</code> creates a form with a text
+ input entry. By clicking the file chooser button the file
+ browser shows up and the user selects the file to be uploaded
+ (the file path will appear in the text input). In order to make
+ sure you're uploading the whole file you must combine the
+ action of the enctype and method attributes of the
+ <form...> tag in the way shown in the example. Failure
+ to do so would result in the client sending only the file's
+ path, rather than the actual contents.
+ </p><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting"><form action="foo.rvt" enctype="multipart/form-data" method="post">
+<input type="file" name="MyUpload"></input>
+<input type="submit" value="Send File"></input>
+</form>
+</pre><p style="width:90%">
+ In the script invoked by the form
+ (<code class="filename">upload.rvt</code>) <span style="font-family:monospace"><span class="command"><strong>upload</strong></span></span>
+ ?<span style="font-family:monospace; font-weight: bold;">argument ...</span>? commands can be used to manipulate the
+ various files uploaded.
+ </p><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting"><?
+upload save MyUpload /tmp/uploadfiles/file1
+puts "Saved file [upload filename MyUpload] \
+ ([upload size MyUpload] bytes) to server"
+?></pre><p style="width:90%">
+ Don't forget that the apache server must have write access to
+ the directory where files are being created. The Rivet Apache
+ directives have a substantial impact on the upload process,
+ you have to carefully read the docs in order to set the
+ appropriate directives values that would match your
+ requirements.
+ </p><p style="width:90%">
+ It is also important to understand that some
+ <span style="font-family:monospace"><span class="command"><strong>upload</strong></span></span> commands are effective only when
+ used in a mutually exclusive way. Apache stores the data in
+ temporary files which are read by the <span style="font-family:monospace"><span class="command"><strong>upload save
+ ?<span style="font-family:monospace; font-weight: bold;">upload name</span>? ?<span style="font-family:monospace; font-weight: bold;">filename</span>?</strong></span></span> or by the
+ <span style="font-family:monospace"><span class="command"><strong>upload data ?<span style="font-family:monospace; font-weight: bold;">upload name</span>?</strong></span></span>
+ command. Subsequent calls to these 2 commands using the same
+ ?<span style="font-family:monospace; font-weight: bold;">upload name</span>? argument will return no data on the
+ second call. Likewise <span style="font-family:monospace"><span class="command"><strong>upload channel ?<span style="font-family:monospace; font-weight: bold;">upload
+ name</span>?</strong></span></span> will return a Tcl file channel that you
+ can use in regular Tcl scripts only if you haven't already
[... 1339 lines stripped ...]
---------------------------------------------------------------------
To unsubscribe, e-mail: site-cvs-unsubscribe@tcl.apache.org
For additional commands, e-mail: site-cvs-help@tcl.apache.org