| <html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Apache Rivet</title><link rel="stylesheet" type="text/css" href="rivet.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="Apache Rivet"><link rel="next" href="installation.html" title="Apache Rivet Installation"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Apache Rivet</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="installation.html"><img src="images/next.png" alt="Next"></a></td></tr></table></div><div class="article"><div class="titlepage"><div><div><h2 class="title"><a name="idm1"></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-2018 Apache Software Foundation</p></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="index.html#introduction">Introduction to Apache Rivet</a></span></dt><dt><span class="section"><a href="installation.html">Apache Rivet Installation</a></span></dt><dt><span class="section"><a href="request.html">Apache Child Processes Lifecycle and Request Processing</a></span></dt><dt><span class="section"><a href="directives.html">Rivet Apache Directives</a></span></dt><dd><dl><dt><span class="section"><a href="directives.html#idm269"></a></span></dt><dt><span class="section"><a href="directives.html#idm274"></a></span></dt></dl></dd><dt><span class="section"><a href="commands.html">Rivet Tcl Commands and Variables</a></span></dt><dd><dl><dt><span class="section"><a href="commands.html#idm512"></a></span></dt><dt><span class="refentrytitle"><a href="shorthand.html"><?= ... ?></a></span><span class="refpurpose"> — | |
| Shorthand construct for single strings output | |
| </span></dt><dt><span class="refentrytitle"><a href="abort_code.html">abort_code</a></span><span class="refpurpose"> — | |
| Returns the code passed to <span style="font-family:monospace"><span class="command"><strong>abort_page</strong></span></span> | |
| earlier during the request processing | |
| </span></dt><dt><span class="refentrytitle"><a href="abort_page.html">abort_page</a></span><span class="refpurpose"> — | |
| Stops outputting 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="apache_log_error.html">apache_log_error</a></span><span class="refpurpose"> — log messages to the Apache error log</span></dt><dt><span class="refentrytitle"><a href="apache_table.html">apache_table</a></span><span class="refpurpose"> — access and manipulate Apache tables in the request structure.</span></dt><dt><span class="refentrytitle"><a href="catch.html">catch</a></span><span class="refpurpose"> — wraps core command <span style="font-family:monospace"><span class="command"><strong>catch</strong></span></span> and handles in | |
| a special way fake error conditions resulting from calls to <span style="font-family:monospace"><span class="command"><strong>exit</strong></span></span> | |
| and <span style="font-family:monospace"><span class="command"><strong>abort_page</strong></span></span></span></dt><dt><span class="refentrytitle"><a href="clock_to_rfc.html">clock_to_rfc850_gmt</a></span><span class="refpurpose"> — create a rfc850 time from [clock seconds].</span></dt><dt><span class="refentrytitle"><a href="cookie.html">cookie</a></span><span class="refpurpose"> — get, set and delete cookies.</span></dt><dt><span class="refentrytitle"><a href="debug.html">debug</a></span><span class="refpurpose"> — | |
| A command to print strings, arrays | |
| and the values of variables as specified by the arguments. | |
| </span></dt><dt><span class="refentrytitle"><a href="env.html">env</a></span><span class="refpurpose"> — | |
| Loads a single "environmental variable" into a Tcl variable. | |
| </span></dt><dt><span class="refentrytitle"><a href="escape_sgml_chars.html">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.html">escape_shell_command</a></span><span class="refpurpose"> — escape shell metacharacters in a string.</span></dt><dt><span class="refentrytitle"><a href="escape_string.html">escape_string</a></span><span class="refpurpose"> — convert a string into escaped characters.</span></dt><dt><span class="refentrytitle"><a href="exit.html">exit</a></span><span class="refpurpose"> — terminate execution and child process</span></dt><dt><span class="refentrytitle"><a href="headers.html">headers</a></span><span class="refpurpose"> — set and parse HTTP headers.</span></dt><dt><span class="refentrytitle"><a href="html.html">html</a></span><span class="refpurpose"> — construct html tagged text.</span></dt><dt><span class="refentrytitle"><a href="http_accept.html">http_accept</a></span><span class="refpurpose"> — Parse HTTP Accept header lines</span></dt><dt><span class="refentrytitle"><a href="import_keyvalue_pairs.html">import_keyvalue_pairs</a></span><span class="refpurpose"> — Import an argument list into the named array</span></dt><dt><span class="refentrytitle"><a href="include.html">include</a></span><span class="refpurpose"> — includes a file into the output stream without modification.</span></dt><dt><span class="refentrytitle"><a href="incr0.html">incr0</a></span><span class="refpurpose"> — increment a variable or set it to 1 if nonexistent.</span></dt><dt><span class="refentrytitle"><a href="inspect.html">inspect</a></span><span class="refpurpose"> — Introspection command for Rivet configuration</span></dt><dt><span class="refentrytitle"><a href="lassign_array.html">lassign_array</a></span><span class="refpurpose"> — Assign a list of values to array variables</span></dt><dt><span class="refentrytitle"><a href="lempty.html">lempty</a></span><span class="refpurpose"> — | |
| Returns 1 if <list> is empty or 0 if it has any elements. | |
| This command emulates the TclX lempty command. | |
| </span></dt><dt><span class="refentrytitle"><a href="lmatch.html">lmatch</a></span><span class="refpurpose"> — | |
| Look for elements in <list> that match <pattern> | |
| </span></dt><dt><span class="refentrytitle"><a href="load_cookies.html">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.html">load_env</a></span><span class="refpurpose"> — get the request's environment variables.</span></dt><dt><span class="refentrytitle"><a href="load_headers.html">load_headers</a></span><span class="refpurpose"> — get client request's headers.</span></dt><dt><span class="refentrytitle"><a href="load_response.html">load_response</a></span><span class="refpurpose"> — load form variables into an array.</span></dt><dt><span class="refentrytitle"><a href="lremove.html">lremove</a></span><span class="refpurpose"> — remove from a list elements matching one or more patterns</span></dt><dt><span class="refentrytitle"><a href="makeurl.html">makeurl</a></span><span class="refpurpose"> — construct url's based on hostname, port.</span></dt><dt><span class="refentrytitle"><a href="no_body.html">no_body</a></span><span class="refpurpose"> — Prevents Rivet from sending any content.</span></dt><dt><span class="refentrytitle"><a href="parray.html">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="parse.html">parse</a></span><span class="refpurpose"> — parses a Rivet template file.</span></dt><dt><span class="refentrytitle"><a href="raw_post.html">raw_post</a></span><span class="refpurpose"> — get the unmodified body of a POST request sent by the client.</span></dt><dt><span class="refentrytitle"><a href="redirect.html">redirect</a></span><span class="refpurpose"> — Interrupt processing and divert to a new URL</span></dt><dt><span class="refentrytitle"><a href="read_file.html">read_file</a></span><span class="refpurpose"> — | |
| Read the entire contents of a file and return it as a string. | |
| </span></dt><dt><span class="refentrytitle"><a href="try.html">try</a></span><span class="refpurpose"> — | |
| Catch error and exception conditions | |
| </span></dt><dt><span class="refentrytitle"><a href="unescape_string.html">unescape_string</a></span><span class="refpurpose"> — unescape escaped characters in a string.</span></dt><dt><span class="refentrytitle"><a href="upload.html">upload</a></span><span class="refpurpose"> — handle a file uploaded by a client.</span></dt><dt><span class="refentrytitle"><a href="url_query.html">url_query</a></span><span class="refpurpose"> — builds a URL query from parameter-value pairs</span></dt><dt><span class="refentrytitle"><a href="var.html">var</a></span><span class="refpurpose"> — get the value of a form variable.</span></dt><dt><span class="refentrytitle"><a href="wrap.html">wrap</a></span><span class="refpurpose"> — | |
| Split a string on newlines. | |
| </span></dt><dt><span class="refentrytitle"><a href="wrapline.html">wrapline</a></span><span class="refpurpose"> — | |
| Split the line into multiple lines by splitting on space characters | |
| </span></dt><dt><span class="refentrytitle"><a href="xml.html">xml</a></span><span class="refpurpose"> — | |
| XML Fragments creation | |
| </span></dt></dl></dd><dt><span class="section"><a href="examples.html">Examples and Usage</a></span></dt><dt><span class="section"><a href="tcl_packages.html">Rivet Tcl Packages</a></span></dt><dt><span class="section"><a href="dio.html">DIO - Database Interface Objects</a></span></dt><dd><dl><dt><span class="refentrytitle"><a href="dio_package.html">DIO</a></span><span class="refpurpose"> — Database Interface Objects</span></dt></dl></dd><dt><span class="section"><a href="diodisplay.html">DIODisplay - Database Interface Objects Display Class</a></span></dt><dd><dl><dt><span class="refentrytitle"><a href="diodisplay_package.html">DIODisplay</a></span><span class="refpurpose"> — Database Interface Objects Display Class</span></dt></dl></dd><dt><span class="section"><a href="session_package.html">Session Package</a></span></dt><dd><dl><dt><span class="section"><a href="session_package.html#idm3032">Introduction</a></span></dt><dt><span class="section"><a href="session_package.html#requirements">Requirements</a></span></dt><dt><span class="section"><a href="session_package.html#idm3041">Preparing To Use It</a></span></dt><dt><span class="section"><a href="session_package.html#idm3051">Example Usage</a></span></dt><dt><span class="section"><a href="session_package.html#idm3063">Using Sessions From Your Code</a></span></dt><dt><span class="section"><a href="session_package.html#idm3109">Session Configuration Options</a></span></dt><dt><span class="section"><a href="session_package.html#idm3187">Session Methods</a></span></dt><dt><span class="section"><a href="session_package.html#idm3243">Getting Additional Randomness From The Entropy File</a></span></dt></dl></dd><dt><span class="section"><a href="form.html">Form: An HTML Form Fields Generation Utility</a></span></dt><dd><dl><dt><span class="section"><a href="form.html#idm3249">Introduction</a></span></dt><dt><span class="refentrytitle"><a href="form_package.html">form</a></span><span class="refpurpose"> — a Tcl command object for creating HTML forms</span></dt></dl></dd><dt><span class="section"><a href="calendar_package.html">Calendar Package</a></span></dt><dd><dl><dt><span class="section"><a href="calendar_package.html#idm3713">Introduction</a></span></dt><dt><span class="refentrytitle"><a href="calendar.html">Calendar</a></span><span class="refpurpose"> — Utility class the builds and prints a calendar table</span></dt><dt><span class="refentrytitle"><a href="xml_calendar.html">XmlCalendar</a></span><span class="refpurpose"> — Prints XML formatted calendar tables</span></dt><dt><span class="refentrytitle"><a href="html_calendar.html">HtmlCalendar</a></span><span class="refpurpose"> — Concrete class derived from XmlCalendar</span></dt></dl></dd><dt><span class="section"><a href="asciiglyphs.html">AsciiGlyphs</a></span></dt><dd><dl><dt><span class="section"><a href="asciiglyphs.html#idm3919">Introduction</a></span></dt><dt><span class="refentrytitle"><a href="toglyphs.html">toGlyphs</a></span><span class="refpurpose"> — | |
| print large ASCII glyphs | |
| </span></dt><dt><span class="section"><a href="asciiglyphs.html#idm3935">Example</a></span></dt></dl></dd><dt><span class="section"><a href="entities.html">RivetEntities</a></span></dt><dd><dl><dt><span class="section"><a href="entities.html#idm3940">Introduction</a></span></dt><dt><span class="refentrytitle"><a href="encode.html">encode</a></span><span class="refpurpose"> — | |
| encode a string replacing every occurrence of characters for | |
| which an SGML entity exists | |
| </span></dt><dt><span class="refentrytitle"><a href="decode.html">decode</a></span><span class="refpurpose"> — | |
| decode an SGML encoded string replacing every entity with the | |
| corresponding character | |
| </span></dt></dl></dd><dt><span class="section"><a href="formbroker.html">The Form Broker</a></span></dt><dd><dl><dt><span class="section"><a href="formbroker.html#idm3980">Introduction</a></span></dt><dt><span class="refentrytitle"><a href="fb.html">FormBroker</a></span><span class="refpurpose"> — | |
| Form broker object creator | |
| </span></dt></dl></dd><dt><span class="section"><a href="help.html">Resources - How to Get Help</a></span></dt><dd><dl><dt><span class="section"><a href="help.html#idm4108">Mailing Lists</a></span></dt><dt><span class="section"><a href="help.html#idm4115">Newsgroup</a></span></dt><dt><span class="section"><a href="help.html#websites">Web Sites</a></span></dt><dt><span class="section"><a href="help.html#idm4135">Bug Tracking System</a></span></dt><dt><span class="section"><a href="help.html#idm4139">IRC</a></span></dt><dt><span class="section"><a href="help.html#idm4142">Editing Rivet Template Files</a></span></dt></dl></dd><dt><span class="section"><a href="internals.html">Rivet Internals</a></span></dt><dd><dl><dt><span class="section"><a href="internals.html#idm4154">Initialization</a></span></dt><dt><span class="section"><a href="internals.html#idm4161">RivetChan</a></span></dt><dt><span class="section"><a href="internals.html#idm4166">The <span style="font-family:monospace"><span class="command"><strong>global</strong></span></span> Command</a></span></dt><dt><span class="section"><a href="internals.html#idm4174">Page Parsing, Execution and Caching</a></span></dt><dt><span class="section"><a href="internals.html#idm4182">Extending Rivet by developing C procedures implementing new commands</a></span></dt><dt><span class="section"><a href="internals.html#idm4208">Debugging Rivet and Apache</a></span></dt></dl></dd><dt><span class="section"><a href="upgrading.html">Upgrading from mod_dtcl or NeoWebScript</a></span></dt><dd><dl><dt><span class="section"><a href="upgrading.html#idm4238">mod_dtcl</a></span></dt><dt><span class="section"><a href="upgrading.html#idm4241">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="examples.html#hello_world">Hello World</a></dt><dt>2. <a href="examples.html#idm1719">Generate a Colorful Table</a></dt><dt>3. <a href="examples.html#variable_access">Variable Access</a></dt><dt>4. <a href="examples.html#file_upload">File Upload</a></dt><dt>5. <a href="examples.html#file_download">File Download</a></dt><dt>6. <a href="examples.html#ajax_xml_messaging">XML Messages and Ajax</a></dt><dt>7. <a href="examples.html#calexample">A Calendar Utility</a></dt></dl></div><p style="width:90%"> | |
| Document released as part of Rivet 2.4.0 (2018-11-24 11:03:21+01:00). | |
| </p><div class="section"><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 focused on the current version of Rivet, but | |
| still 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 class="simplesect"><div class="titlepage"><div><div><h3 class="title"><a name="idm19"></a>New commands in Rivet 2.4</h3></div></div></div><p style="width:90%"> | |
| Rivet 2.4 introduces 2 new commands <span style="font-family:monospace"><span class="command"><strong>::rivet::exit</strong></span></span> | |
| and <span style="font-family:monospace"><span class="command"><strong>::rivet::catch</strong></span></span> | |
| </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><span style="font-family:monospace"><span class="command"><strong>::rivet::exit</strong></span></span> was introduced to help mod_rivet to | |
| give the command <span style="font-family:monospace"><span class="command"><strong>exit</strong></span></span> a more sensible behavior within | |
| the context of the Apache HTTP Web Server. In fact the core command has | |
| become an alias of <span style="font-family:monospace"><span class="command"><strong>::rivet::exit</strong></span></span> which interrupts the | |
| script execution and hands control to any <span style="font-family:monospace"><span class="command"><strong>AbortScript</strong></span></span>, | |
| completes the request and just before returning to the web server framework terminates | |
| the child process by calling <span style="font-family:monospace"><span class="command"><strong>Tcl_Exit</strong></span></span></li><li class="listitem"> | |
| Since <span style="font-family:monospace"><span class="command"><strong>::rivet::abort_page</strong></span></span> and <span style="font-family:monospace"><span class="command"><strong>::rivet::exit</strong></span></span> | |
| interrupt a script execution returning a <span class="emphasis"><em>TCL_ERROR</em></span> code | |
| any call to a <span style="font-family:monospace"><span class="command"><strong>catch</strong></span></span> construct would trap this error and AbortScript | |
| could be executed only by throwing the error condition again. We introduced the | |
| <span style="font-family:monospace"><span class="command"><strong>::rivet::catch</strong></span></span> in order to simplify these operations. | |
| If any real error occurs the procedure returns | |
| 1 and fills the optional arguments with their expected values, otherwise | |
| execution is interrupted control passed on to | |
| <span style="font-family:monospace"><span class="command"><strong>AbortScript</strong></span></span></li></ul></div></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="installation.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"> </td><td width="40%" align="right" valign="top"> Apache Rivet Installation</td></tr></table></div></body></html> |