ref/app.html

<html dir="ltr">
<head>
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type"/>
<title>Arc: App server</title>
<link rel="shortcut icon" href="/assets/favicon.png">
<link rel="stylesheet" type="text/css" href="code.css">
<link href="/assets/bootstrap.css" rel="stylesheet">
</head>
<body style='margin:12px 50px 0'>
  <div class="navbar navbar-inverse">
    <div class="navbar-inner">
      <ul class="nav navbar-nav">
        <li><a href="/ref/">Arc 3.1</a>
        <li><a href="http://tryarc.org">Try it</a></li>
        <li><a href="http://github.com/arclanguage/anarki">Get it</a></li>
        <li><a href="http://ycombinator.com/arc/tut.txt">Tutorial</a></li>
        <li><a href="http://arclanguage.org/forum">Forum</a></li>
      </ul>
    </div>
  </div> <!-- end of navbar -->
<div class="links">Previous: <a href="srv.html">The Arc web server</a>
Up: <a href="index.html">Contents</a>
Next: <a href="setforms.html">Internals of places and setforms</a>
</div>
<h1 class="links">App server</h1>
The Arc distribution includes a simple application server in <code>app.arc</code>.  The two main features of the app server are account management and improved forms handling.

<h2>Running the server</h2>
The server can be started simply with
<pre class="repl">
arc>(asv 8080)
</pre>
<p>
However, it is generally better to start the server in a separate thread, so the Arc REPL can be used.  This allows the web server to be modified while it is running.
<pre class="repl">
arc> (thread (asv 8080))
</pre>

<h2>Account management</h2>
The app server implements user accounts, so a web user can log into a particular account.  Optionally, an account can be an "admin" account with access to the administrative features.  A user logs into an account with a login form.
The user can then log out of the account.  The app server also provides web-based account creation and password modification.
<p>
The user login uses a simple browser cookie to keep track of the login.  Note that the user account management is entirely orthogonal to the fnid-based continuations of the Arc web server.  Logins are maintained through a cookie; fnids are passed in the URL or a form field.  The app server includes several mechanisms to ensure that a fnid callback is executed by the expected user.
<p>
The app server defines the following pages:
<br><code>/whoami</code>: displays the logged-in userid and IP address, or redirects to login.
<br><code>/login</code>: logs user in or creates new account.
<br><code>/logout</code>: logs the current user out.
<br><code>/admin</code>: displays the administrative page, if the user is logged into an admin account.
<br><code>/mismatch</code>: displays an error "Dead link: users don't match."  This page is used when a fnid is accessed by the wrong (or logged-out) user.

<p>
The following is an example page with user authentication; it will run at <a href="http://localhost:8080/example">http://localhost:8080/example</a>.  First, the handler ensures the user is logged in, and displays the login page otherwise.  The page displays a form saying "This is the example page".  When submitted, the page will say, "Hello <i>user</i>".  The <code>uform</code> form ensures that the user is still logged in when the form is submitted; otherwise, the page will display the dead link error.
<pre class="code">
(defopl example req
  (let user (get-user req)
    (uform user req (prn "Hello " user)
      (prn "This is the example page.") (submit))))
