Start of Ur/Web library

1 files changed, 47 insertions, 0 deletions

diff --git a/doc/manual.tex b/doc/manual.tex
index 8ef6a889..894287e1 100644
--- a/doc/manual.tex
+++ b/doc/manual.tex
@@ -915,4 +915,51 @@ It's useful to write Ur functions and functors that take record constructors as
 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