You are viewing a plain text version of this content. The canonical link for it is here.
Posted to rivet-dev@tcl.apache.org by mx...@apache.org on 2011/09/07 00:07:27 UTC
svn commit: r1165899 - in /tcl/rivet/trunk: ChangeLog doc/xml/commands.xml
Author: mxmanghi
Date: Tue Sep 6 22:07:26 2011
New Revision: 1165899
URL: http://svn.apache.org/viewvc?rev=1165899&view=rev
Log:
2011-09-07 Massimo Manghi <mx...@apache.org>
* doc/xml/commands.xml: Add existing undocumented commands
- import_keyvalue_pairs
- lempty
- lmatch
- lassign (consider to remove, as it overlaps for name and features
with identical Tcl core command)
- read_file
- wrap
- wrapline
Changed 'makeurl' documentation to account for new features recently committed
Modified:
tcl/rivet/trunk/ChangeLog
tcl/rivet/trunk/doc/xml/commands.xml
Modified: tcl/rivet/trunk/ChangeLog
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/ChangeLog?rev=1165899&r1=1165898&r2=1165899&view=diff
==============================================================================
--- tcl/rivet/trunk/ChangeLog (original)
+++ tcl/rivet/trunk/ChangeLog Tue Sep 6 22:07:26 2011
@@ -1,3 +1,15 @@
+2011-09-07 Massimo Manghi <mx...@apache.org>
+ * doc/xml/commands.xml: Add existing undocumented commands
+ - import_keyvalue_pairs
+ - lempty
+ - lmatch
+ - lassign (consider to remove, as it overlaps for name and features
+ with identical Tcl core command)
+ - read_file
+ - wrap
+ - wrapline
+ Changed 'makeurl' documentation to account for new features recently committed
+
2011-09-06 Massimo Manghi <mx...@apache.org>
* src/apache-2/mod_rivet.c: Add Id svn keyword.
* src/apache-2/TclWebapache.c: Command load_env and load_headers now resolve
Modified: tcl/rivet/trunk/doc/xml/commands.xml
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/xml/commands.xml?rev=1165899&r1=1165898&r2=1165899&view=diff
==============================================================================
--- tcl/rivet/trunk/doc/xml/commands.xml (original)
+++ tcl/rivet/trunk/doc/xml/commands.xml Tue Sep 6 22:07:26 2011
@@ -1,551 +1,510 @@
<section id="commands">
<title>Rivet Tcl Commands and Variables</title>
- <refentry id="var">
+ <refentry id="abort_code">
+ <refnamediv>
+ <refname>abort_code</refname>
+ <refpurpose>
+ Returns the code passed to <command>abort_page</command>
+ earlier during the request processing
+ </refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>abort_code</command>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+ Usage of this command is meaningful only in scripts run as
+ AbortScript or AfterEveryScript.
+ <command>abort_code</command> returns the value of the optional
+ parameter passed to <command>abort_page</command> earlier during
+ the same request processing.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id="abort_page">
+ <refnamediv>
+ <refname>abort_page</refname>
+ <refpurpose>
+ Stops outputing data to web page, similar in
+ purpose to PHP's <command>die</command> command.
+ </refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>abort_page</command>
+ <group choice="req">
+ <arg><replaceable>abort code</replaceable></arg>
+ <arg><replaceable>-aborting</replaceable></arg>
+ </group>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+ <para>
+ 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
+ <command>exit</command> command, but that cannot be used in
+ Rivet without actually exiting the apache child
+ process!
+ <command>abort_page</command> triggers
+ the execution of an optional AbortScript that has to be
+ specified in the configuration. The value of the
+ argument <arg>abort code</arg> can be retrieved with the
+ <command>abort_code</command> command during the
+ execution of AbortScript or AfterEveryScript, allowing
+ the script to take appropriate actions in order to deal
+ with the cause of the abort.
+ </para>
+ <para>
+ When passed the argument <command>-aborting</command> the
+ command returns 1 if <option>abort_page</option>
+ had been called earlier in the request processing, thus
+ providing a tool for code in AfterEveryScript to tell
+ if the an abort condition took place.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="apache_log_error">
<refnamediv>
- <refname>var</refname>
- <refname>var_qs</refname>
- <refname>var_post</refname>
- <refpurpose>get the value of a form variable.</refpurpose>
+ <refname>apache_log_error</refname>
+ <refpurpose>log messages to the Apache error log</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
- <command>var</command>
- <group choice="req">
- <arg>get</arg>
- <arg>list</arg>
- <arg>exists</arg>
- <arg>number</arg>
- <arg>all</arg>
- </group>
- </cmdsynopsis>
-
- <cmdsynopsis>
- <command>var_qs</command>
- <group choice="req">
- <arg>get</arg>
- <arg>list</arg>
- <arg>exists</arg>
- <arg>number</arg>
- <arg>all</arg>
- </group>
- </cmdsynopsis>
-
- <cmdsynopsis>
- <command>var_post</command>
- <group choice="req">
- <arg>get</arg>
- <arg>list</arg>
- <arg>exists</arg>
- <arg>number</arg>
- <arg>all</arg>
- </group>
+ <command>apache_log_error</command>
+ <arg>priority</arg>
+ <arg>message</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
- <para>
- The <command>var</command> 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 <command>var</command>:
- <command>var_qs</command> and <command>var_post</command>.
- These two restrict the retrieval of information to
- parameters arriving via the querystring
- (?foo=bar&bee=bop) or POSTing, respectively.
+ <para>The apache_log_error command logs a message to the
+ Apache error log, whose name and location have been
+ set by the <option>ErrorLog</option> directive.
</para>
- <variablelist>
- <varlistentry>
- <term>
- <cmdsynopsis>
- <command>var</command>
- <arg choice="plain">get</arg>
- <arg><replaceable>varname</replaceable></arg>
- <arg><replaceable><optional>default</optional></replaceable></arg>
- </cmdsynopsis>
- </term>
- <listitem>
- <para>
- Returns the value of variable
- <option><replaceable>varname</replaceable></option>
- as a string (even if there are multiple values). If
- the variable doesn't exist as a GET or POST
- variable, the
- <option><replaceable><optional>default</optional></replaceable></option>
- value is returned, otherwise "" - an empty string -
- is returned.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <cmdsynopsis>
- <command>var</command>
- <arg choice="plain">list</arg>
- <arg><replaceable>varname</replaceable></arg>
- </cmdsynopsis>
- </term>
- <listitem>
- <para>
- Returns the value of variable
- <option><replaceable>varname</replaceable></option> as a
- list, if there are multiple values.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <cmdsynopsis>
- <command>var</command>
- <arg choice="plain">exists</arg>
- <arg><replaceable>varname</replaceable></arg>
- </cmdsynopsis>
- </term>
- <listitem>
- <para>
- Returns 1 if
- <option><replaceable>varname</replaceable></option>
- exists, 0 if it doesn't.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <cmdsynopsis>
- <command>var</command>
- <arg choice="plain">number</arg>
- </cmdsynopsis>
- </term>
- <listitem>
- <para>
- Returns the number of variables.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <cmdsynopsis>
- <command>var</command>
- <arg choice="plain">all</arg>
- </cmdsynopsis>
- </term>
- <listitem>
- <para>
- Return a list of variable names and values.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
<para>
- See <xref linkend="variable_access"/>.
+ Priority must be one of
+ <option>debug</option>,
+ <option>info</option>,
+ <option>notice</option>,
+ <option>warning</option>,
+ <option>err</option>,
+ <option>crit</option>,
+ <option>alert</option>, or
+ <option>emerg</option>.
</para>
-
</refsect1>
</refentry>
- <refentry id="upload">
+ <refentry id="apache_table">
<refnamediv>
- <refname>upload</refname>
- <refpurpose>handle a file uploaded by a client.</refpurpose>
+ <refname>apache_table</refname>
+ <refpurpose>access and manipulate Apache tables in the request structure.</refpurpose>
</refnamediv>
<refsynopsisdiv>
- <cmdsynopsis>
- <command>upload</command>
- <group choice="req">
- <arg>channel</arg>
- <arg>save</arg>
- <arg>data</arg>
- <arg>exists</arg>
- <arg>size</arg>
- <arg>type</arg>
- <arg>filename</arg>
- </group>
- </cmdsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Description</title>
- <para>The upload command is for file upload manipulation.
- See the relevant Apache Directives to further configure the
- behavior of this Rivet feature.
- </para>
+ <cmdsynopsis>
+ <command>apache_table</command>
+ <group choice="req">
+ <arg>get</arg>
+ <arg>set</arg>
+ <arg>exists</arg>
+ <arg>unset</arg>
+ <arg>names</arg>
+ <arg>array_get</arg>
+ <arg>clear</arg>
+ </group>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+ <para>The apache_table command is for accessing and manipulating
+ Apache tables in the request structure.
+ </para>
+ <para>
+ The table name must be one of
+ <option>notes</option>,
+ <option>headers_in</option>,
+ <option>headers_out</option>,
+ <option>err_headers_out</option>, or
+ <option>subprocess_env</option>.
+ </para>
<variablelist>
<varlistentry>
<term>
- <cmdsynopsis>
- <command>upload</command>
- <arg choice="plain">channel</arg>
- <arg><replaceable>uploadname</replaceable></arg>
+ <cmdsynopsis>
+ <command>apache_table</command>
+ <arg choice="plain">get</arg>
+ <arg><replaceable>tablename</replaceable></arg>
+ <arg><replaceable>key</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ When given the name of an Apache table
+ <option><replaceable>tablename</replaceable></option>
+ and the name of a key
+ <option><replaceable>tablename</replaceable></option>,
+ returns the value of the key in the table, or an empty
+ string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <command>apache_table</command>
+ <arg choice="plain">set</arg>
+ <arg><replaceable>tablename</replaceable></arg>
+ <arg><replaceable>key</replaceable></arg>
+ <arg><replaceable>value</replaceable></arg>
</cmdsynopsis>
- </term>
- <listitem>
- <para>
- When given the name of a file upload
- <option><replaceable>uploadname</replaceable></option>,
- returns a Tcl channel that can be used to access the
- uploaded file.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
<cmdsynopsis>
- <command>upload</command>
- <arg choice="plain">save</arg>
- <arg><replaceable>uploadname</replaceable></arg>
- <arg><replaceable>filename</replaceable></arg>
+ <command>apache_table</command>
+ <arg choice="plain">set</arg>
+ <arg><replaceable>tablename</replaceable></arg>
+ <arg><replaceable>list</replaceable></arg>
</cmdsynopsis>
</term>
<listitem>
<para>
- Saves the
- <option><replaceable>uploadname</replaceable></option> in
- the file
- <option><replaceable>filename</replaceable></option>.
+ Stores the
+ <option><replaceable>value</replaceable></option> in
+ the table
+ <option><replaceable>tablename</replaceable></option>
+ under the key
+ <option><replaceable>key</replaceable></option>.
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <cmdsynopsis>
- <command>upload</command>
- <arg choice="plain">data</arg>
- <arg><replaceable>uploadname</replaceable></arg>
- </cmdsynopsis>
- </term>
- <listitem>
<para>
- 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.
+ For the list form,
+ <option><replaceable>list</replaceable></option> contains
+ a list of zero or more pairs of key-value pairs to be
+ set into the table
+ <option><replaceable>tablename</replaceable></option>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
- <command>upload</command>
+ <command>apache_table</command>
<arg choice="plain">exists</arg>
- <arg><replaceable>uploadname</replaceable></arg>
- </cmdsynopsis>
- </term>
- <listitem>
- <para>
- Returns true if an upload named <arg>uploadname</arg>
- 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.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <cmdsynopsis>
- <command>upload</command>
- <arg choice="plain">size</arg>
- <arg><replaceable>uploadname</replaceable></arg>
+ <arg><replaceable>tablename</replaceable></arg>
+ <arg><replaceable>key</replaceable></arg>
</cmdsynopsis>
</term>
<listitem>
<para>
- Returns the size of the file uploaded.
+ Returns 1 if the specified key,
+ <option><replaceable>key</replaceable></option>,
+ exists in table
+ <option><replaceable>tablename</replaceable></option>,
+ else 0.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
- <command>upload</command>
- <arg choice="plain">type</arg>
+ <command>apache_table</command>
+ <arg choice="plain">unset</arg>
+ <arg><replaceable>tablename</replaceable></arg>
+ <arg><replaceable>key</replaceable></arg>
</cmdsynopsis>
</term>
<listitem>
<para>
- If the <varname>Content-type</varname> is set, it is
- returned, otherwise, an empty string.
+ Removes the key-value pair referenced by
+ <option><replaceable>key</replaceable></option>
+ from the table
+ <option><replaceable>tablename</replaceable></option>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
- <command>upload</command>
- <arg choice="plain">filename</arg>
- <arg><replaceable>uploadname</replaceable></arg>
+ <command>apache_table</command>
+ <arg choice="plain">names</arg>
+ <arg><replaceable>tablename</replaceable></arg>
</cmdsynopsis>
</term>
<listitem>
<para>
- Returns the filename on the remote host that uploaded the file.
+ Returns a list of all of the keys present in the table
+ <option><replaceable>tablename</replaceable></option>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
- <command>upload</command>
- <arg choice="plain">tempname</arg>
- <arg><replaceable>uploadname</replaceable></arg>
+ <command>apache_table</command>
+ <arg choice="plain">array_get</arg>
+ <arg><replaceable>tablename</replaceable></arg>
</cmdsynopsis>
</term>
<listitem>
<para>
- Returns the name of the temporary file on the local host that the file was uploaded into.
+ Returns a list of key-value pairs from the table
+ <option><replaceable>tablename</replaceable></option>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
- <command>upload</command>
- <arg choice="plain">names</arg>
+ <command>apache_table</command>
+ <arg choice="plain">clear</arg>
+ <arg><replaceable>tablename</replaceable></arg>
</cmdsynopsis>
</term>
<listitem>
<para>
- Returns the variable names, as a list, of all the files
- uploaded.
+ Clears the contents of the specified table.
</para>
</listitem>
</varlistentry>
</variablelist>
-
- <para>
- See <xref linkend="upload"/>.
- </para>
</refsect1>
</refentry>
- <refentry id="raw_post">
- <refnamediv>
- <refname>raw_post</refname>
- <refpurpose>get the unmodified body of a POST request sent by the client.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <cmdsynopsis>
- <command>raw_post</command>
- </cmdsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Description</title>
- </refsect1>
- <para>
- Returns the raw POST data from the request. If the request was
- not a POST or there is no data, then "" - an empty string - is returned.
- </para>
- </refentry>
-
- <refentry id="load_response">
+ <refentry id="clock_to_rfc">
<refnamediv>
- <refname>load_response</refname>
- <refpurpose>load form variables into an array.</refpurpose>
+ <refname>clock_to_rfc850_gmt</refname>
+ <refpurpose>create a rfc850 time from [clock seconds].</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
- <command>load_response</command>
- <arg><replaceable>arrayName</replaceable></arg>
+ <command>clock_to_rfc850_gmt</command>
+ <arg><replaceable>seconds</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
- <title>Description</title>
- <para>
- Load any form variables passed to this page into an
- array. If <command>load_response</command> is called without
- arguments the array <option>response</option> 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. <command>load_response</command>
- 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 <command>load_response</command> 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.
- </para>
- </refsect1>
- </refentry>
-
- <refentry id="load_headers">
- <refnamediv>
- <refname>load_headers</refname>
- <refpurpose>get client request's headers.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <cmdsynopsis>
- <command>load_headers</command>
- <arg><replaceable>array_name</replaceable></arg>
- </cmdsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
<title>Description</title>
<para>
- Load the headers that come from a client request into the
- provided array name, or use <option>headers</option> if no
- name is provided.
+ Convert an integer-seconds-since-1970 click value to
+ RFC850 format, with the additional requirement that it be
+ GMT only.
</para>
</refsect1>
</refentry>
- <refentry id="load_cookies">
+ <refentry id="cookie">
<refnamediv>
- <refname>load_cookies</refname>
- <refpurpose>get any cookie variables sent by the client.</refpurpose>
+ <refname>cookie</refname>
+ <refpurpose>get and set cookies.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
- <command>load_cookies</command>
- <arg choice="opt"><replaceable>array_name</replaceable></arg>
+ <command>cookie</command>
+ <arg>set</arg>
+ <arg><replaceable>cookieName</replaceable></arg>
+ <arg><replaceable><optional>cookiValue</optional></replaceable></arg>
+ <arg>-days <replaceable>expireInDays</replaceable></arg>
+ <arg>-hours <replaceable>expireInHours</replaceable></arg>
+ <arg>-minutes <replaceable>expireInMinutes</replaceable></arg>
+ <arg>-expires <replaceable>Wdy, DD-Mon-YYYY HH:MM:SS GMT</replaceable></arg>
+ <arg>-path <replaceable>uriPathCookieAppliesTo</replaceable></arg>
+ <arg>-secure <replaceable>1/0</replaceable></arg>
+ </cmdsynopsis>
+ <cmdsynopsis>
+ <command>cookie</command>
+ <arg>get</arg>
+ <arg><replaceable>cookieName</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
+ <para>
+ <command>cookie</command> 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.
+ </para>
</refsect1>
- <para>
- Load the array of cookie variables into the specified
- array name. Uses array <option>cookies</option> by
- default.
- </para>
</refentry>
- <refentry id="load_env">
+ <refentry id="debug">
+ <refnamediv>
+ <refname>debug</refname>
+ <refpurpose>
+ A command to print strings, arrays
+ and the values of variables as specified by the arguments.
+ </refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>debug</command>
+ <arg choice="plain">-subst</arg><arg><on|off></arg>
+ <arg choice="plain">-separator</arg><arg><string></arg>
+ <arg choice="plain">-option</arg><arg><replaceable><value></replaceable></arg>
+ <arg choice="plain">-option</arg><arg><replaceable><value></replaceable></arg>
+ <arg choice="plain">...</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+ <para>
+ A command to make debugging more convenient print strings, arrays
+ and the values of variables as specified by the arguments.
+ </para>
+ <para>
+ Also allows the setting of an array called debug which will pick up
+ options for all debug commands.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="env">
<refnamediv>
- <refname>load_env</refname>
- <refpurpose>get the request's environment variables.</refpurpose>
+ <refname>env</refname> <refpurpose>Loads a single
+ "environmental variable" into a Tcl variable.</refpurpose>
</refnamediv>
<refsynopsisdiv>
- <cmdsynopsis>
- <command>load_env</command>
- <arg choice="opt"><replaceable>array_name</replaceable></arg>
- </cmdsynopsis>
+ <cmdsynopsis>
+ <command>env</command>
+ <arg><replaceable>varName</replaceable></arg>
+ </cmdsynopsis>
</refsynopsisdiv>
<refsect1>
- <title>Description</title>
+ <title>Description</title>
- <para>
- Load the array of environment variables into the specified
- array name. Uses array <option>::request::env</option> by
- default.
- </para>
- <para>
- As Rivet pages are run in the <option>::request</option>
- namespace, it isn't necessary to qualify the array name
- for most uses - it's ok to access it as
- <option>env</option>.
- </para>
+ <para>
+ 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.
+ </para>
</refsect1>
</refentry>
- <refentry id="env">
+ <refentry id="escape_sgml_chars">
<refnamediv>
- <refname>env</refname> <refpurpose>Loads a single
- "environmental variable" into a Tcl variable.</refpurpose>
+ <refname>escape_sgml_chars</refname>
+ <refpurpose>escape special SGML characters in a string.</refpurpose>
</refnamediv>
<refsynopsisdiv>
- <cmdsynopsis>
- <command>env</command>
- <arg><replaceable>varName</replaceable></arg>
- </cmdsynopsis>
+ <cmdsynopsis>
+ <command>escape_sgml_chars</command>
+ <arg>string</arg>
+ </cmdsynopsis>
</refsynopsisdiv>
<refsect1>
- <title>Description</title>
-
- <para>
- 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.
- </para>
+ <title>Description</title>
+ <para>
+ 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.
+ </para>
+ <note>
+ You must require the Rivet package in order to gain access to this command
+ </note>
</refsect1>
</refentry>
- <refentry id="include">
+ <refentry id="escape_shell_command">
<refnamediv>
- <refname>include</refname>
- <refpurpose>includes a file into the output stream without modification.</refpurpose>
+ <refname>escape_shell_command</refname>
+ <refpurpose>escape shell metacharacters in a string.</refpurpose>
</refnamediv>
<refsynopsisdiv>
- <cmdsynopsis>
- <command>include</command>
- <arg><replaceable>filename_name</replaceable></arg>
- </cmdsynopsis>
+ <cmdsynopsis>
+ <command>escape_shell_command</command>
+ <arg>string</arg>
+ </cmdsynopsis>
</refsynopsisdiv>
<refsect1>
- <title>Description</title>
- <para>
- 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.
- </para>
+ <title>Description</title>
+ <para>
+ 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.
+ </para>
+ <para>
+ For each metacharacter found, it is quoted in the result by
+ prepending it with a backslash, returning the result.
+ </para>
+ <note>
+ You must require the Rivet package in order to gain access to this command
+ </note>
+
</refsect1>
</refentry>
- <refentry id="parse">
+ <refentry id="escape_string">
<refnamediv>
- <refname>parse</refname>
- <refpurpose>parses a Rivet template file.</refpurpose>
+ <refname>escape_string</refname>
+ <refpurpose>convert a string into escaped characters.</refpurpose>
</refnamediv>
<refsynopsisdiv>
- <cmdsynopsis>
- <command>parse</command>
- <arg><replaceable>filename</replaceable></arg>
- </cmdsynopsis>
+ <cmdsynopsis>
+ <command>escape_string</command>
+ <arg>string</arg>
+ </cmdsynopsis>
</refsynopsisdiv>
<refsect1>
- <title>Description</title>
- <para>
- Like the Tcl <command>source</command> command, but also
- parses for Rivet <? and ?> processing tags. Using
- this command, you can use one .rvt file from another.
- </para>
+ <title>Description</title>
+ <para>
+ 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.
+ </para>
+ <para>
+ This is useful for quoting strings that are going to be
+ part of a URL.
+ </para>
+ <note>
+ You must require the Rivet package in order to gain access to this command
+ </note>
</refsect1>
</refentry>
<refentry id="headers">
<refnamediv>
- <refname>headers</refname>
- <refpurpose>set and parse HTTP headers.</refpurpose>
+ <refname>headers</refname>
+ <refpurpose>set and parse HTTP headers.</refpurpose>
</refnamediv>
<refsynopsisdiv>
- <cmdsynopsis>
- <command>headers</command>
- <group choice="req">
- <arg>set</arg>
- <arg>redirect</arg>
- <arg>add</arg>
- <arg>type</arg>
- <arg>numeric</arg>
- </group>
- </cmdsynopsis>
+ <cmdsynopsis>
+ <command>headers</command>
+ <group choice="req">
+ <arg>set</arg>
+ <arg>redirect</arg>
+ <arg>add</arg>
+ <arg>type</arg>
+ <arg>numeric</arg>
+ </group>
+ </cmdsynopsis>
</refsynopsisdiv>
<refsect1>
@@ -638,613 +597,872 @@
</refsect1>
</refentry>
- <refentry id="makeurl">
+ <refentry id="html">
<refnamediv>
- <refname>makeurl</refname>
- <refpurpose>construct url's based on hostname, port.</refpurpose>
+ <refname>html</refname>
+ <refpurpose>construct html tagged text.</refpurpose>
</refnamediv>
<refsynopsisdiv>
- <cmdsynopsis>
- <command>makeurl</command>
- <arg><replaceable>filename</replaceable></arg>
- </cmdsynopsis>
+ <cmdsynopsis>
+ <command>html</command>
+ <arg><replaceable>string</replaceable></arg>
+ <arg rep="repeat"><replaceable>arg</replaceable></arg>
+ </cmdsynopsis>
</refsynopsisdiv>
<refsect1>
- <title>Description</title>
- <para>
- Create a self referencing URL from a filename. For example:
- <programlisting>makeurl /tclp.gif</programlisting>
- returns
- <computeroutput>http://[hostname]:[port]/tclp.gif</computeroutput>.
- where hostname and port are the hostname and port of the
- server in question.
- </para>
+ <title>Description</title>
+ <para>
+ Print text with the added ability to pass HTML tags
+ following the string. Example:
+ <programlisting>html "Test" b i</programlisting>
+ produces: <computeroutput><b><i>Test</i></b></computeroutput>
+ </para>
</refsect1>
</refentry>
- <!-- Reference page for command 'cookie' -->
- <refentry id="cookie">
+ <refentry id="import_keyvalue_pairs">
+ <refnamediv>
+ <refname>import_keyvalue_pairs</refname>
+ <refpurpose>Import an argument list into the named array</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>import_keyvalue_pairs</command>
+ <arg>arrayName</arg>
+ <arg>argsList</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+ key-value pairs, like "-foo bar" are stored in the array <arg>arrayName</arg>.
+ In that case, the value "bar" would be stored in the element "foo"
+ </para>
+ <para>
+ If "--" appears or a key doesn't begin with "-", the rest of the arg
+ list is stored in the special args element of the array.
+ </para>
+ <para>
+ Example:
+ <programlisting>import_keyvalue_pairs keyvalue_map [list -a1 v1 -a2 v2 -a3 v3 -- 1 2 3 4 5]
+parray keyvalue_map
+
+keyvalue_map(a1) = v1
+keyvalue_map(a2) = v2
+keyvalue_map(a3) = v3
+keyvalue_map(args) = 1 2 3 4 5</programlisting>
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id="include">
<refnamediv>
- <refname>cookie</refname>
- <refpurpose>get, set and delete cookies.</refpurpose>
+ <refname>include</refname>
+ <refpurpose>includes a file into the output stream without modification.</refpurpose>
</refnamediv>
<refsynopsisdiv>
- <cmdsynopsis>
- <command>cookie</command>
- <arg>set</arg>
- <arg><replaceable>cookieName</replaceable></arg>
- <arg><replaceable><optional>cookiValue</optional></replaceable></arg>
- <arg>-days <replaceable>expireInDays</replaceable></arg>
- <arg>-hours <replaceable>expireInHours</replaceable></arg>
- <arg>-minutes <replaceable>expireInMinutes</replaceable></arg>
- <arg>-expires <replaceable>Wdy, DD-Mon-YYYY HH:MM:SS GMT</replaceable></arg>
- <arg>-path <replaceable>uriPathCookieAppliesTo</replaceable></arg>
- <arg>-secure <replaceable>1/0</replaceable></arg>
- </cmdsynopsis>
- <cmdsynopsis>
- <command>cookie</command>
- <arg>get</arg>
- <arg><replaceable>cookieName</replaceable></arg>
- </cmdsynopsis>
- <cmdsynopsis>
- <command>cookie</command>
- <arg>delete</arg>
- <arg><replaceable>cookieName</replaceable></arg>
- </cmdsynopsis>
- <cmdsynopsis>
- <command>cookie</command>
- <arg>unset</arg>
- <arg><replaceable>cookieName</replaceable></arg>
- </cmdsynopsis>
+ <cmdsynopsis>
+ <command>include</command>
+ <arg><replaceable>filename_name</replaceable></arg>
+ </cmdsynopsis>
</refsynopsisdiv>
<refsect1>
- <title>Description</title>
- <para>
- <command>cookie</command> gets, sets, unsets or deletes a cookie. When you
- get a cookie, the command returns the value of the cookie,
- or an empty string if no cookie exists.
- </para>
- <para>
- <command>cookie delete</command> will set the timeout value to -1 minutes -
- deleting the cookie in the browser.
- </para>
- <para>
- <command>cookie unset</command> will remove the defined cookie in the server
- (perhaps preparatory to checking/resetting the cookie).
- </para>
+ <title>Description</title>
+ <para>
+ 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.
+ </para>
</refsect1>
</refentry>
- <!-- Reference page for command 'clock_to_rfc' -->
- <refentry id="clock_to_rfc">
+ <refentry id="incr0">
<refnamediv>
- <refname>clock_to_rfc850_gmt</refname>
- <refpurpose>create a rfc850 time from [clock seconds].</refpurpose>
+ <refname>incr0</refname>
+ <refpurpose>increment a variable or set it to 1 if nonexistant.</refpurpose>
</refnamediv>
<refsynopsisdiv>
- <cmdsynopsis>
- <command>clock_to_rfc850_gmt</command>
- <arg><replaceable>seconds</replaceable></arg>
- </cmdsynopsis>
+ <cmdsynopsis>
+ <command>incr0</command>
+ <arg><replaceable>varname</replaceable></arg>
+ <arg><replaceable>num</replaceable></arg>
+ </cmdsynopsis>
</refsynopsisdiv>
<refsect1>
- <title>Description</title>
- <para>
- Convert an integer-seconds-since-1970 click value to
- RFC850 format, with the additional requirement that it be
- GMT only.
- </para>
+ <title>Description</title>
+ <para>
+ Increment a variable
+ <option><replaceable>varname</replaceable></option> by
+ <option><replaceable>num</replaceable></option>. If the
+ variable doesn't exist, create it instead of returning an
+ error.
+ </para>
</refsect1>
</refentry>
- <refentry id="html">
+ <refentry id="lassign">
+ <refnamediv>
+ <refname>lassign</refname>
+ <refpurpose>Assign a list of values to a list of variables</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>lassign</command>
+ <arg>value_list</arg>
+ <arg>variables</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+ <command>lassign</command> emulates the TclX lassign command. It accepts
+ a list variables and treats the rest as a list of variable names that will
+ be assigned with the values in the caller's scope
+ </para>
+ <para>
+ <programlisting># lassign {1 2 3} a b c
+# set a
+1
+# set b
+2
+# set c
+3</programlisting>
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="lempty">
<refnamediv>
- <refname>html</refname>
- <refpurpose>construct html tagged text.</refpurpose>
+ <refname>lempty</refname>
+ <refpurpose>Returns 1 if <list> is empty or 0 if it has any elements.
+ This command emulates the TclX lempty command.
+ </refpurpose>
</refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>lempty</command>
+ <arg>list</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+ Returns 1 if <list> is empty or 0 if it has any elements.
+ This command emulates the TclX lempty command.
+ </para>
+ </refsect1>
+ </refentry>
- <refsynopsisdiv>
- <cmdsynopsis>
- <command>html</command>
- <arg><replaceable>string</replaceable></arg>
- <arg rep="repeat"><replaceable>arg</replaceable></arg>
- </cmdsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Description</title>
- <para>
- Print text with the added ability to pass HTML tags
- following the string. Example:
- <programlisting>html "Test" b i</programlisting>
- produces: <computeroutput><b><i>Test</i></b></computeroutput>
- </para>
- </refsect1>
- </refentry>
-
- <refentry id="incr0">
+ <refentry id="lmatch">
<refnamediv>
- <refname>incr0</refname>
- <refpurpose>increment a variable or set it to 1 if nonexistent.</refpurpose>
+ <refname>lmatch</refname>
+ <refpurpose>
+ Look for elements in <list> that match <pattern>
+ </refpurpose>
</refnamediv>
-
- <refsynopsisdiv>
+ <refsynopsisdiv>
<cmdsynopsis>
- <command>incr0</command>
- <arg><replaceable>varname</replaceable></arg>
- <arg><replaceable>num</replaceable></arg>
+ <command>lmatch</command>
+ <group choice="req">
+ <arg>-exact</arg>
+ <arg>-glob</arg>
+ <arg>-regexp</arg>
+ </group>
+ <arg>list</arg>
+ <arg>pattern</arg>
</cmdsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
+ </refsynopsisdiv>
+ <refsect1>
<title>Description</title>
<para>
- Increment a variable
- <option><replaceable>varname</replaceable></option> by
- <option><replaceable>num</replaceable></option>. If the
- variable doesn't exist, create it instead of returning an
- error.
+ Look for elements in <list> that match <pattern>.
+ This command emulates the TclX lmatch command, but if TclX isn't
+ available, it's a decent substitute.
</para>
- </refsect1>
- </refentry>
+ <para>
+ In the following example a regular expression is matched against
+ each element in the input list and a list containing the matching
+ elements is returned
+ </para>
+ <para>
+ <programlisting># lmatch -regexp lmatch -regexp { aaxa bxxb ccxxxxcc } {.+[x]{2}.+}
+bxxb ccxxxxcc
+ </programlisting>
+ </para>
+ </refsect1>
+ </refentry>
- <refentry id="parray">
+
+ <refentry id="load_cookies">
<refnamediv>
- <refname>parray</refname>
- <refpurpose>Tcl's <command>parray</command> with html formatting.</refpurpose>
+ <refname>load_cookies</refname>
+ <refpurpose>get any cookie variables sent by the client.</refpurpose>
</refnamediv>
<refsynopsisdiv>
- <cmdsynopsis>
- <command>parray</command>
- <arg><replaceable>arrayName</replaceable></arg>
- <arg><replaceable><optional>pattern</optional></replaceable></arg>
- </cmdsynopsis>
+ <cmdsynopsis>
+ <command>load_cookies</command>
+ <arg choice="opt"><replaceable>array_name</replaceable></arg>
+ </cmdsynopsis>
</refsynopsisdiv>
<refsect1>
- <title>Description</title>
- <para>
- An html version of the standard Tcl
- <command>parray</command> command. Displays the entire
- contents of an array in a sorted, nicely-formatted way.
- Mostly used for debugging purposes.
- </para>
-
+ <title>Description</title>
</refsect1>
+ <para>
+ Load the array of cookie variables into the specified
+ array name. Uses array <option>cookies</option> by
+ default.
+ </para>
</refentry>
- <refentry id="abort_page">
+ <refentry id="load_env">
<refnamediv>
- <refname>abort_page</refname>
- <refpurpose>
- Stops outputting data to web page, similar in
- purpose to PHP's <command>die</command> command.
- </refpurpose>
+ <refname>load_env</refname>
+ <refpurpose>get the request's environment variables.</refpurpose>
</refnamediv>
<refsynopsisdiv>
- <cmdsynopsis>
- <command>abort_page</command>
- <group choice="req">
- <arg><replaceable>abort code</replaceable></arg>
- <arg><replaceable>-aborting</replaceable></arg>
- </group>
- </cmdsynopsis>
+ <cmdsynopsis>
+ <command>load_env</command>
+ <arg choice="opt"><replaceable>array_name</replaceable></arg>
+ </cmdsynopsis>
</refsynopsisdiv>
<refsect1>
- <title>Description</title>
- <para>
- 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
- <command>exit</command> command, but that cannot be used in
- Rivet without actually exiting the apache child
- process!
- <command>abort_page</command> triggers
- the execution of an optional AbortScript that has to be
- specified in the configuration. The value of the
- argument <arg>abort code</arg> can be retrieved with the
- <command>abort_code</command> command during the
- execution of AbortScript or AfterEveryScript, allowing
- the script to take appropriate actions in order to deal
- with the cause of the abort.
- </para>
- <para>
- When passed the argument <option>-aborting</option> the
- command returns 1 if <option>abort_page</option>
- had been called earlier in the request processing, thus
- providing a tool for code in AfterEveryScript to tell
- if the an abort condition took place.
- </para>
+ <title>Description</title>
+
+ <para>
+ Load the array of environment variables into the specified
+ array name. Uses array <option>::request::env</option> by
+ default.
+ </para>
+ <para>
+ As Rivet pages are run in the <option>::request</option>
+ namespace, it isn't necessary to qualify the array name
+ for most uses - it's ok to access it as
+ <option>env</option>.
+ </para>
</refsect1>
- </refentry>
+ </refentry>
- <refentry id="abort_code">
- <refnamediv>
- <refname>abort_code</refname>
- <refpurpose>
- Returns the code passed to <command>abort_page</command>
- earlier during the request processing
- </refpurpose>
- </refnamediv>
- <refsynopsisdiv>
- <cmdsynopsis>
- <command>abort_code</command>
- </cmdsynopsis>
+ <refentry id="load_headers">
+ <refnamediv>
+ <refname>load_headers</refname>
+ <refpurpose>get client request's headers.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>load_headers</command>
+ <arg><replaceable>array_name</replaceable></arg>
+ </cmdsynopsis>
</refsynopsisdiv>
- <refsect1>
- <title>Description</title>
- <para>
- Usage of this command is meaningful only in code that runs as
- AbortScript or AfterEveryScript.
- <command>abort_code</command> returns the value of the optional
- parameter passed to <command>abort_page</command> earlier in
- the same request processing.
- </para>
+
+ <refsect1>
+ <title>Description</title>
+ <para>
+ Load the headers that come from a client request into the
+ provided array name, or use <option>headers</option> if no
+ name is provided.
+ </para>
</refsect1>
- </refentry>
-
- <refentry id="no_body">
+ </refentry>
+
+ <refentry id="load_response">
<refnamediv>
- <refname>no_body</refname>
- <refpurpose>Prevents Rivet from sending any content.</refpurpose>
+ <refname>load_response</refname>
+ <refpurpose>load form variables into an array.</refpurpose>
</refnamediv>
<refsynopsisdiv>
- <cmdsynopsis>
- <command>no_body</command>
- </cmdsynopsis>
+ <cmdsynopsis>
+ <command>load_response</command>
+ <arg><replaceable>arrayName</replaceable></arg>
+ </cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
- 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.
+ Load any form variables passed to this page into an
+ array. If <command>load_response</command> is called without
+ arguments the array <option>response</option> 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. <command>load_response</command>
+ 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 <command>load_response</command> 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.
</para>
- </refsect1>
- </refentry>
+ </refsect1>
+ </refentry>
- <refentry id="escape_string">
+ <refentry id="makeurl">
<refnamediv>
- <refname>escape_string</refname>
- <refpurpose>convert a string into escaped characters.</refpurpose>
+ <refname>makeurl</refname>
+ <refpurpose>construct url's based on hostname, port.</refpurpose>
</refnamediv>
<refsynopsisdiv>
- <cmdsynopsis>
- <command>escape_string</command>
- <arg>string</arg>
- </cmdsynopsis>
+ <cmdsynopsis>
+ <command>makeurl</command>
+ <arg><replaceable>filename</replaceable></arg>
+ </cmdsynopsis>
</refsynopsisdiv>
<refsect1>
- <title>Description</title>
- <para>
- 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.
- </para>
- <para>
- This is useful for quoting strings that are going to be
- part of a URL.
- </para>
- <note>
- You must require the Rivet package in order to gain access to this command
- </note>
+ <title>Description</title>
+ <para>
+ Create a self referencing URL from a filename. <command>makeurl</command>
+ can be used in three ways
+ <itemizedlist>
+ <listitem> No argument is passed to the command (returns the current script URL)</listitem>
+ <listitem>
+ A relative style path is passed (returns the argument prepended with the
+ current script's URL
+ </listitem>
+ <listitem>
+ An absolute path is passed to the command: (returns the full URL to the
+ resource)
+ </listitem>
+
+ </itemizedlist>
+ </para>
+ <para>
+ Example of absolute path: <programlisting>makeurl /tclp.gif</programlisting> returns
+ <computeroutput>http://[hostname]:[port]/tclp.gif</computeroutput>.
+ where hostname and port are the hostname and port of the
+ server in question.
+ </para>
</refsect1>
- </refentry>
+ </refentry>
- <refentry id="escape_sgml_chars">
+ <refentry id="no_body">
<refnamediv>
- <refname>escape_sgml_chars</refname>
- <refpurpose>escape special SGML characters in a string.</refpurpose>
+ <refname>no_body</refname>
+ <refpurpose>Prevents Rivet from sending any content.</refpurpose>
</refnamediv>
<refsynopsisdiv>
- <cmdsynopsis>
- <command>escape_sgml_chars</command>
- <arg>string</arg>
- </cmdsynopsis>
+ <cmdsynopsis>
+ <command>no_body</command>
+ </cmdsynopsis>
</refsynopsisdiv>
<refsect1>
- <title>Description</title>
- <para>
- 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.
- </para>
- <note>
- You must require the Rivet package in order to gain access to this command
- </note>
+ <title>Description</title>
+ <para>
+ 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.
+ </para>
</refsect1>
</refentry>
- <refentry id="escape_shell_command">
+ <refentry id="parray">
<refnamediv>
- <refname>escape_shell_command</refname>
- <refpurpose>escape shell metacharacters in a string.</refpurpose>
+ <refname>parray</refname>
+ <refpurpose>Tcl's <command>parray</command> with html formatting.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
- <command>escape_shell_command</command>
- <arg>string</arg>
+ <command>parray</command>
+ <arg><replaceable>arrayName</replaceable></arg>
+ <arg><replaceable><optional>pattern</optional></replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
- 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.
- </para>
- <para>
- For each metacharacter found, it is quoted in the result by
- prepending it with a backslash, returning the result.
+ An html version of the standard Tcl
+ <command>parray</command> command. Displays the entire
+ contents of an array in a sorted, nicely-formatted way.
+ Mostly used for debugging purposes.
</para>
- <note>
- You must require the Rivet package in order to gain access to this command
- </note>
</refsect1>
</refentry>
- <refentry id="unescape_string">
+ <refentry id="parse">
<refnamediv>
- <refname>unescape_string</refname>
- <refpurpose>unescape escaped characters in a string.</refpurpose>
+ <refname>parse</refname>
+ <refpurpose>parses a Rivet template file.</refpurpose>
</refnamediv>
<refsynopsisdiv>
- <cmdsynopsis>
- <command>unescape_string</command>
- <arg>string</arg>
- </cmdsynopsis>
+ <cmdsynopsis>
+ <command>parse</command>
+ <arg><replaceable>filename</replaceable></arg>
+ </cmdsynopsis>
</refsynopsisdiv>
<refsect1>
- <title>Description</title>
- <para>
- 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.
- </para>
- <para>
- This is useful for unquoting strings that have been quoted to
- be part of a URL.
- </para>
- <note>
- You must require the Rivet package in order to gain access to this command
- </note>
+ <title>Description</title>
+ <para>
+ Like the Tcl <command>source</command> command, but also
+ parses for Rivet <? and ?> processing tags. Using
+ this command, you can use one .rvt file from another.
+ </para>
</refsect1>
</refentry>
- <refentry id="apache_log_error">
+ <refentry id="read_file">
+ <refnamediv>
+ <refname>read_file</refname>
+ <refpurpose>
+ Read the entire contents of a file and return it as a string.
+ </refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>read_file</command>
+ <arg>file name</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+ This is a utility command which loads the entire content of
+ a file and returns it as a result.
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id="unescape_string">
<refnamediv>
- <refname>apache_log_error</refname>
- <refpurpose>log messages to the Apache error log</refpurpose>
+ <refname>unescape_string</refname>
+ <refpurpose>unescape escaped characters in a string.</refpurpose>
</refnamediv>
<refsynopsisdiv>
- <cmdsynopsis>
- <command>apache_log_error</command>
- <arg>priority</arg>
- <arg>message</arg>
- </cmdsynopsis>
+ <cmdsynopsis>
+ <command>unescape_string</command>
+ <arg>string</arg>
+ </cmdsynopsis>
</refsynopsisdiv>
<refsect1>
- <title>Description</title>
- <para>The apache_log_error command logs a message to the
- Apache error log, whose name and location have been
- set by the <option>ErrorLog</option> directive.
- </para>
- <para>
- Priority must be one of
- <option>debug</option>,
- <option>info</option>,
- <option>notice</option>,
- <option>warning</option>,
- <option>err</option>,
- <option>crit</option>,
- <option>alert</option>, or
- <option>emerg</option>.
- </para>
+ <title>Description</title>
+ <para>
+ 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.
+ </para>
+ <para>
+ This is useful for unquoting strings that have been quoted to
+ be part of a URL.
+ </para>
+ <note>
+ You must require the Rivet package in order to gain access to this command
+ </note>
</refsect1>
</refentry>
- <refentry id="apache_table">
+ <refentry id="upload">
<refnamediv>
- <refname>apache_table</refname>
- <refpurpose>access and manipulate Apache tables in the request structure.</refpurpose>
+ <refname>upload</refname>
+ <refpurpose>handle a file uploaded by a client.</refpurpose>
</refnamediv>
<refsynopsisdiv>
- <cmdsynopsis>
- <command>apache_table</command>
- <group choice="req">
- <arg>get</arg>
- <arg>set</arg>
- <arg>exists</arg>
- <arg>unset</arg>
- <arg>names</arg>
- <arg>array_get</arg>
- <arg>clear</arg>
- </group>
- </cmdsynopsis>
+ <cmdsynopsis>
+ <command>upload</command>
+ <group choice="req">
+ <arg>channel</arg>
+ <arg>save</arg>
+ <arg>data</arg>
+ <arg>exists</arg>
+ <arg>size</arg>
+ <arg>type</arg>
+ <arg>filename</arg>
+ </group>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+ <para>The upload command is for file upload manipulation.
+ See the relevant Apache Directives to further configure the
+ behavior of this Rivet feature.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <command>upload</command>
+ <arg choice="plain">channel</arg>
+ <arg><replaceable>uploadname</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ When given the name of a file upload
+ <option><replaceable>uploadname</replaceable></option>,
+ returns a Tcl channel that can be used to access the
+ uploaded file.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <command>upload</command>
+ <arg choice="plain">save</arg>
+ <arg><replaceable>uploadname</replaceable></arg>
+ <arg><replaceable>filename</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Saves the
+ <option><replaceable>uploadname</replaceable></option> in
+ the file
+ <option><replaceable>filename</replaceable></option>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <command>upload</command>
+ <arg choice="plain">data</arg>
+ <arg><replaceable>uploadname</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <command>upload</command>
+ <arg choice="plain">exists</arg>
+ <arg><replaceable>uploadname</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Returns true if an upload named <arg>uploadname</arg>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <command>upload</command>
+ <arg choice="plain">size</arg>
+ <arg><replaceable>uploadname</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Returns the size of the file uploaded.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <command>upload</command>
+ <arg choice="plain">type</arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ If the <varname>Content-type</varname> is set, it is
+ returned, otherwise, an empty string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <command>upload</command>
+ <arg choice="plain">filename</arg>
+ <arg><replaceable>uploadname</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Returns the filename on the remote host that uploaded the file.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <command>upload</command>
+ <arg choice="plain">tempname</arg>
+ <arg><replaceable>uploadname</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Returns the name of the temporary file on the local host that the file was uploaded into.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <command>upload</command>
+ <arg choice="plain">names</arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Returns the variable names, as a list, of all the files
+ uploaded.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ See <xref linkend="upload"/>.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="var">
+ <refnamediv>
+ <refname>var</refname>
+ <refname>var_qs</refname>
+ <refname>var_post</refname>
+ <refpurpose>get the value of a form variable.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>var</command>
+ <group choice="req">
+ <arg>get</arg>
+ <arg>list</arg>
+ <arg>exists</arg>
+ <arg>number</arg>
+ <arg>all</arg>
+ </group>
+ </cmdsynopsis>
+
+ <cmdsynopsis>
+ <command>var_qs</command>
+ <group choice="req">
+ <arg>get</arg>
+ <arg>list</arg>
+ <arg>exists</arg>
+ <arg>number</arg>
+ <arg>all</arg>
+ </group>
+ </cmdsynopsis>
+
+ <cmdsynopsis>
+ <command>var_post</command>
+ <group choice="req">
+ <arg>get</arg>
+ <arg>list</arg>
+ <arg>exists</arg>
+ <arg>number</arg>
+ <arg>all</arg>
+ </group>
+ </cmdsynopsis>
</refsynopsisdiv>
<refsect1>
- <title>Description</title>
- <para>The apache_table command is for accessing and manipulating
- Apache tables in the request structure.
- </para>
- <para>
- The table name must be one of
- <option>notes</option>,
- <option>headers_in</option>,
- <option>headers_out</option>,
- <option>err_headers_out</option>, or
- <option>subprocess_env</option>.
- </para>
-
+ <title>Description</title>
+ <para>
+ The <command>var</command> 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 <command>var</command>:
+ <command>var_qs</command> and <command>var_post</command>.
+ These two restrict the retrieval of information to
+ parameters arriving via the querystring
+ (?foo=bar&bee=bop) or POSTing, respectively.
+ </para>
<variablelist>
<varlistentry>
<term>
<cmdsynopsis>
- <command>apache_table</command>
+ <command>var</command>
<arg choice="plain">get</arg>
- <arg><replaceable>tablename</replaceable></arg>
- <arg><replaceable>key</replaceable></arg>
+ <arg><replaceable>varname</replaceable></arg>
+ <arg><replaceable><optional>default</optional></replaceable></arg>
</cmdsynopsis>
</term>
<listitem>
<para>
- When given the name of an Apache table
- <option><replaceable>tablename</replaceable></option>
- and the name of a key
- <option><replaceable>tablename</replaceable></option>,
- returns the value of the key in the table, or an empty
- string.
+ Returns the value of variable
+ <option><replaceable>varname</replaceable></option>
+ as a string (even if there are multiple values). If
+ the variable doesn't exist as a GET or POST
+ variable, the
+ <option><replaceable><optional>default</optional></replaceable></option>
+ value is returned, otherwise "" - an empty string -
+ is returned.
</para>
</listitem>
</varlistentry>
+
<varlistentry>
<term>
<cmdsynopsis>
- <command>apache_table</command>
- <arg choice="plain">set</arg>
- <arg><replaceable>tablename</replaceable></arg>
- <arg><replaceable>key</replaceable></arg>
- <arg><replaceable>value</replaceable></arg>
- </cmdsynopsis>
- <cmdsynopsis>
- <command>apache_table</command>
- <arg choice="plain">set</arg>
- <arg><replaceable>tablename</replaceable></arg>
- <arg><replaceable>list</replaceable></arg>
+ <command>var</command>
+ <arg choice="plain">list</arg>
+ <arg><replaceable>varname</replaceable></arg>
</cmdsynopsis>
</term>
<listitem>
<para>
- Stores the
- <option><replaceable>value</replaceable></option> in
- the table
- <option><replaceable>tablename</replaceable></option>
- under the key
- <option><replaceable>key</replaceable></option>.
- </para>
- <para>
- For the list form,
- <option><replaceable>list</replaceable></option> contains
- a list of zero or more pairs of key-value pairs to be
- set into the table
- <option><replaceable>tablename</replaceable></option>.
+ Returns the value of variable
+ <option><replaceable>varname</replaceable></option> as a
+ list, if there are multiple values.
</para>
</listitem>
</varlistentry>
+
<varlistentry>
<term>
<cmdsynopsis>
- <command>apache_table</command>
+ <command>var</command>
<arg choice="plain">exists</arg>
- <arg><replaceable>tablename</replaceable></arg>
- <arg><replaceable>key</replaceable></arg>
- </cmdsynopsis>
- </term>
- <listitem>
- <para>
- Returns 1 if the specified key,
- <option><replaceable>key</replaceable></option>,
- exists in table
- <option><replaceable>tablename</replaceable></option>,
- else 0.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <cmdsynopsis>
- <command>apache_table</command>
- <arg choice="plain">unset</arg>
- <arg><replaceable>tablename</replaceable></arg>
- <arg><replaceable>key</replaceable></arg>
- </cmdsynopsis>
- </term>
- <listitem>
- <para>
- Removes the key-value pair referenced by
- <option><replaceable>key</replaceable></option>
- from the table
- <option><replaceable>tablename</replaceable></option>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <cmdsynopsis>
- <command>apache_table</command>
- <arg choice="plain">names</arg>
- <arg><replaceable>tablename</replaceable></arg>
+ <arg><replaceable>varname</replaceable></arg>
</cmdsynopsis>
</term>
<listitem>
<para>
- Returns a list of all of the keys present in the table
- <option><replaceable>tablename</replaceable></option>.
+ Returns 1 if
+ <option><replaceable>varname</replaceable></option>
+ exists, 0 if it doesn't.
</para>
</listitem>
</varlistentry>
+
<varlistentry>
<term>
<cmdsynopsis>
- <command>apache_table</command>
- <arg choice="plain">array_get</arg>
- <arg><replaceable>tablename</replaceable></arg>
+ <command>var</command>
+ <arg choice="plain">number</arg>
</cmdsynopsis>
</term>
<listitem>
<para>
- Returns a list of key-value pairs from the table
- <option><replaceable>tablename</replaceable></option>.
+ Returns the number of variables.
</para>
</listitem>
</varlistentry>
+
<varlistentry>
<term>
<cmdsynopsis>
- <command>apache_table</command>
- <arg choice="plain">clear</arg>
- <arg><replaceable>tablename</replaceable></arg>
+ <command>var</command>
+ <arg choice="plain">all</arg>
</cmdsynopsis>
</term>
<listitem>
<para>
- Clears the contents of the specified table.
+ Return a list of variable names and values.
</para>
</listitem>
</varlistentry>
</variablelist>
+
+ <para>
+ See <xref linkend="variable_access"/>.
+ </para>
+
</refsect1>
</refentry>
+
+ <refentry id="wrap">
+ <refnamediv>
+ <refname>wrap</refname>
+ <refpurpose>
+ Split a string on newlines.
+ </refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>wrap</command>
+ <arg>string</arg>
+ <arg>maxlen</arg>
+ <arg choice="plan">html</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+ For each line, wrap the line at a space character to be
+ equal to or shorter than the maximum length value passed.
+ </para>
+ <para>
+ If a third argument called "-html" is present, the string is put together
+ with html <br> line breaks, otherwise it's broken with newlines.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="wrapline">
+ <refnamediv>
+ <refname>wrapline</refname>
+ <refpurpose>
+ Split the line into multiple lines by splitting on space characters
+ </refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>wrapline</command>
+ <arg>string</arg>
+ <arg>maxlen</arg>
+ <arg choice="plan">html</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+ Given a line and a maximum length and option "-html" argument, split the line
+ into multiple lines by splitting on space characters and making sure each line
+ is less than maximum length.
+ </para>
+ <para>
+ If the third argument, "-html", is present, return the result with the lines
+ separated by html <br> line breaks, otherwise the lines are returned
+ separated by newline characters.
+ </para>
+ <para>
+ If a third argument called "-html" is present, the string is put together
+ with html <br> line breaks, otherwise it's broken with newlines.
+ </para>
+ </refsect1>
+ </refentry>
</section>
---------------------------------------------------------------------
To unsubscribe, e-mail: rivet-cvs-unsubscribe@tcl.apache.org
For additional commands, e-mail: rivet-cvs-help@tcl.apache.org