# HG changeset patch
# User Adam Chlipala <adamc@hcoop.net>
# Date 1228586688 18000
# Node ID 31482f333362d1527163c9b7370701bfeab4867b
# Parent  2bf2d0e0fb61df1a13748a4add56d8ef25b5950d
Start of Ur/Web library

diff -r 2bf2d0e0fb61 -r 31482f333362 doc/manual.tex
--- a/doc/manual.tex	Sat Dec 06 12:01:12 2008 -0500
+++ b/doc/manual.tex	Sat Dec 06 13:04:48 2008 -0500
@@ -915,4 +915,51 @@
 Constructor, constraint, and type class witness members of structures may be omitted, when those structures are used in contexts where their assigned signatures imply how to fill in those missing members.  This feature combines well with reverse-engineering to allow for uses of complicated meta-programming functors with little more code than would be necessary to invoke an untyped, ad-hoc code generator.
 
 
+\section{The Ur Standard Library}
+
+The built-in parts of the Ur/Web standard library are described by the signature in \texttt{lib/basis.urs} in the distribution.  A module $\mt{Basis}$ ascribing to that signature is available in the initial environment, and every program is implicitly prefixed by $\mt{open} \; \mt{Basis}$.
+
+Additionally, other common functions that are definable within Ur are included in \texttt{lib/top.urs} and \texttt{lib/top.ur}.  This $\mt{Top}$ module is also opened implicitly.
+
+The idea behind Ur is to serve as the ideal host for embedded domain-specific languages.  For now, however, the ``generic'' functionality is intermixed with Ur/Web-specific functionality, including in these two library modules.  We hope that these generic library components have types that speak for themselves.  The next section introduces the Ur/Web-specific elements.  Here, we only give the type declarations from the beginning of $\mt{Basis}$.
+
+$$\begin{array}{l}
+  \mt{type} \; \mt{int} \\
+  \mt{type} \; \mt{float} \\
+  \mt{type} \; \mt{string} \\
+  \mt{type} \; \mt{time} \\
+  \\
+  \mt{type} \; \mt{unit} = \{\} \\
+  \\
+  \mt{datatype} \; \mt{bool} = \mt{False} \mid \mt{True} \\
+  \\
+  \mt{datatype} \; \mt{option} \; \mt{t} = \mt{None} \mid \mt{Some} \; \mt{of} \; \mt{t}
+\end{array}$$
+
+
+\section{The Ur/Web Standard Library}
+
+\subsection{Transactions}
+
+Ur is a pure language; we use Haskell's trick to support controlled side effects.  The standard library defines a monad $\mt{transaction}$, meant to stand for actions that may be undone cleanly.  By design, no other kinds of actions are supported.
+
+$$\begin{array}{l}
+  \mt{con} \; \mt{transaction} :: \mt{Type} \to \mt{Type} \\
+  \\
+  \mt{val} \; \mt{return} : \mt{t} ::: \mt{Type} \to \mt{t} \to \mt{transaction} \; \mt{t} \\
+  \mt{val} \; \mt{bind} : \mt{t_1} ::: \mt{Type} \to \mt{t_2} ::: \mt{Type} \to \mt{transaction} \; \mt{t_1} \to (\mt{t_1} \to \mt{transaction} \; \mt{t_2}) \to \mt{transaction} \; \mt{t_2}
+\end{array}$$
+
+\subsection{HTTP}
+
+There are transactions for reading an HTTP header by name and for getting and setting strongly-typed cookies.  Cookies may only be created by the $\mt{cookie}$ declaration form, ensuring that they be named consistently based on module structure.
+
+$$\begin{array}{l}
+\mt{val} \; \mt{requestHeader} : \mt{string} \to \mt{transaction} \; (\mt{option} \; \mt{string}) \\
+\\
+\mt{con} \; \mt{http\_cookie} :: \mt{Type} \to \mt{Type} \\
+\mt{val} \; \mt{getCookie} : \mt{t} ::: \mt{Type} \to \mt{http\_cookie} \; \mt{t} \to \mt{transaction} \; (\mt{option} \; \mt{t}) \\
+\mt{val} \; \mt{setCookie} : \mt{t} ::: \mt{Type} \to \mt{http\_cookie} \; \mt{t} \to \mt{t} \to \mt{transaction} \; \mt{unit}
+\end{array}$$
+
 \end{document}
\ No newline at end of file