Mercurial > urweb

comparison doc/manual.tex @ 1799:3d922a28370b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Basis.getenv
author Adam Chlipala <adam@chlipala.net>
date Thu, 02 Aug 2012 16:33:25 -0400
parents bb942416bf1c
children ae8b0e05522a
comparison
equal deleted inserted replaced
1798:10a2cb93d175 1799:3d922a28370b
133 133
134 For each entry \texttt{M} in the module list, the file \texttt{M.urs} is included in the project if it exists, and the file \texttt{M.ur} must exist and is always included. 134 For each entry \texttt{M} in the module list, the file \texttt{M.urs} is included in the project if it exists, and the file \texttt{M.ur} must exist and is always included.
135 135
136 Here is the complete list of directive forms. ``FFI'' stands for ``foreign function interface,'' Ur's facility for interaction between Ur programs and C and JavaScript libraries. 136 Here is the complete list of directive forms. ``FFI'' stands for ``foreign function interface,'' Ur's facility for interaction between Ur programs and C and JavaScript libraries.
137 \begin{itemize} 137 \begin{itemize}
138 \item \texttt{[allow|deny] [url|mime|requestHeader|responseHeader] PATTERN} registers a rule governing which URLs, MIME types, HTTP request headers, or HTTP response headers are allowed to appear explicitly in this application. The first such rule to match a name determines the verdict. If \texttt{PATTERN} ends in \texttt{*}, it is interpreted as a prefix rule. Otherwise, a string must match it exactly. 138 \item \texttt{[allow|deny] [url|mime|requestHeader|responseHeader|env] PATTERN} registers a rule governing which URLs, MIME types, HTTP request headers, HTTP response headers, or environment variable names are allowed to appear explicitly in this application. The first such rule to match a name determines the verdict. If \texttt{PATTERN} ends in \texttt{*}, it is interpreted as a prefix rule. Otherwise, a string must match it exactly.
139 \item \texttt{alwaysInline PATH} requests that every call to the referenced function be inlined. Section \ref{structure} explains how functions are assigned path strings. 139 \item \texttt{alwaysInline PATH} requests that every call to the referenced function be inlined. Section \ref{structure} explains how functions are assigned path strings.
140 \item \texttt{benignEffectful Module.ident} registers an FFI function or transaction as having side effects. The optimizer avoids removing, moving, or duplicating calls to such functions. Every effectful FFI function must be registered, or the optimizer may make invalid transformations. This version of the \texttt{effectful} directive registers that this function only has side effects that remain local to a single page generation. 140 \item \texttt{benignEffectful Module.ident} registers an FFI function or transaction as having side effects. The optimizer avoids removing, moving, or duplicating calls to such functions. Every effectful FFI function must be registered, or the optimizer may make invalid transformations. This version of the \texttt{effectful} directive registers that this function only has side effects that remain local to a single page generation.
141 \item \texttt{clientOnly Module.ident} registers an FFI function or transaction that may only be run in client browsers. 141 \item \texttt{clientOnly Module.ident} registers an FFI function or transaction that may only be run in client browsers.
142 \item \texttt{clientToServer Module.ident} adds FFI type \texttt{Module.ident} to the list of types that are OK to marshal from clients to servers. Values like XML trees and SQL queries are hard to marshal without introducing expensive validity checks, so it's easier to ensure that the server never trusts clients to send such values. The file \texttt{include/urweb.h} shows examples of the C support functions that are required of any type that may be marshalled. These include \texttt{attrify}, \texttt{urlify}, and \texttt{unurlify} functions. 142 \item \texttt{clientToServer Module.ident} adds FFI type \texttt{Module.ident} to the list of types that are OK to marshal from clients to servers. Values like XML trees and SQL queries are hard to marshal without introducing expensive validity checks, so it's easier to ensure that the server never trusts clients to send such values. The file \texttt{include/urweb.h} shows examples of the C support functions that are required of any type that may be marshalled. These include \texttt{attrify}, \texttt{urlify}, and \texttt{unurlify} functions.
143 \item \texttt{database DBSTRING} sets the string to pass to libpq to open a database connection. 143 \item \texttt{database DBSTRING} sets the string to pass to libpq to open a database connection.
1467 \mt{val} \; \mt{fileName} : \mt{file} \to \mt{option} \; \mt{string} \\ 1467 \mt{val} \; \mt{fileName} : \mt{file} \to \mt{option} \; \mt{string} \\
1468 \mt{val} \; \mt{fileMimeType} : \mt{file} \to \mt{string} \\ 1468 \mt{val} \; \mt{fileMimeType} : \mt{file} \to \mt{string} \\
1469 \mt{val} \; \mt{fileData} : \mt{file} \to \mt{blob} 1469 \mt{val} \; \mt{fileData} : \mt{file} \to \mt{blob}
1470 \end{array}$$ 1470 \end{array}$$
1471 1471
1472 It is also possible to get HTTP request headers and set HTTP response headers, using abstract types similar to the one for URLs. 1472 It is also possible to get HTTP request headers and environment variables, and set HTTP response headers, using abstract types similar to the one for URLs.
1473 1473
1474 $$\begin{array}{l} 1474 $$\begin{array}{l}
1475 \mt{type} \; \mt{requestHeader} \\ 1475 \mt{type} \; \mt{requestHeader} \\
1476 \mt{val} \; \mt{blessRequestHeader} : \mt{string} \to \mt{requestHeader} \\ 1476 \mt{val} \; \mt{blessRequestHeader} : \mt{string} \to \mt{requestHeader} \\
1477 \mt{val} \; \mt{checkRequestHeader} : \mt{string} \to \mt{option} \; \mt{requestHeader} \\ 1477 \mt{val} \; \mt{checkRequestHeader} : \mt{string} \to \mt{option} \; \mt{requestHeader} \\
1478 \mt{val} \; \mt{getHeader} : \mt{requestHeader} \to \mt{transaction} \; (\mt{option} \; \mt{string}) \\ 1478 \mt{val} \; \mt{getHeader} : \mt{requestHeader} \to \mt{transaction} \; (\mt{option} \; \mt{string}) \\
1479 \\
1480 \mt{type} \; \mt{envVar} \\
1481 \mt{val} \; \mt{blessEnvVar} : \mt{string} \to \mt{envVar} \\
1482 \mt{val} \; \mt{checkEnvVar} : \mt{string} \to \mt{option} \; \mt{envVar} \\
1483 \mt{val} \; \mt{getenv} : \mt{envVar} \to \mt{transaction} \; (\mt{option} \; \mt{string}) \\
1479 \\ 1484 \\
1480 \mt{type} \; \mt{responseHeader} \\ 1485 \mt{type} \; \mt{responseHeader} \\
1481 \mt{val} \; \mt{blessResponseHeader} : \mt{string} \to \mt{responseHeader} \\ 1486 \mt{val} \; \mt{blessResponseHeader} : \mt{string} \to \mt{responseHeader} \\
1482 \mt{val} \; \mt{checkResponseHeader} : \mt{string} \to \mt{option} \; \mt{responseHeader} \\ 1487 \mt{val} \; \mt{checkResponseHeader} : \mt{string} \to \mt{option} \; \mt{responseHeader} \\
1483 \mt{val} \; \mt{setHeader} : \mt{responseHeader} \to \mt{string} \to \mt{transaction} \; \mt{unit} 1488 \mt{val} \; \mt{setHeader} : \mt{responseHeader} \to \mt{string} \to \mt{transaction} \; \mt{unit}