<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.78.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="idp51790080"></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">&lt;<a class="email" href="mailto:rivet-dev@tcl.apache.org">rivet-dev@tcl.apache.org</a>&gt;</code><br>
	        </p></div></div></div></div><div><p class="copyright">Copyright © 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 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#idp55071840"></a></span></dt><dt><span class="section"><a href="directives.html#idp55120400"></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#idp55340080"></a></span></dt><dt><span class="refentrytitle"><a href="shorthand.html">&lt;?= ... ?&gt;</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="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="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 &lt;list&gt; 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 &lt;list&gt; that match &lt;pattern&gt;
		</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="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="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="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#idp58018000">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#idp58066416">Preparing To Use It</a></span></dt><dt><span class="section"><a href="session_package.html#idp58071808">Example Usage</a></span></dt><dt><span class="section"><a href="session_package.html#idp58078560">Using Sessions From Your Code</a></span></dt><dt><span class="section"><a href="session_package.html#idp58102224">Session Configuration Options</a></span></dt><dt><span class="section"><a href="session_package.html#idp58129568">Session Methods</a></span></dt><dt><span class="section"><a href="session_package.html#idp58156624">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#idp58223936">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#idp58816656">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="entities.html">RivetEntities</a></span></dt><dd><dl><dt><span class="section"><a href="entities.html#idp59054784">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="help.html">Resources - How to Get Help</a></span></dt><dd><dl><dt><span class="section"><a href="help.html#idp59092416">Mailing Lists</a></span></dt><dt><span class="section"><a href="help.html#idp59078688">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#idp59158896">Bug Tracking System</a></span></dt><dt><span class="section"><a href="help.html#idp59160816">IRC</a></span></dt><dt><span class="section"><a href="help.html#idp59162144">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#idp59151152">Initialization</a></span></dt><dt><span class="section"><a href="internals.html#idp59137536">RivetChan</a></span></dt><dt><span class="section"><a href="internals.html#idp59201312">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#idp59206752">Page Parsing, Execution and Caching</a></span></dt><dt><span class="section"><a href="internals.html#idp59211824">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#idp59193408">mod_dtcl</a></span></dt><dt><span class="section"><a href="upgrading.html#idp59194752">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#idp56521120">Generate a 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#calendar">A Calendar Utility</a></dt></dl></div><p style="width:90%">
    Document revision: $Revision: 1562035 $, last modified 2014-02-28 23:42:55+01:00$ by $Author: mxmanghi $.
  </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="idp50103648"></a>Acknowledgements</h3></div></div></div><p style="width:90%">
            Rivet 2.1.0 comes with relevant contributions provided by 
            <span class="emphasis"><em>Harald Oehlmann</em></span> (page RivetEntitites, 
            new command ::rivet::http_accept and bugfixes), 
            <span class="emphasis"><em>Cyril Shtumf</em></span> (important bugfixes) and
            <span class="emphasis"><em>Jeff Lawson</em></span> (who introduced the 
            shorthand syntax for string output)
        </p></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>