changeset 542:31482f333362

Start of Ur/Web library
author Adam Chlipala <adamc@hcoop.net>
date Sat, 06 Dec 2008 13:04:48 -0500
parents 2bf2d0e0fb61
children c01415a171ed
files doc/manual.tex
diffstat 1 files changed, 47 insertions(+), 0 deletions(-) [+]
line wrap: on
line diff
--- 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