Updating documentation

1 files changed, 21 insertions, 3 deletions

diff --git a/doc/manual.tex b/doc/manual.tex
index 4d8ff987..fa0f0fcd 100644
--- a/doc/manual.tex
+++ b/doc/manual.tex
@@ -147,6 +147,7 @@ Here is the complete list of directive forms.  ``FFI'' stands for ``foreign func
 \item \texttt{jsFunc Module.ident=name} gives the JavaScript name of an FFI value.
 \item \texttt{library FILENAME} parses \texttt{FILENAME.urp} and merges its contents with the rest of the current file's contents.  If \texttt{FILENAME.urp} doesn't exist, the compiler also tries \texttt{FILENAME/lib.urp}.
 \item \texttt{link FILENAME} adds \texttt{FILENAME} to the list of files to be passed to the GCC linker at the end of compilation.  This is most useful for importing extra libraries needed by new FFI modules.
+\item \texttt{onError Module.var} changes the handling of fatal application errors.  Instead of displaying a default, ugly error 500 page, the error page will be generated by calling function \texttt{Module.var} on a piece of XML representing the error message.  The error handler should have type $\mt{xbody} \to \mt{transaction} \; \mt{page}$.  Note that the error handler \emph{cannot} be in the application's main module, since that would register it as explicitly callable via URLs.
 \item \texttt{path NAME=VALUE} creates a mapping from \texttt{NAME} to \texttt{VALUE}.  This mapping may be used at the beginnings of filesystem paths given to various other configuration directives.  A path like \texttt{\$NAME/rest} is expanded to \texttt{VALUE/rest}.  There is an initial mapping from the empty name (for paths like \texttt{\$/list}) to the directory where the Ur/Web standard library is installed.  If you accept the default \texttt{configure} options, this directory is \texttt{/usr/local/lib/urweb/ur}.
 \item \texttt{prefix PREFIX} sets the prefix included before every URI within the generated application.  The default is \texttt{/}.
 \item \texttt{profile} generates an executable that may be used with gprof.
