# HG changeset patch # User Adam Chlipala # Date 1283867226 14400 # Node ID 41484478a32d8af44fd5741c7883b5857fd0e0d3 # Parent 0d3d9e653829b842e14557777beb095d1d7c77d2 Updating documentation diff -r 0d3d9e653829 -r 41484478a32d CHANGELOG --- a/CHANGELOG Tue Sep 07 09:21:51 2010 -0400 +++ b/CHANGELOG Tue Sep 07 09:47:06 2010 -0400 @@ -3,7 +3,12 @@ ======== - Polymorphic variants (see Basis.variant) +- New 'onError' directive for .urp files - (* *) and comments in XML +- Basis.classes, Basis.confirm, and Basis.tryDml +- Invocations like 'urweb foo' will compile foo.ur as a single-file project, + even if no foo.urp exists +- Bug fixes and optimization improvements ======== 20100603 diff -r 0d3d9e653829 -r 41484478a32d doc/manual.tex --- a/doc/manual.tex Tue Sep 07 09:21:51 2010 -0400 +++ b/doc/manual.tex Tue Sep 07 09:47:06 2010 -0400 @@ -147,6 +147,7 @@ \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 @@ \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 @@ 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 @@ 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 @@ \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 @@ \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 @@ \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.