summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorGravatar Adam Chlipala <adam@chlipala.net>2010-09-07 09:47:06 -0400
committerGravatar Adam Chlipala <adam@chlipala.net>2010-09-07 09:47:06 -0400
commitdf1314f40a89b39188c26a303f09e673bf061070 (patch)
tree310ff0ded426ee2e0f86e286871246d544624b33 /doc
parent2da3f4c86d4fbdfb2c88d7db3c1d9cc5f6e39092 (diff)
Updating documentation
Diffstat (limited to 'doc')
-rw-r--r--doc/manual.tex24
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.