@@ -278,6 +279,7 @@ fastcgi.server = (
 \item \texttt{-static}: Link the runtime system statically.  The default is to link against dynamic libraries.
 \end{itemize}
 
+There is an additional convenience method for invoking \texttt{urweb}.  If the main argument is \texttt{FOO}, and \texttt{FOO.ur} exists but \texttt{FOO.urp} doesn't, then the invocation is interpreted as if called on a \texttt{.urp} file containing \texttt{FOO} as its only main entry, with an additional \texttt{rewrite all FOO/*} directive.
 
 \section{Ur Syntax}
 
@@ -311,6 +313,8 @@ We write $\ell$ for literals of the primitive types, for the most part following
 
 This version of the manual doesn't include operator precedences; see \texttt{src/urweb.grm} for that.
 
+As in the ML language family, the syntax \texttt{(* ... *)} is used for (nestable) comments.  Within XML literals, Ur/Web also supports the usual \texttt{<!-- ... -->} XML comments.
+
 \subsection{\label{core}Core Syntax}
 
 \emph{Kinds} classify types and other compile-time-only entities.  Each kind in the grammar is listed with a description of the sort of data it classifies.
@@ -1283,6 +1287,13 @@ $$\begin{array}{l}
 
 The only unusual element of this list is the $\mt{blob}$ type, which stands for binary sequences.  Simple blobs can be created from strings via $\mt{Basis.textBlob}$.  Blobs will also be generated from HTTP file uploads.
 
+Ur also supports \emph{polymorphic variants}, a dual to extensible records that has been popularized by OCaml.  A type $\mt{variant} \; r$ represents an $n$-ary sum type, with one constructor for each field of record $r$.  Each constructor $c$ takes an argument of type $r.c$; the type $\{\}$ can be used to ``simulate'' a nullary constructor.  The \cd{make} function builds a variant value, while \cd{match} implements pattern-matching, with match cases represented as records of functions.
+$$\begin{array}{l}
+  \mt{con} \; \mt{variant} :: \{\mt{Type}\} \to \mt{Type} \\
+  \mt{val} \; \mt{make} : \mt{nm} :: \mt{Name} \to \mt{t} ::: \mt{Type} \to \mt{ts} ::: \{\mt{Type}\} \to [[\mt{nm}] \sim \mt{ts}] \Rightarrow \mt{t} \to \mt{variant} \; ([\mt{nm} = \mt{t}] \rc \mt{ts}) \\
+  \mt{val} \; \mt{match} : \mt{ts} ::: \{\mt{Type}\} \to \mt{t} ::: \mt{Type} \to \mt{variant} \; \mt{ts} \to \$(\mt{map} \; (\lambda \mt{t'} \Rightarrow \mt{t'} \to \mt{t}) \; \mt{ts}) \to \mt{t}
+\end{array}$$
+
 Another important generic Ur element comes at the beginning of \texttt{top.urs}.
 
 $$\begin{array}{l}
@@ -1750,6 +1761,12 @@ $$\begin{array}{l}
   \mt{val} \; \mt{dml} : \mt{dml} \to \mt{transaction} \; \mt{unit}
 \end{array}$$
 
+The function $\mt{Basis.dml}$ will trigger a fatal application error if the command fails, for instance, because a data integrity constraint is violated.  An alternate function returns an error message as a string instead.
+
+$$\begin{array}{l}
+  \mt{val} \; \mt{tryDml} : \mt{dml} \to \mt{transaction} \; (\mt{option} \; \mt{string})
+\end{array}$$
+
 Properly-typed records may be used to form $\mt{INSERT}$ commands.
 $$\begin{array}{l}
   \mt{val} \; \mt{insert} : \mt{fields} ::: \{\mt{Type}\} \to \mt{sql\_table} \; \mt{fields} \\
@@ -1808,7 +1825,7 @@ $$\begin{array}{l}
   \hspace{.1in} \to \mt{tag} \; (\mt{attrsGiven} \rc \mt{attrsAbsent}) \; \mt{ctxOuter} \; \mt{ctxInner} \; \mt{useOuter} \; \mt{bindOuter} \\
   \hspace{.1in} \to \mt{xml} \; \mt{ctxInner} \; \mt{useInner} \; \mt{bindInner} \to \mt{xml} \; \mt{ctxOuter} \; (\mt{useOuter} \rc \mt{useInner}) \; (\mt{bindOuter} \rc \mt{bindInner})
 \end{array}$$
-Note that any tag may be assigned a CSS class.  This is the sole way of making use of the values produced by $\mt{style}$ declarations.  Ur/Web itself doesn't deal with the syntax or semantics of style sheets; they can be linked via URLs with \texttt{link} tags.  However, Ur/Web does make it easy to calculate upper bounds on usage of CSS classes through program analysis.
+Note that any tag may be assigned a CSS class.  This is the sole way of making use of the values produced by $\mt{style}$ declarations.  Ur/Web itself doesn't deal with the syntax or semantics of style sheets; they can be linked via URLs with \texttt{link} tags.  However, Ur/Web does make it easy to calculate upper bounds on usage of CSS classes through program analysis.  The function $\mt{Basis.classes}$ can be used to specify a list of CSS classes for a single tag.
 
 Two XML fragments may be concatenated.
 $$\begin{array}{l}
@@ -1837,9 +1854,10 @@ Ur/Web supports running code on web browsers, via automatic compilation to JavaS
 
 \subsubsection{The Basics}
 
-Clients can open alert dialog boxes, in the usual annoying JavaScript way.
+Clients can open alert and confirm dialog boxes, in the usual annoying JavaScript way.
 $$\begin{array}{l}
-  \mt{val} \; \mt{alert} : \mt{string} \to \mt{transaction} \; \mt{unit}
+  \mt{val} \; \mt{alert} : \mt{string} \to \mt{transaction} \; \mt{unit} \\
+  \mt{val} \; \mt{confirm} : \mt{string} \to \mt{transaction} \; \mt{bool}
 \end{array}$$
 
 Any transaction may be run in a new thread with the $\mt{spawn}$ function.