</pre>
The following example illustrates <code>urform</code>.  The page <a href="http://localhost:8080/urexample">http://localhost:8080/urexample</a> will accept a value in a form.  When submitted, the continuation function will output a cookie header and redirect to the page "uexample", which will display the cookies.
<pre class="code">
(defopl urexample req
  (let user (get-user req)
    (urform user req
      (do (prn "Set-cookie: mycook=" (alref (req 'args) "foo")) "uexample")
      (prn "Enter value:") (input 'foo) (submit))))

(defopl uexample req (prn "User " (get-user req)) (br) (prn "Cookies " (req 'cooks)))
</pre>

<h2>Improved forms</h2>
The second feature provided by the app server is improved form functionality: markdown and typed forms.
<p>
Markdown is a simple mechanism for adding some formatting to plain text.  Text surrounded by asterisks is converted to italics.  URLs are converted to links.  Blank lines indicate paragraph breaks.  Lines that are indented and separated from previous lines by a blank line are displayed as preformatted code.
The Arc app server provides mechanisms to convert markdown text to HTML, and supports markdown input in forms.
<p>
The app server also provides a mechanism to create forms consisting of multiple typed fields in a table.  For example, a form can have one string input and one integer input.  The types are entirely separate from Arc's datatypes.  The following table outlines the supported types:
<table class="info"><tr><th>Type</th><th>Form field</th><th>Result</th></tr>
<tr><td><code>string</code></td><td>text input of width <code>formwid*</code></td><td>String</td></tr>
<tr><td><code>string1</code></td><td>text input of width <code>formwid*</code></td><td>String, empty not allowed</td></tr>
<tr><td><code>int</code></td><td>text input of width <code>numwid*</code></td><td>Integer (rounded)</td></tr>
<tr><td><code>num</code></td><td>text input of width <code>numwid*</code></td><td>Number</td></tr>
<tr><td><code>posint</code></td><td>text input of width <code>numwid*</code></td><td>Integer > 0 (rounded)</td></tr>
<tr><td><code>doc</code></td><td>textarea input of width big<code>formwid*</code></td><td>String</td></tr>
<tr><td><code>text</code></td><td>textarea input of width <code>formwid*</code></td><td>String</td></tr>
<tr><td><code>mdtext</code></td><td>textarea input of width <code>formwid*</code></td><td>Markdown text</td></tr>
<tr><td><code>mdtext2</code></td><td>textarea input of width <code>formwid*</code></td><td>Markdown text, no links</td></tr>
<tr><td><code>toks</code></td><td>text input of width <code>formwid*</code></td><td>List of string tokens</td></tr>
<tr><td><code>bigtoks</code></td><td>textarea input of width <code>formwid*</code></td><td>List of tokens</td></tr>
<tr><td><code>sexpr</code></td><td>text input of width <code>formwid*</code></td><td>List of S-expressions.</td></tr>
<tr><td><code>hexcol</code></td><td>text input</td><td>String if the string defines a valid hex color</td></tr>
<tr><td><code>url</code></td><td>text input of width <code>formwid*</code></td><td>URL (empty string allowed).</td></tr>
<tr><td><code>users</code></td><td>text input of width <code>formwid*</code></td><td>List of usernames with bad names filtered out</td></tr>
<tr><td><code>choice</code></td><td>select dropdown menu.</td><td>Type from the choice list</td></tr>
<tr><td><code>yesno</code></td><td>select dropdown with "yes" and "no" choices.</td><td>Boolean, true for input "yes"</td></tr>
</table>
The <code>choice</code> type is specified as a list: <code>choice</code>, the type of the choices, and the choices themselves, for instance <code>'(choice int 1 2 3)</code>.  The <code>mdtext</code> and <code>mdtext2</code> inputs include a help link to <code>formatdoc-url*</code>.
<p>
A typed form is generated by <code>vars-form</code>, which is a fairly complex procedure.  It takes a list of field specifications, where each field specification is a list
of <code>(type label value view modify question)</code>.  The <code>type</code> specifier is from the above table.  The <code>label</code> is the name assigned to the input field.  The initial value of the field is <code>value</code>.  If <code>view</code> is <code>nil</code>, the field is skipped.  If <code>modify</code> is nil, the field is not modifiable; it is displayed as text rather than an input field.  If <code>question</code> is defined, it appears as a caption above the field; otherwise, the label is displayed before the field.
<p>
The following example shows a form created by <code>vars-form</code>.  When the form is submitted, each name and value is printed, followed by "Done!".  The user must log in, if not already logged in.
The example runs at the URL <a href="http://localhost:8080/vars-form">http://localhost:8080/vars-form</a>.
<pre class="code">
(defopl vars-form req
  (vars-form (get-user req)
     '((int field1 42 t t "Enter int:")
       (toks field2 (a b c) t t)
       (string nil "bar" t nil "Can't touch this."))
     (fn (name val) (prn name " " val) (br))
     (fn () (prn "Done!"))
     "Doit"))
</pre>
The generated form is:
<br>
<img style="border: 1px;" src="vars-form.gif">
<h2>App server</h2>
<p><table class='arc'>
  <tr>
    <td class='arc'><a name='asv'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>asv</span> <span class='args'>[port]</span>
    <div class='desc'>Starts the application server.</div>
    </td>
    <td class='arc'><pre>
&gt;(asv 8080)

</pre>
  </td></tr>
</table>
<h2>User management</h2>
<p><table class='arc'>
  <tr>
    <td class='arc'><a name='get-user'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>get-user</span> <span class='args'>req</span>
    <div class='desc'>Gets the user id string associated with <code>req</code>.  Returns <code>nil</code> if no associated user.</div>
    </td>
    <td class='arc'><pre>
&gt;(get-user req)
foo
</pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='admin'></a>
<img src='proc.gif' title='Procedure'/>
<img src='predicate.gif' title='Predicate'/>
<span class='op'>admin</span> <span class='args'>user</span>
    <div class='desc'>Tests if <code>user</code> is an administrator; i.e. is in <code>admins*</code>.</div>
    </td>
    <td class='arc'><pre>
&gt;(admin "foo")
<span class="stdout">Error: _admins*: undefined;
 cannot reference an identifier 
before its definition
  in module: top-level
  internal name
: _admins*

</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='goodname'></a>
<img src='proc.gif' title='Procedure'/>
<img src='predicate.gif' title='Predicate'/>
<span class='op'>goodname</span> <span class='args'>str [min [max]]</span>
    <div class='desc'>Tests that <code>str</code> is of the appropriate length and contains no bad characters.</div>
    </td>
    <td class='arc'><pre>
&gt;(goodname "abc")
<span class="return">"abc"
</span></pre>
<pre>
&gt;(goodname "ab!")
<span class="return">nil
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='logout-user'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>logout-user</span> <span class='args'>user</span>
    <div class='desc'>Logs out <code>user</code>.  The user's entry is removed from <code>logins*</code>, <code>cookie->user*</code>, <code>user->cookie*</code>, and the updated <code>cookie->user*</code> is written to <code>cookfile*</code>.</div>
    </td>
    <td class='arc'><pre>
&gt;(logout-user "foo")
<span class="return">nil
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='set-pw'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>set-pw</span> <span class='args'>user pw</span>
    <div class='desc'>Creates (or updates) account with the name <code>user</code> and password <code>pw</code>.  Saves <code>hpasswords*</code> in <code>hpwfile*</code>.</div>
    </td>
    <td class='arc'><pre>
&gt;(set-pw "foo" "bar")

</pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='defopl'></a>
<img src='macro.gif' title='Macro'/>
<span class='op'>defopl</span> <span class='args'>name parm [body]</span>
    <div class='desc'>Version of <code>defop</code> to create handler that will redirect to login page if the user is not logged in.</div>
    </td>
    <td class='arc'><pre>
&gt;(defopl foo req (prn "Welcome!"))

</pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='uform'></a>
<img src='macro.gif' title='Macro'/>
<span class='op'>uform</span> <span class='args'>user req after [body ...]</span>
    <div class='desc'>Generates form that ensures it was submitted by <code>user</code> (by using <code>when-umatch</code>).  <code>body</code> outputs the form body to stdout.  After submission, the continuation code <code>after</code> is executed; <code>req</code> specifies the varible name in <code>after</code> to receive the request.</div>
    </td>
    <td class='arc'><pre>
&gt;(uform user req (prn "Result") (prn "The form") (submit))

</pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='urform'></a>
<img src='macro.gif' title='Macro'/>
<span class='op'>urform</span> <span class='args'>user req after [body ...]</span>
    <div class='desc'>Generates form with redirection target with guard that <code>user</code> submitted it.  After submission, the continuation expression <code>after</code> is executed and must return the redirect string; <code>req</code> specifies the varible name in <code>after</code> to receive the request.</div>
    </td>
    <td class='arc'><pre>
&gt;(urform user req "newpage" (prn "Form") (submit))

</pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='when-umatch'></a>
<img src='macro.gif' title='Macro'/>
<span class='op'>when-umatch</span> <span class='args'>user req [body...]</span>
    <div class='desc'>If <code>user</code> matches the user associated with <code>req</code>, executes <code>body</code>.  Otherwise executes <code>mismatch-message</code>.</div>
    </td>
    <td class='arc'><pre>
&gt;(defopl ul req (let user (get-user req)
  (when-umatch user req (prn "You are " user))))

</pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='when-umatch/r'></a>
<img src='macro.gif' title='Macro'/>
<span class='op'>when-umatch/r</span> <span class='args'>user req [body ...]</span>
    <div class='desc'>Test <code>user</code> for use with redirect.  If <code>user</code> is the user associated with <code>req</code>, executes body.  Otherwise returns "mismatch", to redirect to the mismatch page.</div>
    </td>
    <td class='arc'><pre>
&gt;(when-umatch/r user req (logout-user user) "example")

</pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='ulink'></a>
<img src='macro.gif' title='Macro'/>
<span class='op'>ulink</span> <span class='args'>user text [body ...]</span>
    <div class='desc'>Outputs a HTML link with <code>text</code>.  When clicked, the link will execute <code>body</code> if the user matches <code>user</code>.  Similar to <code>onlink</code>, but with the user guard.  Renamed from userlink in arc3.</div>
    </td>
    <td class='arc'><pre>
&gt;(userlink user "click here" (prn "Thanks for clicking"))

</pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='admin-page'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>admin-page</span> <span class='args'>user [msg]</span>
    <div class='desc'>Generates the administrator page. This page allows new accounts to be created.  The current admin login (<code>user</code>) is displayed at the top of the page, along with <code>msg</code>, if present.</div>
    </td>
    <td class='arc'><pre>
&gt;(admin-page user "Please administer...")

</pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='login-page'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>login-page</span> <span class='args'>switch [msg [afterward]]</span>
    <div class='desc'>Generates a login page.  <code>switch</code> is <code>'register</code>, <code>'login</code>, or <code>'both</code>, allowing account creation, account login, or both operations respectively.  The top of the page displays <code>msg</code>.  After the page completes, the <code>afterward</code> continuation is executed (by default <code>hello-page</code>).  <code>afterward</code> is either a function or a (function, redirect-string) pair.  The function takes the user name and IP as arguments.</div>
    </td>
    <td class='arc'><pre>
&gt;(defop mylogin req (login-page 'login "Hello"
    (fn (user ip) (prn "Welcome " user ip))))

</pre>
  </td></tr>
</table>
<h2>Typed and marked-up forms</h2>
<p><table class='arc'>
  <tr>
    <td class='arc'><a name='vars-form'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>vars-form</span> <span class='args'>user fields f done [button [lasts]]</span>
    <div class='desc'>Generates a form for <code>user</code>.  <code>fields</code> is a list of <code>(type label value view modify question)</code> lists specifying the form.  When submitted, <code>f</code> is executed on each field, with the arguments <code>label newval</code>.  Then continuation function <code>done</code> is executed. If there is a modifiable field, a submit button is generated with label specified by <code>button</code>.  The lifetime of the associated fnid can be specified with <code>lasts</code>.</div>
    </td>
    <td class='arc'>  </td></tr>
  <tr>
    <td class='arc'><a name='md-from-form'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>md-from-form</span> <span class='args'>str [nolinks]</span>
    <div class='desc'>Converts <code>str</code> to markdown after escaping it.  URLs will be converted to links unless <code>nolinks</code> is set.  Used to generate markdown from form input.</div>
    </td>
    <td class='arc'><pre>
&gt;(md-from-form "Hello *world* &amp;")
<span class="return">"Hello &lt;i&gt;world&lt;/i&gt; &amp;#38;"
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='markdown'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>markdown</span> <span class='args'>s [maxurl [nolinks]]</span>
    <div class='desc'>Applies the markdown rules to <code>s</code> to generate HTML.</div>
    </td>
    <td class='arc'><pre>
&gt;(prn (markdown "Text\n\n  Code\nhttp://arcfn.com, and *stuff*"))
<span class="stdout">Text&lt;p&gt;&lt;pre&gt;&lt;code&gt;  Code&lt;/code&gt;&lt;/pre&gt;

&lt;a href="http://arcfn.com" rel="nofollow"&gt;http://arcfn.com
&lt;/a&gt;, and &lt;i&gt;stuff&lt;/i&gt;

</span></pre>
<hr/>
Text<p><pre><code>  Code</code></pre>
<a href="http://arcfn.com" rel="nofollow">http://arcfn.com</a>, and <i>stuff</i>

  </td></tr>
  <tr>
    <td class='arc'><a name='unmarkdown'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>unmarkdown</span> <span class='args'>s</span>
    <div class='desc'>Inverse of <code>markdown</code> to convert HTML to a marked-down string.</div>
    </td>
    <td class='arc'><pre>
&gt;(unmarkdown "Text&lt;p&gt;&lt;pre&gt;&lt;code&gt;  Code&lt;/code&gt;&lt;/pre&gt;")
<span class="return">"Text\n\n  Code"
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='paras'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>paras</span> <span class='args'>s</span>
    <div class='desc'>Returns list of paragraph indices.  New in arc3.</div>
    </td>
    <td class='arc'><pre>
&gt;(paras "ab\n\ncde\n\nfgh")
<span class="return">("ab" "cde" "fgh")
</span></pre>
  </td></tr>
</table>
<h2>Variables</h2>
<p><table class='arc'>
  <tr>
    <td class='arc'><a name='good-logins*'></a>
<img src='var.gif' title='Variable'/>
<span class='op'>good-logins*</span> <span class='args'></span>
    <div class='desc'>A queue of successful logins, holding lists of the timestamp, IP, and user id.</div>
    </td>
    <td class='arc'>  </td></tr>
  <tr>
    <td class='arc'><a name='bad-logins*'></a>
<img src='var.gif' title='Variable'/>
<span class='op'>bad-logins*</span> <span class='args'></span>
    <div class='desc'>A queue of unsuccessful logins, holding lists of the timestamp, IP, and user id.</div>
    </td>
    <td class='arc'>  </td></tr>
  <tr>
    <td class='arc'><a name='hpasswords*'></a>
<img src='var.gif' title='Variable'/>
<span class='op'>hpasswords*</span> <span class='args'></span>
    <div class='desc'>Table of passwords mapping from user to hash.</div>
    </td>
    <td class='arc'>  </td></tr>
  <tr>
    <td class='arc'><a name='admins*'></a>
<img src='var.gif' title='Variable'/>
<span class='op'>admins*</span> <span class='args'></span>
    <div class='desc'>Admin stuff.</div>
    </td>
    <td class='arc'>  </td></tr>
  <tr>
    <td class='arc'><a name='cookie->user*'></a>
<img src='var.gif' title='Variable'/>
<span class='op'>cookie->user*</span> <span class='args'></span>
    <div class='desc'>Table mapping cookies to users.</div>
    </td>
    <td class='arc'>  </td></tr>
  <tr>
    <td class='arc'><a name='user->cookie*'></a>
<img src='var.gif' title='Variable'/>
<span class='op'>user->cookie*</span> <span class='args'></span>
    <div class='desc'>Table mapping users to cookies.</div>
    </td>
    <td class='arc'>  </td></tr>
  <tr>
    <td class='arc'><a name='logins*'></a>
<img src='var.gif' title='Variable'/>
<span class='op'>logins*</span> <span class='args'></span>
    <div class='desc'>Table of logins mapping from user name to IP address.</div>
    </td>
    <td class='arc'>  </td></tr>
  <tr>
    <td class='arc'><a name='hpwfile*'></a>
<img src='var.gif' title='Variable'/>
<span class='op'>hpwfile*</span> <span class='args'></span>
    <div class='desc'>Password file, backs <code>hpasswords*</code>.</div>
    </td>
    <td class='arc'><pre>
&gt;hpwfile*
<span class="return">"arc/hpw"
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='adminfile*'></a>
<img src='var.gif' title='Variable'/>
<span class='op'>adminfile*</span> <span class='args'></span>
    <div class='desc'>Admin file, backs <code>admins*</code>.</div>
    </td>
    <td class='arc'><pre>
&gt;adminfile*
<span class="return">"arc/admins"
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='cookfile*'></a>
<img src='var.gif' title='Variable'/>
<span class='op'>cookfile*</span> <span class='args'></span>
    <div class='desc'>Cookie file, backs <code>cookie->user*</code>.</div>
    </td>
    <td class='arc'><pre>
&gt;cookfile*
<span class="return">"arc/cooks"
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='formwid*'></a>
<img src='var.gif' title='Variable'/>
<span class='op'>formwid*</span> <span class='args'></span>
    <div class='desc'>Specifies width of form field.</div>
    </td>
    <td class='arc'><pre>
&gt;formwid*
<span class="return">60
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='bigformwid*'></a>
<img src='var.gif' title='Variable'/>
<span class='op'>bigformwid*</span> <span class='args'></span>
    <div class='desc'></div>
    </td>
    <td class='arc'><pre>
&gt;bigformwid*
<span class="return">80
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='numwid*'></a>
<img src='var.gif' title='Variable'/>
<span class='op'>numwid*</span> <span class='args'></span>
    <div class='desc'></div>
    </td>
    <td class='arc'><pre>
&gt;numwid*
<span class="return">16
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='formatdoc-url*'></a>
<img src='var.gif' title='Variable'/>
<span class='op'>formatdoc-url*</span> <span class='args'></span>
    <div class='desc'></div>
    </td>
    <td class='arc'><pre>
&gt;formatdoc-url*
<span class="return">nil
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='oidfile*'></a>
<img src='var.gif' title='Variable'/>
<span class='op'>oidfile*</span> <span class='args'></span>
    <div class='desc'>Openids file; apparently unused.  New in arc3.</div>
    </td>
    <td class='arc'><pre>
&gt;oidfile*
<span class="return">"arc/openids"
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='dc-usernames*'></a>
<img src='var.gif' title='Variable'/>
<span class='op'>dc-usernames*</span> <span class='args'></span>
    <div class='desc'>Downcased usernames.  New in arc3.</div>
    </td>
    <td class='arc'><pre>
&gt;dc-usernames*
<span class="return">#hash()
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='months*'></a>
<img src='var.gif' title='Variable'/>
<span class='op'>months*</span> <span class='args'></span>
    <div class='desc'>Month names.  New in arc3.</div>
    </td>
    <td class='arc'><pre>
&gt;months*
<span class="return">("January" "February" "March" "April" "May" "June" "July" "August" "September" "October" "November" "December")
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='month-names*'></a>
<img src='var.gif' title='Variable'/>
<span class='op'>month-names*</span> <span class='args'></span>
    <div class='desc'>Table from month name to month number.  New in arc3.</div>
    </td>
    <td class='arc'><pre>
&gt;(month-names* "jan")
<span class="return">1
</span></pre>
<pre>
&gt;(month-names* "February")
<span class="return">nil
</span></pre>
  </td></tr>
</table>
<h2>Internals</h2>
<p><table class='arc'>
  <tr>
    <td class='arc'><a name='load-userinfo'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>load-userinfo</span> <span class='args'></span>
    <div class='desc'>Initializes <code>hpasswords*</code>, <code>admins*</code>, and <code>cookie->user</code>.</div>
    </td>
    <td class='arc'><pre>
&gt;(load-userinfo)

</pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='mismatch-message'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>mismatch-message</span> <span class='args'></span>
    <div class='desc'>Prints an error message if the user doesn't match the cookie.</div>
    </td>
    <td class='arc'><pre>
&gt;(mismatch-message)
<span class="stdout">Dead link: users don't match.

</span><span class="return">"Dead link: users don't match."
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='admin-gate'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>admin-gate</span> <span class='args'>user</span>
    <div class='desc'>Gates access to admin-page.  If <code>user</code> is an admin, displays <code>admin-page</code>, otherwise redirects to <code>login-page</code>.</div>
    </td>
    <td class='arc'><pre>
&gt;(admin-gate "myuserid")
t
</pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='user-exists'></a>
<img src='proc.gif' title='Procedure'/>
<img src='predicate.gif' title='Predicate'/>
<span class='op'>user-exists</span> <span class='args'>user</span>
    <div class='desc'>Tests if <code>user</code> is not <code>nil</code> and present in <code>hpasswords*</code>.</div>
    </td>
    <td class='arc'><pre>
&gt;(user-exists "myuserid")
t
</pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='cook-user'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>cook-user</span> <span class='args'>user</span>
    <div class='desc'>Generates and saves a cookie for <code>user</code>.  Returns the cookie id.</div>
    </td>
    <td class='arc'><pre>
&gt;(cook-user "testuser")
<span class="return">wcXi0tW4
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='new-user-cookie'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>new-user-cookie</span> <span class='args'></span>
    <div class='desc'>Generates a unique cookie id.</div>
    </td>
    <td class='arc'><pre>
&gt;(new-user-cookie)
<span class="return">BWYtAvav
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='create-acct'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>create-acct</span> <span class='args'>user pw</span>
    <div class='desc'>Creates a user account.  Just a wrapper around <code>set-pw</code>.</div>
    </td>
    <td class='arc'><pre>
&gt;(create-acct "foo" "secret")
<span class="return">(("foo" "(stdin)= e5e9fa1ba31ecd1ae84f75caaa474f3a663f05f4"))
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='disable-acct'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>disable-acct</span> <span class='args'>user</span>
    <div class='desc'>Disables user account by logging user out and changing the password to a random string.</div>
    </td>
    <td class='arc'><pre>
&gt;(disable-acct "badperson")
<span class="return">((wcXi0tW4 "testuser"))
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='hello-page'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>hello-page</span> <span class='args'>user ip</span>
    <div class='desc'>Displays a simple page saying 'hello <i>user</i> at <i>ip</i>'.</div>
    </td>
    <td class='arc'>  </td></tr>
  <tr>
    <td class='arc'><a name='prcookie'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>prcookie</span> <span class='args'>cook</span>
    <div class='desc'>Prints a header field to update cookie <code>user</code> to the value <code>cook</code>.</div>
    </td>
    <td class='arc'><pre>
&gt;(prcookie "myvalue")
<span class="stdout">Set-Cookie: user=myvalue; expires=Sun, 17-Jan-2038 19:14:07 
GMT

</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='pwfields'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>pwfields</span> <span class='args'>[label]</span>
    <div class='desc'>Generates HTML for username and password fields, and a submit button, labelled "login" by default.</div>
    </td>
    <td class='arc'><pre>
&gt;(pwfields)
<span class="stdout">&lt;table border=0&gt;&lt;tr&gt;&lt;td&gt;username:&lt;/td&gt;&lt;td&gt;
&lt;input type=text name="u" size=20&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;
&lt;td&gt;password:&lt;/td&gt;&lt;td&gt;&lt;input type=password name="p" size=20&gt;
&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&lt;br&gt;
&lt;input type=submit value="login"&gt;
</span></pre>
<hr/>
<table border=0><tr><td>username:</td><td><input type=text name="u" size=20></td></tr><tr><td>password:</td><td><input type=password name="p" size=20></td></tr></table><br>
<input type=submit value="login">
  </td></tr>
  <tr>
    <td class='arc'><a name='good-login'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>good-login</span> <span class='args'>user pw ip</span>
    <div class='desc'>Tests if the user and password are valid according to <code>hpasswords*</code>.  Returns <code>user</code> on success, and <code>nil</code> on failure.  Updates <code>good-logins*</code> or <code>bad-logins</code> as appropriate.</div>
    </td>
    <td class='arc'><pre>
&gt;(good-login "foo" "bar" "127.0.0.1")
<span class="return">nil
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='shash'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>shash</span> <span class='args'>str</span>
    <div class='desc'>Hashes <code>str</code> to a sha1 digest using <code>openssl</code>.</div>
    </td>
    <td class='arc'><pre>
&gt;(shash "foo")
<span class="return">"(stdin)= 0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33"
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='bad-newacct'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>bad-newacct</span> <span class='args'>user pw</span>
    <div class='desc'>Tests if the new userid and password are bad (bad length, bad characters, or already in use).  Returns an error message if the new account specification is bad, and <code>nil</code> if the information is okay.</div>
    </td>
    <td class='arc'><pre>
&gt;(bad-newacct "foo" "x")
<span class="return">"That username is taken. Please choose another."
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='varfield'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>varfield</span> <span class='args'>typ id val</span>
    <div class='desc'>Prints HTML for an input field of type <code>typ</code>, name <code>id</code>, and value <code>val</code>.  <code>typ</code> is one of
<code>bigtoks</code>, <code>date</code>, <code>doc</code>, <code>int</code>, <code>lines</code>, <code>mdtext</code>, <code>mdtext2</code>, <code>num</code>, <code>posint</code>, <code>string</code>, <code>string1</code>, <code>sym</code>, <code>syms</code>, <code>text</code>, <code>time</code>, <code>toks</code>, <code>url</code>, <code>users</code>.  The type of field and the processing of val depend on <code>typ</code>.</div>
    </td>
    <td class='arc'><pre>
&gt;(varfield 'syms 'foo '(a b c))
<span class="stdout">&lt;textarea cols=60 rows=5 wrap=virtual name="foo"&gt;
a b c
&lt;/textarea&gt;
</span></pre>
<hr/>
<textarea cols=60 rows=5 wrap=virtual name="foo">
a b c</textarea>
  </td></tr>
  <tr>
    <td class='arc'><a name='text-rows'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>text-rows</span> <span class='args'>text width [pad]</span>
    <div class='desc'>Detemines how many rows to hold <code>text</code> based on <code>width</code> and padding.</div>
    </td>
    <td class='arc'><pre>
&gt;(text-rows "abcde" 2)
<span class="return">6
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='needrows'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>needrows</span> <span class='args'>text cols [pad]</span>
    <div class='desc'>Determines how many rows are needed to hold <code>text</code>, based on the length of the text and the number of newlines.</div>
    </td>
    <td class='arc'><pre>
&gt;(needrows "abcde" 2)
<span class="return">1
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='varline'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>varline</span> <span class='args'>type id val [liveurls]</span>
    <div class='desc'>Prints <code>val</code> according to <code>type</code>.  <code>id</code> is ignored.  If <code>liveurls</code> is true, links will be made to URLs.</div>
    </td>
    <td class='arc'><pre>
&gt;(varline 'yesno 'junk 1)
<span class="stdout">yes
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='text-type'></a>
<img src='proc.gif' title='Procedure'/>
<img src='predicate.gif' title='Predicate'/>
<span class='op'>text-type</span> <span class='args'>type</span>
    <div class='desc'>Tests if <code>type</code> is one of <code>string</code>, <code>string1</code>, <code>url</code>, <code>text</code>, <code>mdtext</code>, <code>mdtext2</code>.</div>
    </td>
    <td class='arc'><pre>
&gt;(text-type 'string1)
<span class="return">t
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='readvar'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>readvar</span> <span class='args'>type str [fail]</span>
    <div class='desc'>Reads variable of <code>type</code> from <code>str</code>.  Returns <code>fail</code> (default <code>nil</code> on failure).</div>
    </td>
    <td class='arc'><pre>
&gt;(readvar 'string "a&lt;b&gt;c")
<span class="return">"ac"
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='showvars'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>showvars</span> <span class='args'>fields [liveurls]</span>
    <div class='desc'>Generates table rows for a <code>varfield</code> list of fields.  If liveurls is true, will make links to URLs.</div>
    </td>
    <td class='arc'>  </td></tr>
  <tr>
    <td class='arc'><a name='indented-code'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>indented-code</span> <span class='args'>s i [newlines [spaces]]</span>
    <div class='desc'>Tests if <code>s</code> is indented code under the markup rules.  Returns a pair of the index of the start of the code, and the number of spaces of indentation.  Returns <code>nil</code> if not indented code.  The first <code>i</code> characters are skipped.</div>
    </td>
    <td class='arc'><pre>
&gt;(indented-code "\n\n  abc" 0)
<span class="return">(4 2)
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='parabreak'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>parabreak</span> <span class='args'>s i [newlines]</span>
    <div class='desc'>If <code>s</code> starts with a paragraph break (at least one blank line), returns the index of the start of the paragraph.  Otherwise returns <code>nil</code>.  Skips the first <code>i</code> characters.</div>
    </td>
    <td class='arc'><pre>
&gt;(parabreak "\n\nabc\ndef" 0)
<span class="return">2
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='urlend'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>urlend</span> <span class='args'>s i</span>
    <div class='desc'>Finds the logical end of a URL embedded in a string, and returns the index of the first character not in the URL.  The first <code>i</code> characters are skipped.</div>
    </td>
    <td class='arc'><pre>
&gt;(let url "http://arcfn.com; stuff" (cut url 0 (urlend url 0)))
<span class="return">"http://arcfn.com"
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='delimc'></a>
<img src='proc.gif' title='Procedure'/>
<img src='predicate.gif' title='Predicate'/>
<span class='op'>delimc</span> <span class='args'>c</span>
    <div class='desc'>Tests if <code>c</code> is a delimiter: a parenthesis, square bracket, curly bracket, or double quote.</div>
    </td>
    <td class='arc'><pre>
&gt;(delimc #\})
<span class="stdout">Error: _delimc: undefined;
 cannot reference an identifier b
efore its definition
  in module: top-level
  internal name:
 _delimc

</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='code-block'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>code-block</span> <span class='args'>s i</span>
    <div class='desc'>Markdown formatting: Returns a 'code block', which is terminated by a line that is not indented with whitespace.  The first <code>i+1</code> characters are skipped.</div>
    </td>
    <td class='arc'><pre>
&gt;(code-block "abc\n def\n ghi\njkl" 0)
<span class="return">"bc\n def\n ghi"
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='login-form'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>login-form</span> <span class='args'>label switch handler afterward</span>
    <div class='desc'>Creates login form for login-page.  New in arc3.</div>
    </td>
    <td class='arc'>  </td></tr>
  <tr>
    <td class='arc'><a name='login-handler'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>login-handler</span> <span class='args'>req switch afterward</span>
    <div class='desc'>Handler called from login-page.  New in arc3.</div>
    </td>
    <td class='arc'>  </td></tr>
  <tr>
    <td class='arc'><a name='create-handler'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>create-handler</span> <span class='args'>req switch afterward</span>
    <div class='desc'>Handler called from login-page to create account.  New in arc3.</div>
    </td>
    <td class='arc'>  </td></tr>
  <tr>
    <td class='arc'><a name='login'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>login</span> <span class='args'>user ip cookie afterward</span>
    <div class='desc'>Handles successful login.  New in arc3.</div>
    </td>
    <td class='arc'>  </td></tr>
  <tr>
    <td class='arc'><a name='failed-login'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>failed-login</span> <span class='args'>user ip cookie afterward</span>
    <div class='desc'>Handles login failure.  New in arc3.</div>
    </td>
    <td class='arc'>  </td></tr>
  <tr>
    <td class='arc'><a name='username-taken'></a>
<img src='proc.gif' title='Procedure'/>
<img src='predicate.gif' title='Predicate'/>
<span class='op'>username-taken</span> <span class='args'>user</span>
    <div class='desc'>Tests if username is in dc-usernames* and updates that table.  New in arc3.</div>
    </td>
    <td class='arc'><pre>
&gt;(username-taken "joe")
<span class="return">nil
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='next-parabreak'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>next-parabreak</span> <span class='args'>s i</span>
    <div class='desc'>Returns index of next paragraph break after i, if any.  New in arc3.</div>
    </td>
    <td class='arc'><pre>
&gt;(next-parabreak "ab\n\ncd" 0)
<span class="return">(2 4)
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='opendelim'></a>
<img src='proc.gif' title='Procedure'/>
<img src='predicate.gif' title='Predicate'/>
<span class='op'>opendelim</span> <span class='args'>c</span>
    <div class='desc'>Tests is character is an opening delimiter.  New in arc3.</div>
    </td>
    <td class='arc'><pre>
&gt;(opendelim #\&lt;)
<span class="return">t
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='closedelim'></a>
<img src='proc.gif' title='Procedure'/>
<img src='predicate.gif' title='Predicate'/>
<span class='op'>closedelim</span> <span class='args'>c</span>
    <div class='desc'>Tests is character is an closing delimiter.  New in arc3.</div>
    </td>
    <td class='arc'><pre>
&gt;(closedelim #\])
<span class="return">t
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='english-time'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>english-time</span> <span class='args'>min</span>
    <div class='desc'>Converts time in minutes to string.  New in arc3.</div>
    </td>
    <td class='arc'><pre>
&gt;(english-time 720)
<span class="return">"12:00 noon"
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='parse-time'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>parse-time</span> <span class='args'>s</span>
    <div class='desc'>Parses a time string to minutes.  New in arc3.</div>
    </td>
    <td class='arc'><pre>
&gt;(parse-time "12:30pm")
<span class="return">750
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='english-date'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>english-date</span> <span class='args'>(y m d)</span>
    <div class='desc'>Converts date to string.  New in arc3.</div>
    </td>
    <td class='arc'><pre>
&gt;(english-date (2009 6 8))
<span class="stdout">Error: Function call on inappropriate object 2009 (6 8)

</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='monthnum'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>monthnum</span> <span class='args'>s</span>
    <div class='desc'>Converts month name to number.  New in arc3.</div>
    </td>
    <td class='arc'><pre>
&gt;(monthnum "Mar")
<span class="return">3
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='date-nums'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>date-nums</span> <span class='args'>s</span>
    <div class='desc'>Used by date-nums to parses a date string to (y m d).  New in arc3.</div>
    </td>
    <td class='arc'><pre>
&gt;(date-nums "2009-12-31")
<span class="return">(2009 12 31)
</span></pre>
<pre>
&gt;(date-nums "December 31, 2009")
<span class="return">(2009 12 31)
</span></pre>
<pre>
&gt;(date-nums "June 5")
<span class="return">(2018 6 5)
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='valid-date'></a>
<img src='proc.gif' title='Procedure'/>
<img src='predicate.gif' title='Predicate'/>
<span class='op'>valid-date</span> <span class='args'>(y m d)</span>
    <div class='desc'>Minimal validation on date.  New in arc3.</div>
    </td>
    <td class='arc'><pre>
&gt;(valid-date '(2009 1 31))
<span class="return">t
</span></pre>
<pre>
&gt;(valid-date '(2009 2 31))
<span class="return">t
</span></pre>
<pre>
&gt;(valid-date '(2009 2 32))
<span class="return">nil
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='parse-date'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>parse-date</span> <span class='args'>s</span>
    <div class='desc'>Parses a date string to (y m d) with some validation.  New in arc3.</div>
    </td>
    <td class='arc'><pre>
&gt;(parse-date "2009-12-31")
<span class="return">(2009 12 31)
</span></pre>
<pre>
&gt;(parse-date "December 32, 2009")
<span class="stdout">Error: Invalid date: December 32, 2009

</span></pre>
  </td></tr>
</table>
<p>
Copyright 2008 Ken Shirriff.
</body>
</html>