websh/quickref/context

<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Context handling</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.1"><link rel="home" href="index.html" title="Websh Reference 3.6.0b5"><link rel="up" href="index.html" title="Websh Reference 3.6.0b5"><link rel="prev" href="logging.html" title="Logging"><link rel="next" href="file_handling_and_file_IO.html" title="File handling and file I/O"></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">Context handling</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="logging.html">Prev</a>�</td><th width="60%" align="center">�</th><td width="20%" align="right">�<a accesskey="n" href="file_handling_and_file_IO.html">Next</a></td></tr></table><hr></div><div class="section" title="Context handling"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="context_handling"></a>Context handling</h2></div></div></div><div class="section" title="web::context"><div class="titlepage"><div><div><h3 class="title"><a name="web::context"></a><span style="font-family:monospace"><span class="command"><strong>web::context</strong></span></span></h3></div></div></div><p style="width:90%"> Creation </p><div class="cmdsynopsis"><span style="background:#bbbbff"><span style="font-weight:bold"><code class="command">web::context</code></span> <em class="replaceable"><code>name</code></em></span></div><p style="width:90%"> Creates a namespace <tt>name</tt> with the following commands: </p><div class="cmdsynopsis"><span style="background:#bbbbff"><span style="font-weight:bold"><code class="command"><em class="replaceable"><code>name</code></em>::subcommand</code></span> <em class="replaceable"><code>args</code></em></span></div><p style="width:90%"> Subcommands are: <tt>cset</tt>, <tt>cappend</tt>, <tt>clappend</tt>, <tt>cget</tt>, <tt>cexists</tt>, <tt>cunset</tt>, <tt>carray</tt>, <tt>cnames</tt>, <tt>delete</tt>, and <tt>dump</tt>. Manages data of the context. The subcommands behave like the Tcl commands with similar names. </p><div class="variablelist"><dl><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::cset</strong></span></span> <tt><em class="replaceable"><code>key</code></em></tt> <tt><em class="replaceable"><code>value</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Set <tt>key</tt> to <tt>value</tt>. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::cappend</strong></span></span> <tt><em class="replaceable"><code>key</code></em></tt> <tt><em class="replaceable"><code>value</code></em></tt> ?<span class="optional"><tt><em class="replaceable"><code>value</code></em></tt></span>? ?<span class="optional"><tt><em class="replaceable"><code>...</code></em></tt></span>?</span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Appends <tt>value</tt> to existing value for <tt>key</tt>. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::clappend</strong></span></span> <tt><em class="replaceable"><code>key</code></em></tt> <tt><em class="replaceable"><code>value</code></em></tt> ?<span class="optional"><tt><em class="replaceable"><code>value</code></em></tt></span>? ?<span class="optional"><tt><em class="replaceable"><code>...</code></em></tt></span>?</span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Appends <tt>value</tt> to existing list of values for <tt>key</tt>. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::cget</strong></span></span> <tt><em class="replaceable"><code>key</code></em></tt> ?<span class="optional"><tt><em class="replaceable"><code>default</code></em></tt></span>?</span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Accesses the value for key <tt>key</tt>, or returns <tt>default</tt> if <tt>key</tt> does not exist in the context. If <tt>default</tt> is omitted, an empty string is returned if <tt>key</tt> is unknown. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::cexists</strong></span></span> <tt><em class="replaceable"><code>key</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Returns true (1) if <tt>key</tt> exists in context, false (0) otherwise. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::cunset</strong></span></span> <tt><em class="replaceable"><code>key</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Removes <tt>key</tt> from context. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::carray</strong></span></span> <tt><em class="replaceable"><code>option</code></em></tt> <tt><em class="replaceable"><code>key</code></em></tt> <tt><em class="replaceable"><code>arg</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Array manipulation as known from the Tcl command <span class="emphasis"><em>array</em></span>. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::cnames</strong></span></span> ?<span class="optional"><tt><em class="replaceable"><code>pattern</code></em></tt></span>?</span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Lists existing keys of context matching <tt>pattern</tt>. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::delete</strong></span></span></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Deletes the context (same as <span style="font-family:monospace"><span class="command"><strong>namespace delete <em class="replaceable"><code>name</code></em></strong></span></span>) </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::dump</strong></span></span></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Serializes context in a "source"-able format. </div></div></dd></dl></div><p style="width:90%"> </p><div class="example"><a name="id2739577"></a><p class="title"><b>Example�12.�<span style="font-family:monospace"><span class="command">web::context</span></span></b></p><div class="example-contents"><pre style="background:#bbffbb ; width:75%" class="programlisting"> % web::context sc % sc::cset lang FR FR % # ... some code ... % set lang [sc::cget lang EN] FR % </pre></div></div><p style="width:90%"><br class="example-break"> </p></div><div class="section" title="web::filecontext"><div class="titlepage"><div><div><h3 class="title"><a name="web::filecontext"></a><span style="font-family:monospace"><span class="command"><strong>web::filecontext</strong></span></span></h3></div></div></div><p style="width:90%"> Creation: </p><div class="cmdsynopsis"><span style="background:#bbbbff"><span style="font-weight:bold"><code class="command">web::filecontext</code></span> <em class="replaceable"><code>name</code></em> ?<em class="replaceable"><code>options</code></em>?</span></div><p style="width:90%"> Options are: <tt>-perm</tt>, <tt>-path</tt>, <tt>-crypt</tt>, <tt>-idgen</tt>, and <tt>-attachto</tt>. Creates a namespace <tt>name</tt> to manage file-based context data: </p><div class="cmdsynopsis"><span style="background:#bbbbff"><span style="font-weight:bold"><code class="command"><em class="replaceable"><code>name</code></em>::subcommand</code></span> <em class="replaceable"><code>args</code></em></span></div><p style="width:90%"> Subcommands are: <tt>cset</tt>, <tt>cappend</tt>, <tt>clappend</tt>, <tt>cget</tt>, <tt>cexists</tt>, <tt>cunset</tt>, <tt>carray</tt>, <tt>cnames</tt>, <tt>init</tt>, <tt>new</tt>, <tt>commit</tt>, <tt>invalidate</tt>, and <tt>id</tt>. Manages file-based context data. The subcommands have their familiar behaviour of the Tcl commands with similar names. Please refer to the section <a class="link" href="context_handling.html" title="Context handling">context management</a> for a description of the commands <tt>cset</tt>, <tt>cappend</tt>, <tt>clappend</tt>, <tt>cget</tt>, <tt>cexists</tt>, <tt>cunset</tt>, <tt>carray</tt>, and <tt>cnames</tt>. </p><div class="variablelist"><dl><dt><span style="background:#bbbbff"><span class="term"> <span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::init</strong></span></span> ?<span class="optional"><tt><em class="replaceable"><code>id</code></em></tt></span>? </span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Loads an existing session context with id <tt>id</tt>, or creates a new one, if possible. Automation depends on the settings of the actual context manager settings, see below.</div><div style="margin-bottom:6"> If you specify an <tt>id</tt>, you must decide when to create a new file and when to use the old one, if any, by yourself. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::new</strong></span></span> ?<span class="optional"><tt><em class="replaceable"><code>id</code></em></tt></span>?</span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Creates a new session context. Automation depends on the settings of the actual context manager settings, see below. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::commit</strong></span></span></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Makes session context persistent. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::id</strong></span></span></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Returns id of session. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::invalidate</strong></span></span></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Deletes session in memory and on file system. </div></div></dd></dl></div><p style="width:90%"> Options: </p><div class="cmdsynopsis"><span style="background:#bbbbff"><span style="font-weight:bold"><code class="command">web::filecontext</code></span> <em class="replaceable"><code>name</code></em> -perm <em class="replaceable"><code>perm</code></em></span></div><p style="width:90%"> Sets the file permissions of the session context files <tt>perm</tt> is an unix-like octal value like 0644. If not specified, files are created with the permissions defined in <span style="font-family:monospace"><span class="command"><strong>web::config filepermissions</strong></span></span>, which again defaults to 0644. </p><div class="variablelist"><dl><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::filecontext</strong></span></span> <tt><em class="replaceable"><code>name</code></em></tt> <tt>-path</tt> <tt><em class="replaceable"><code>path</code></em></tt> </span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Specifies where to store session context files and how to name them. Suppose that the session id is 99. <span class="emphasis"><em>-path [file join .. data s%d.dat]</em></span> would then cause filecontext to save the session context as <code class="literal">../data/s99.dat</code>. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::filecontext</strong></span></span> <tt><em class="replaceable"><code>name</code></em></tt> <tt>-crypt</tt> <tt>boolean</tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Sets crypting of session context on or off. Default: on. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::filecontext</strong></span></span> <tt><em class="replaceable"><code>name</code></em></tt> <tt>-idgen</tt> <tt><em class="replaceable"><code>idgen</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Sets command <tt>idgen</tt> to find a new session id. See doc of <span style="font-family:monospace"><span class="command"><strong>web::filecounter</strong></span></span> below for an implementation provided by Websh. </div><div style="margin-bottom:6"> <tt>idgen</tt> is used in case that no <tt>id</tt> argument has been passed to <tt>init</tt> or <tt>new</tt>. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::filecontext</strong></span></span> <tt><em class="replaceable"><code>name</code></em></tt> <tt>-attachto</tt> <tt><em class="replaceable"><code>idparam</code></em></tt> </span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Causes <span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::init</strong></span></span> to initialize with the id given in the querystring parameter <tt>idparam</tt>. (This is one important reason why the querystring should be encrypted). After <span style="font-family:monospace"><span class="command"><strong>web::dispatch</strong></span></span> has parsed the querystring, <span style="font-family:monospace"><span class="command"><strong>web::param</strong></span></span> will report the current session id in <tt>idparam</tt>, if any. <span class="emphasis"><em>Note</em></span> that you can maintain several sessions in parallel, and attach every session to its own <tt>idparam</tt>. </div><div style="margin-bottom:6"> Using <span class="emphasis"><em><span style="font-family:monospace"><span class="command"><strong>web::dispatch -track</strong></span></span></em></span> further automates the passing of session ids from request to request. </div></div></dd></dl></div><p style="width:90%"> <span class="emphasis"><em>Note:</em></span> Whenever you create a new file-based context, the context is initialized and you loose whatever information that you might have stored in the context before you initialized it as a file-based session context. </p></div><div class="section" title="web::cookiecontext"><div class="titlepage"><div><div><h3 class="title"><a name="web::cookiecontext"></a><span style="font-family:monospace"><span class="command"><strong>web::cookiecontext</strong></span></span></h3></div></div></div><p style="width:90%"> Creation: </p><div class="cmdsynopsis"><span style="background:#bbbbff"><span style="font-weight:bold"><code class="command">web::cookiecontext</code></span> <em class="replaceable"><code>name</code></em> ?<em class="replaceable"><code>options</code></em>?</span></div><p style="width:90%"> Options are: <tt>-expires</tt>, <tt>-path</tt>, <tt>-domain</tt>, <tt>-secure</tt>, <tt>-crypt</tt>, and <tt>-channel</tt>. Creates a namespace <tt>name</tt> to manage cookie-based context data: </p><div class="variablelist"><dl><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::subcommand</strong></span></span> <tt><em class="replaceable"><code>args</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Subcommands are: <tt>cset</tt>, <tt>cappend</tt>, <tt>clappend</tt>, <tt>cget</tt>, <tt>cexists</tt>, <tt>cunset</tt>, <tt>carray</tt>, <tt>cnames</tt>, <tt>init</tt>, <tt>new</tt>, <tt>commit</tt>, <tt>invalidate</tt>, and <tt>id</tt>. </div></div></dd></dl></div><p style="width:90%"> </p><div class="variablelist"><dl><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::init</strong></span></span> ?<span class="optional"><tt><em class="replaceable"><code>id</code></em></tt></span>?</span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Loads an existing session context (cookie must have been sent by the client). </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::new</strong></span></span> ?<span class="optional"><tt><em class="replaceable"><code>id</code></em></tt></span>?</span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Creates a new session context. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::commit</strong></span></span></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Sends a cookie (if no output to the page has been sent yet). </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::id</strong></span></span></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Returns id of session. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::invalidate</strong></span></span></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Deletes session in memory and on client side. </div></div></dd></dl></div><p style="width:90%"> Options: </p><div class="variablelist"><dl><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::cookiecontext</strong></span></span> <tt><em class="replaceable"><code>name</code></em></tt> <tt>-expires</tt> <tt><em class="replaceable"><code>time</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Sets the expiration date of the cookie. Possible values for <tt>time</tt> are <span class="emphasis"><em>seconds</em></span> (time in seconds since 1970-01-01) or <span class="emphasis"><em>date-string</em></span> (any time string that Tcl can scan. Note that therefore many relative times, such as <span class="emphasis"><em>24 hours</em></span>, <span class="emphasis"><em>week</em></span>, <span class="emphasis"><em>2 weeks</em></span>, <span class="emphasis"><em>tomorrow</em></span>, etc. are possible. Default is <span class="emphasis"><em>now + 24 hours</em></span> (i.e. cookie expires in 24 hours. (Please note that the behavior of some of these relative time specifiers changed from Tcl8.4 to Tcl8.5.) Use <span class="emphasis"><em>-expires ""</em></span> to send a cookie without an expires parameter. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::cookiecontext</strong></span></span> <tt><em class="replaceable"><code>name</code></em></tt> <tt>-path</tt> <tt><em class="replaceable"><code>path</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Sets the <tt>path</tt> property of the cookie. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::cookiecontext</strong></span></span> <tt><em class="replaceable"><code>name</code></em></tt> <tt>-domain</tt> <tt><em class="replaceable"><code>domain</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Sets the <tt>domain</tt> property of the cookie. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::cookiecontext</strong></span></span> <tt><em class="replaceable"><code>name</code></em></tt> <tt>-secure</tt> <tt>boolean</tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Sets the <tt>secure</tt> property of the cookie. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::cookiecontext</strong></span></span> <tt><em class="replaceable"><code>name</code></em></tt> <tt>-crypt</tt> <tt>boolean</tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Sets crypting of cookie context on or off. Default: on. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::cookiecontext</strong></span></span> <tt><em class="replaceable"><code>name</code></em></tt> <tt>-channel</tt> <tt><em class="replaceable"><code>channelName</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Sets the response object to send the cookie to (see also <span style="font-family:monospace"><span class="command"><strong>web::response</strong></span></span>). </div></div></dd></dl></div><p style="width:90%"> Because cookies are client-based, in principle no id is needed. Websh uses <tt>id</tt> to name the cookie, however, and the <span style="font-family:monospace"><span class="command"><strong>new</strong></span></span>, <span style="font-family:monospace"><span class="command"><strong>init</strong></span></span>, and <span style="font-family:monospace"><span class="command"><strong>load</strong></span></span> commands still require the <tt>id</tt> argument. (fixme: any changes?) Please note that property settings of a cookie context can only be changed <span class="emphasis"><em>before</em></span> anything is output on the respective channel. </p></div><div class="section" title="web::filecounter"><div class="titlepage"><div><div><h3 class="title"><a name="web::filecounter"></a><span style="font-family:monospace"><span class="command"><strong>web::filecounter</strong></span></span></h3></div></div></div><p style="width:90%"> This is a numeric sequence-number generator which stores its state in a file. Basic usage: </p><div class="variablelist"><dl><dt><span style="background:#bbbbff"><span class="term">Creation:</span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> <span style="font-family:monospace"><span class="command"><strong>web::filecounter</strong></span></span> <tt><em class="replaceable"><code>name</code></em></tt> <tt>-filename</tt> <tt><em class="replaceable"><code>fname</code></em></tt> ?<span class="optional"><tt><em class="replaceable"><code>options</code></em></tt></span>? </div><div style="margin-bottom:6"> Options are: <tt>-min</tt>, <tt>-max</tt>, <tt>-seed</tt>, <tt>-incr</tt>, <tt>-mask</tt>, <tt>-wrap</tt> </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><tt>-filename</tt> <tt><em class="replaceable"><code>filename</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Uses <tt>filename</tt> to store the current value (no default). </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><tt>-min</tt> <tt><em class="replaceable"><code>value</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Uses this value as a minimum at start and after wrap, if wrap is true. Default: 0. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><tt>-max</tt> <tt><em class="replaceable"><code>value</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Uses this value as a maximum, if wrap is true. Default: 2147483647. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><tt>-seed</tt> <tt><em class="replaceable"><code>value</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Usea this value as a starting point if persistent file does not exist yet. Default: 0. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><tt>-incr</tt> <tt><em class="replaceable"><code>value</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Uses this value as an increment for each 'nextval'. Default: 1. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><tt>-perms</tt> <tt><em class="replaceable"><code>value</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Sets the permissions on the newly created files. Default is configured in <span style="font-family:monospace"><span class="command"><strong>web::config filepermissions</strong></span></span>, which defaults to 0644. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><tt>-wrap</tt> <tt>boolean</tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Indicates whether this counter should wrap around its values (back to min from max). Default: false. </div></div></dd></dl></div><p style="width:90%"> After creation, a new command <tt>name</tt> is registered with the following subcommands: </p><div class="variablelist"><dl><dt><span style="background:#bbbbff"><span class="term"><tt><em class="replaceable"><code>name</code></em></tt> config</span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Returns a flat list of key value pairs with the filecounter's configuration. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><tt><em class="replaceable"><code>name</code></em></tt> nextval</span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Returns the next value. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><tt><em class="replaceable"><code>name</code></em></tt> curval</span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Returns the current value, that is, the value that the last call to "nextval" or "getval" reported (as opposed to the current value in the file). </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><tt><em class="replaceable"><code>name</code></em></tt> getval</span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Returns the current value in the file. (Does not increment file as in "nextval".) </div></div></dd></dl></div><p style="width:90%"> </p><div class="example"><a name="id2741137"></a><p class="title"><b>Example�13.�<span style="font-family:monospace"><span class="command">web::filecounter</span></span></b></p><div class="example-contents"><pre style="background:#bbffbb ; width:75%" class="programlisting"> % web::filecounter fc1 -filename test.dat fc1 % fc1 config file test.dat handle fc1 seed 0 min 0 max 2147483647 incr 1 perms 0644 wrap false curr {not valid} % fc1 curval web::filecounter: no current value available % fc1 nextval 0 % fc1 config file test.dat handle fc1 seed 0 min 0 max 2147483647 incr 1 perms 0644 wrap false curr 0 % fc1 nextval 1 % web::filecounter fc2 -filename test.dat fc2 % fc2 curval web::filecounter: no current value available % fc2 getval 1 % fc2 nextval 2 % fc2 curval 2 % fc1 curval 1 % fc1 nextval 3 % fc2 getval 3 % web::filecounter fc3 -filename othertest.dat -min 1 -max 10 -seed 1 -incr 2 -wrap 1 fc3 % fc3 config file othertest.dat handle fc3 seed 1 min 1 max 10 incr 2 perms 0644 wrap true curr {not valid} % fc3 nextval 1 % fc3 nextval 3 % </pre></div></div><br class="example-break"></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="logging.html">Prev</a>�</td><td width="20%" align="center">�</td><td width="40%" align="right">�<a accesskey="n" href="file_handling_and_file_IO.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Logging�</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">�File handling and file I/O</td></tr></table></div></body></html>

websh/quickref/context_handling.html (344 lines of code) (raw):