scsh-conservatory
/
sunet
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Fix typos and do some rephrasing.

This commit is contained in:
interp 2004-09-17 15:54:21 +00:00
parent 58a540854f
commit d904121149
3 changed files with 158 additions and 157 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

90
doc/latex/surfletapi.tex
View File

@ -18,7 +18,7 @@ add the \surflet handler to it, which resides in the
\begin{alltt} \begin{alltt}
(httpd (httpd
(make-httpd-options (make-httpd-options
\dots \dots \\
with-request-handler with-request-handler
(alist-path-dispatcher (alist-path-dispatcher
(list (list
@ -33,9 +33,10 @@ requests directed to \surflets. Here's the interface description:
\defun{surflet-handler}{options}{request-handler} \defun{surflet-handler}{options}{request-handler}
\begin{desc} \begin{desc}
This procedures sets up the \surflet handler and returns the request This procedures sets up the \surflet handler and returns the
handler for the SUnet webserver. The options argument is similar to according request handler for the SUnet webserver. The options
the one passed to \ex{httpd} and is exlpained below. argument is similar to the one passed to \ex{httpd} and is exlpained
below.
The \surflet handler accepts requests (solely) to \surflets whose The \surflet handler accepts requests (solely) to \surflets whose
file name must have the extension \ex{.scm}. The structure of file name must have the extension \ex{.scm}. The structure of
@ -127,7 +128,7 @@ For example,
\end{alltt} \end{alltt}
defines the \surflet handler to serve \surflets from the directory defines the \surflet handler to serve \surflets from the directory
\ex{root/surflets} and to timeout unused session after one hour. \ex{root/surflets} and to timeout unused sessions after one hour.
The \surflet handler allows runtime read and write access to her The \surflet handler allows runtime read and write access to her
options: options:
@ -188,12 +189,14 @@ the Scheme48 module language. See the documentation of Scheme48 for
details. details.
\surflets should not use the \ex{shift-reset} structure, as this might \surflets should not use the \ex{shift-reset} structure, as this might
confuse the \surflet handler. confuse the \surflet handler. The use of threads within a surflet is
currently discouraged, as some procedures might not work, especially
procedures dealing with session IDs.
\subsection{\surflet management} \subsection{\surflet management}
Upon an initial client request, the \surflet handler looks for the Upon an initial client request, the \surflet handler looks for the
requested \surflet, dynamically loads it, installs an error handler requested \surflet, loads it dynamically, installs an error handler
and calls the \ex{main} function of the \surflet with the initial and calls the \ex{main} function of the \surflet with the initial
\ex{surflet-request}. To minimize the time of loading a \surflet, \ex{surflet-request}. To minimize the time of loading a \surflet,
the \surflet handler caches the structure of the \surflet in a cache, the \surflet handler caches the structure of the \surflet in a cache,
@ -282,7 +285,7 @@ For some unknown weird cases, there are also these two procedures:
\subsection{Surflet Response} \subsection{Surflet Response}
\surflets answer to a request by sending an \ex{surflet-response} to \surflets answer to a request by sending a \ex{surflet-response} to
the \surflet handler. The next section deals with how the surflet the \surflet handler. The next section deals with how the surflet
responses are sent to the \surflet handler. The relevant procedures responses are sent to the \surflet handler. The relevant procedures
for \ex{surflet-response} are the following. They are all exported by for \ex{surflet-response} are the following. They are all exported by
@ -357,7 +360,10 @@ structures.
\defun{instance-session-id}{}{session-id} \defun{instance-session-id}{}{session-id}
\begin{desc} \begin{desc}
This returns the session ID for the current session. The current This returns the session ID for the current session. The current
session is the session from which the function is called. session is the session from which the function is called. The
\surflet handler guarantees that there won't be two sessions with
the same ID for any given point in time. However, session IDs may
be reused.
\end{desc} \end{desc}
\defun{get-session}{session-id}{session} \defun{get-session}{session-id}{session}
@ -435,21 +441,21 @@ of a session via the following procedures.
\defunx{session-continuation-table-lock}{session}{lock} \defunx{session-continuation-table-lock}{session}{lock}
\defunx{session-continuation-counter}{session}{thread-safe-counter} \defunx{session-continuation-counter}{session}{thread-safe-counter}
\begin{desc} \begin{desc}
These functions the continuation table, the lock for the These functions return the continuation table, the lock for the
continuation table and the counter for the continuations. The continuation table and the counter for the continuations,
continuation \var{table} is a hash table with the continuation ID as respectively. The continuation \var{table} is a hash table with the
key and the continuation as value, based on the \ex{tables} continuation ID as key and the continuation as value, based on the
structure of Scheme48. The \var{lock} is based on the \ex{locks} \ex{tables} structure of Scheme48. The \var{lock} is based on the
structure of Scheme48. The \var{thread-safe-counter} is based on \ex{locks} structure of Scheme48. The \var{thread-safe-counter} is
the \ex{thread-safe-counter} structure that is part of the based on the \ex{thread-safe-counter} structure that is part of the
\surflets. \surflets.
The access to these functions is currently unrestricted but may be The access to these functions is currently unrestricted but may be
restricted in future versions of the \surflet server. restricted in future versions of the \surflet server.
\end{desc} \end{desc}
The \exi{surflets/continuations} also offers procedures to access the The \exi{surflets/continuations} structure also offers procedures to
continuations. access the continuations.
\defun{get-continuations}{session}{list} \defun{get-continuations}{session}{list}
\begin{desc} \begin{desc}
@ -478,7 +484,7 @@ The \exi{surflets/continuations} also offers procedures to access the
The \exi{surflets/ids} structure provides procedures to determine the The \exi{surflets/ids} structure provides procedures to determine the
session and continuation IDs of the current session. See also the session and continuation IDs of the current session. See also the
entry for \ex{resume-url-ids} some where else in this document. entry for \ex{resume-url-ids} somewhere else in this document.
\defun{my-session-id}{surlfet-request}{number} \defun{my-session-id}{surlfet-request}{number}
\defunx{my-continuation-id}{surlfet-request}{number} \defunx{my-continuation-id}{surlfet-request}{number}
@ -538,7 +544,7 @@ the \ex{status-code} syntax.
\defun{send}{surflet-response}{\noreturn} \defun{send}{surflet-response}{\noreturn}
\begin{desc} \begin{desc}
This procedure send the data of the \var{surflet-response} to the This procedure sends the data of the \var{surflet-response} to the
client and does not return. client and does not return.
\end{desc} \end{desc}
@ -626,7 +632,8 @@ element of a list, right after the SXML tag.
\defunx{sxml-attribute-attributes}{sxml-attribute}{list} \defunx{sxml-attribute-attributes}{sxml-attribute}{list}
\begin{desc} \begin{desc}
These are procedures on SXML attribute forms. \ex{sxml-attribute?} These are procedures on SXML attribute forms. \ex{sxml-attribute?}
is a predicate for SXML attribute forms. is a predicate for SXML attribute forms. It checks if \var{object}
is a list whose first element is the symbol \ex{@}.
\ex{sxml-attribute-attributes} returns the list of name-value-lists \ex{sxml-attribute-attributes} returns the list of name-value-lists
of the attributes form. Both procedures are exported by the of the attributes form. Both procedures are exported by the
\exi{surflets/sxml} structure. \exi{surflets/sxml} structure.
@ -636,7 +643,7 @@ The translator translates list elements which are numbers and symbols
to their string representation (except for the first element, of to their string representation (except for the first element, of
course). She scans strings for the special characters \verb'&', course). She scans strings for the special characters \verb'&',
\verb'"', \verb'>' and \verb'<' and replaces them by their HTML \verb'"', \verb'>' and \verb'<' and replaces them by their HTML
equivalents, and she ignores \sharpf and the emtpy list. See below equivalents, and she ignores \sharpf\ and the emtpy list. See below
the special SXML tag \ex{plain-html} to see how to insert HTML code the special SXML tag \ex{plain-html} to see how to insert HTML code
untranslated. Furthermore, the translator accepts \ex{input-fields} untranslated. Furthermore, the translator accepts \ex{input-fields}
as list elements, which are translated to their HTML representation. as list elements, which are translated to their HTML representation.
@ -668,7 +675,7 @@ directly translate to an HTML tag.
\hfill\quad\textnormal{SXML-tag}}}\index{#1}} \hfill\quad\textnormal{SXML-tag}}}\index{#1}}
\defsxmltag{url}{URL [text]} \defsxmltag{url}{ URL [text]}
\begin{desc} \begin{desc}
Inserts a link to \var{URL}, named with \var{text}. \var{text} Inserts a link to \var{URL}, named with \var{text}. \var{text}
defaults to \var{URL}. Takes at least one argument. \Eg defaults to \var{URL}. Takes at least one argument. \Eg
@ -687,19 +694,19 @@ directly translate to an HTML tag.
Inserts the HTML sequence \ex{"\&nbsp;"}. Takes no arguments. Inserts the HTML sequence \ex{"\&nbsp;"}. Takes no arguments.
\end{desc} \end{desc}
\defsxmltag{plain-html}{html \ldots} \defsxmltag{plain-html}{ html \ldots}
\begin{desc} \begin{desc}
Inserts \var{html} without any changes, thus it works like a quote. Inserts \var{html} without any changes, thus it works like a quote.
Takes any number of arguments. Takes any number of arguments.
\end{desc} \end{desc}
\defsxmltag{*COMMENT*}{comment \ldots} \defsxmltag{*COMMENT*}{ comment \ldots}
\begin{desc} \begin{desc}
Inserts a comment, \ie \var{comment} enclosed between \verb|<!--| Inserts a comment, \ie \var{comment} enclosed between \verb|<!--|
and \verb|-->|. Takes any number of arguments. and \verb|-->|. Takes any number of arguments.
\end{desc} \end{desc}
\defsxmltag{surflet-form}{k-url [method] [attributes] [SXML \ldots]} \defsxmltag{surflet-form}{ k-url [method] [attributes] [SXML \ldots]}
\begin{desc} \begin{desc}
Inserts HTML code for a web form. See below for details. Inserts HTML code for a web form. See below for details.
\var{k-url} usually is a continuation-URL. \var{method} is the \var{k-url} usually is a continuation-URL. \var{method} is the
@ -722,14 +729,14 @@ this, a short introduction to the translation process.
The translation process takes place in two steps. Step one translates The translation process takes place in two steps. Step one translates
the given SXML to low level SXML, essentially a rough form of HTML in the given SXML to low level SXML, essentially a rough form of HTML in
list notation. Step two takes this low level SXML and prints to a list notation. Step two takes this low level SXML and prints it to a
port. Step one is performed by \ex{sxml->low-level-sxml}, step two by port. Step one is performed by \ex{sxml->low-level-sxml}, step two by
\ex{display-low-level-sxml}. All procedures and rules presented in \ex{display-low-level-sxml}. All procedures and rules presented in
this subsection are exported from \exi{surflets/sxml}. this subsection are exported from \exi{surflets/sxml}.
\defun{sxml->low-level-sxml}{sxml rules}{low-level-sxml} \defun{sxml->low-level-sxml}{sxml rules}{low-level-sxml}
\begin{desc} \begin{desc}
Takes an SXML object (which essentially is a list) and a list of Takes an SXML object (which is essentially a list) and a list of
SXML rules (more on this below) and translates it to low level SXML. SXML rules (more on this below) and translates it to low level SXML.
This procedure is an alias to the \ex{pre-post-order} procedure of This procedure is an alias to the \ex{pre-post-order} procedure of
Oleg Kiselyov's SSAX module. It is an error if no rule triggers Oleg Kiselyov's SSAX module. It is an error if no rule triggers
@ -742,8 +749,8 @@ this subsection are exported from \exi{surflets/sxml}.
Takes low level SXML and \ex{display}s it to a port. She traverses Takes low level SXML and \ex{display}s it to a port. She traverses
the list \var{low-level-sxml} depth-first, ignores the empty list the list \var{low-level-sxml} depth-first, ignores the empty list
and \sharpf, executes thunks and \ex{display}s all other elements, and \sharpf, executes thunks and \ex{display}s all other elements,
usually strings and characters, to \var{port}. Returns \sharpt if usually strings and characters, to \var{port}. Returns \sharpt\ if
she wrote anything, \sharpf otherwise. This function is basically she wrote anything, \sharpf\ otherwise. This function is basically
the \ex{SRV:send-reply} procedure of Oleg Kiselyov's SSAX module. the \ex{SRV:send-reply} procedure of Oleg Kiselyov's SSAX module.
\end{desc} \end{desc}
@ -867,11 +874,12 @@ for the double naming \ex{resume-url} and continuation-URL.
\defunx{resume-url-session-id}{resume-url}{session-id} \defunx{resume-url-session-id}{resume-url}{session-id}
\defunx{resume-url-continuation-id}{resume-url}{continuation-id} \defunx{resume-url-continuation-id}{resume-url}{continuation-id}
\begin{desc} \begin{desc}
These inspect values of a resume url. \ex{resume-url?} is predicate These inspect values of a resume url. \ex{resume-url?} is a
for resume urls. Note that it only operates on strings. predicate for resume urls (the same as continuation urls). Note
\ex{resume-url-ids} returns the session- and the continuation-id that it only operates on strings. \ex{resume-url-ids} returns the
that is stored in the \var{resume-url}. \ex{resume-url-session-id} session- and the continuation-id that is stored in the
and \ex{resume-url-continuation-id} return only the session- or the \var{resume-url}. \ex{resume-url-session-id} and
\ex{resume-url-continuation-id} return only the session- or the
continuation-id, respectively. continuation-id, respectively.
\end{desc} \end{desc}
@ -889,9 +897,9 @@ The \surflets support all input fields defined for HTML~2.0 and allow
\surflet the input field reports as its value, which may be of any \surflet the input field reports as its value, which may be of any
type, not only strings. type, not only strings.
Here is a short overview, how to use input fields. See also the howto Here is a short overview on how to use input fields. See also the
for more informations. First, you create the \ex{input-field} that howto for more informations. First, you create the \ex{input-field}
represents the input field you want to use. Then you put this that represents the input field you want to use. Then you put this
\ex{input-field} into the SXML of the web page at the place the \ex{input-field} into the SXML of the web page at the place the
input field shall appear. After \ex{send-html/suspend} has returned input field shall appear. After \ex{send-html/suspend} has returned
with the next \ex{surflet-request}, you call \ex{get-bindings} with with the next \ex{surflet-request}, you call \ex{get-bindings} with
@ -950,13 +958,13 @@ The \exi{surflets/bindings} structures exports the necessary functions
be translated to a string before use. \ex{extract-bindings} returns be translated to a string before use. \ex{extract-bindings} returns
a list of all values from \var{bindings} whose key is \var{key}. a list of all values from \var{bindings} whose key is \var{key}.
\ex{extract-single-binding} returns the value from the binding whose \ex{extract-single-binding} returns the value from the binding whose
key is \var{key} and raises an error if there more than one such key is \var{key} and raises an error if there is more than one such
binding. The two procedures are the same as in PLT's webserver. binding. The two procedures are the same as in PLT's webserver.
\end{desc} \end{desc}
\ex{get-bindings} must acces the "Content-length" header field to \ex{get-bindings} must acces the "Content-length" header field to
handle \ex{POST} request. \ex{surflets/bindings} therefore also handle \ex{POST} requests. \ex{surflets/bindings} also exports the
exports the procedure that does that job: procedure that does that job:
\defun{get-content-length}{headers}{number} \defun{get-content-length}{headers}{number}
\begin{desc} \begin{desc}

223
doc/latex/surflethowto.tex
View File

@ -33,18 +33,18 @@ description.
%\marginpar{\surflets are pieces of code for web site scripting.} %\marginpar{\surflets are pieces of code for web site scripting.}
For those who don't know it already, \surflets are pieces of code that For those who don't know it already, \surflets are pieces of code that
can be executed interactively through a website. There is a \surflet can be executed interactively through a website. There is a \surflet
handler who administrates their execution and suspension and as part handler who administrates their execution and suspension. The
of the SUnet webserver. \surflets ease the implementation of web \surflet handler is part of the SUnet webserver. \surflets ease the
applications in two ways, compared to other server-side scripting implementation of web applications in two ways, compared to other
tools like Java\texttrademark Servlets or Microsoft\textregistered server-side scripting tools like Java\texttrademark Servlets or
Active Server Pages or PHP: Microsoft\textregistered Active Server Pages or PHP:
\begin{enumerate} \begin{enumerate}
\item \surflets have an automatic program flow control like any \item \surflets have an automatic program flow control like any
other usual program, \ie the web designer doesn't have to care about other usual program (but unlike usual web programs), \ie the web
session management at all. The sequence of the web pages result from designer doesn't have to care about session management at all. The
their appearance in the program like the print statements in any other sequence of the web pages result from their appearance in the program
usual program. like the print statements in any other usual program.
\item \surflets come along with a library for robust user \item \surflets come along with a library for robust user
interaction. \surflets represent interaction elements of the web page interaction. \surflets represent interaction elements of the web page
@ -125,7 +125,7 @@ Going to run SUrflet server with:
htdocs-dir: /home/andreas/bin/lib/scsh/0.6/sunet-2.1/web-server/root/htdocs htdocs-dir: /home/andreas/bin/lib/scsh/0.6/sunet-2.1/web-server/root/htdocs
surflet-dir: /home/andreas/bin/lib/scsh/0.6/sunet-2.1/web-server/root/surflets surflet-dir: /home/andreas/bin/lib/scsh/0.6/sunet-2.1/web-server/root/surflets
images-dir: /home/andreas/bin/lib/scsh/0.6/sunet-2.1/web-server/root/img images-dir: /home/andreas/bin/lib/scsh/0.6/sunet-2.1/web-server/root/img
port: 8008 port: 8080
log-file-name: /tmp/httpd.log log-file-name: /tmp/httpd.log
a maximum of 5 simultaneous requests, syslogging activated, a maximum of 5 simultaneous requests, syslogging activated,
and home-dir-handler (public_html) activated. and home-dir-handler (public_html) activated.
@ -134,7 +134,7 @@ Going to run SUrflet server with:
\end{alltt} \end{alltt}
This means the server is up and running. Try to connect to This means the server is up and running. Try to connect to
\url{http://localhost:8008} with your browser and you will see the \url{http://localhost:8080} with your browser and you will see the
welcome page of the SUnet server. There's a link to the welcome page of the SUnet server. There's a link to the
\surflets homepage. You can also already try out some of the \surflets homepage. You can also already try out some of the
\surflets that come with the distribution. \surflets that come with the distribution.
@ -144,8 +144,8 @@ the first \surflet. This is because the server has to load the
\surflet libraries. The server handles further requests to \surflets \surflet libraries. The server handles further requests to \surflets
faster. faster.
If the port the \surflet server tries to use is occupied use, you will If the port the \surflet server tries to use is occupied, you will see
see an error message similar to this one: an error message similar to this one:
\begin{alltt} \begin{alltt}
Error: 98 Error: 98
@ -153,7 +153,7 @@ Error: 98
#{Procedure 11701 (\%bind in scsh-level-0)} #{Procedure 11701 (\%bind in scsh-level-0)}
4 4
2 2
(0 . 8008) (0 . 8080)
\end{alltt} \end{alltt}
In this case, pass another port number to the script, \eg 8000: In this case, pass another port number to the script, \eg 8000:
@ -244,7 +244,7 @@ use to send web pages to the browser. The other two functions are
\name{send-html} and \name{send-html/suspend}. \name{send-html} and \name{send-html/suspend}.
\name{send-html/finish} -- as the name already suggests -- sends a \name{send-html/finish} -- as the name already suggests -- sends a
HTML page to the browser and finishes the \surflet. \name{send-html} HTML page to the browser and finishes the \surflet. \name{send-html}
just sends the HTML page and does not return and just sends the HTML page and does not return.
\name{send-html/suspend} sends the HTML page and suspends the \name{send-html/suspend} sends the HTML page and suspends the
\surflet, \ie it waits until the user continues with the \surflet, \surflet, \ie it waits until the user continues with the \surflet,
\eg by submitting a webform. We will discuss \name{send-html} and \eg by submitting a webform. We will discuss \name{send-html} and
@ -255,38 +255,35 @@ In a \surflet, HTML pages are represented as lists, or, to be more
precise, as SXML (S-expression based XML).\label{sec:SXML} The first precise, as SXML (S-expression based XML).\label{sec:SXML} The first
element of a SXML list is a symbol stating the HTML tag. The other element of a SXML list is a symbol stating the HTML tag. The other
elements of a SXML list are the contents that are enclosed by this elements of a SXML list are the contents that are enclosed by this
HTML tag. The contents can be other SXML list, too. Here are some HTML tag. The contents can be other SXML lists, too. Here are some
examples of SXML lists and how they translate to HTML: examples of SXML lists and how they translate to HTML:
\newcommand{\htmltag}[1]{$\mathtt{<}$#1$\mathtt{>}$} %\newcommand{\htmltag}[1]{$\mathtt{<}$#1$\mathtt{>}$}
\begin{tabbing} \begin{tabular}{ll}
HTML: \medskip\=\kill SXML: & \verb|'(p "A paragraph.")}| \\
SXML: \> \texttt{'(p "A paragraph.")} \\ HTML: & \verb|<p>A paragraph.\htmltag{/p}}|\\
HTML: \> \texttt{\htmltag{p}A paragraph.\htmltag{/p}}\\
\\ \\
SXML: \> \texttt{'(p "A paragraph." (br) "With break line.")} \\ SXML: & \verb|'(p "A paragraph." (br) "With break line.")}| \\
HTML: \> \texttt{\htmltag{p}A paragraph.\htmltag{br}With break line.\htmltag{/p}}\\ HTML: & \verb|<p>A paragraph.<br>With break line.</p>}|\\
\\ \\
SXML: \> \texttt{'(p "Nested" (p "paragraphs"))}\\ SXML: & \verb|'(p "Nested" (p "paragraphs"))}|\\
HTML: \> \texttt{\htmltag{p}Nested\htmltag{p}paragraphs\htmltag{/p}\htmltag{/p}}\\ HTML: & \verb|<p>Nested<p>paragraphs</p></p>}|\\
\end{tabbing} \end{tabular}
Attributes are stated by a special list whose first element is the Attributes are stated by a special list whose first element is the
at-symbol. The attribute list must be the second element in the list: at-symbol. The attribute list must be the second element in the list:
\begin{tabbing} \begin{tabular}{ll}
HTML: \medskip\=\kill SXML: & \verb|'(a (@ (href "attr.html")) "Attributed HTML tags.")|\\
SXML: \> \texttt{'(a (@ (href "attr.html")) "Attributed HTML tags.")} \\ HTML: & \verb|<a href="attr.html">Attributed HTML tags.</a>|\\
HTML: \> \texttt{\htmltag{a href="attr.html"}Attributed HTML tags.\htmltag{/a}}\\
\\ \\
SXML: \> \texttt{'(a (@ (href "attr2.html") (target "\_blank")) "2 SXML: & \verb|'(a (@ (href "attr2.html") (target "\_blank")) "2
attributes.")} \\ attributes.")}| \\
HTML: \> \texttt{\htmltag{a href="attr2.html" target="\_blank"}2 HTML: & \verb|<a href="attr2.html" target="\_blank">2 attributes.</a>}|
attributes.\htmltag{/a}} \end{tabular}
\end{tabbing}
As you see from the \surflet example, \name{send-html/finish} expects As you see from the \surflet example, \name{send-html/finish} expects
as an argument SXML. In the example, the SXML translates to the SXML as an argument. In the example, the SXML translates to the
following HTML code: following HTML code:
\begin{alltt} \begin{alltt}
<html><body><h1>Hello, world!</h1> <html><body><h1>Hello, world!</h1>
@ -332,7 +329,7 @@ a regular quote (\typew{'}) as in the previous example.
Instead of passing a ``static'' list, \ie a list whose contents are Instead of passing a ``static'' list, \ie a list whose contents are
given before execution, this \surflet uses the quasiquote and unquote given before execution, this \surflet uses the quasiquote and unquote
feature of Scheme to create a ``dynamic'' list, \ie list whose feature of Scheme to create a ``dynamic'' list, \ie a list whose
contents are given only during execution. A ``dynamic'' list is contents are given only during execution. A ``dynamic'' list is
introduced by a backquote (\typew{`}) and its dynamic contents are introduced by a backquote (\typew{`}) and its dynamic contents are
noted by commata (\typew{,}). Thus, if the \surflet is executed while noted by commata (\typew{,}). Thus, if the \surflet is executed while
@ -354,13 +351,13 @@ want; the quasiquote notation is just a convenient way to do it.
\subsubsection{Several web pages in a row} \subsubsection{Several web pages in a row}
The previous example \surflets only showed one page and finished The previous example \surflets only showed one page and finished
afterwards. Here, we want to present to web pages in a row. We use afterwards. Here, we want to present two web pages in a row. We use
the previously mentioned function \name{send-html/suspend}, which the previously mentioned function \name{send-html/suspend}, which
suspends after it has send the page and continues when the user suspends after it has sent the page and continues when the user
clicked for the next page. In contrast to \name{send-html/finish}, clicked for the next page. In contrast to \name{send-html/finish},
that expected SXML, \name{send-html/suspend} expects a function that that expected SXML, \name{send-html/suspend} expects a function that
takes an argument and returns SXML. The parameter the function gets takes an argument and returns SXML. The parameter the function gets
(here: \name{k-url} is the URL that points to the next (here: \name{k-url}) is the URL that points to the next
page:\footnote{In the API this URL is called the \emph{continuation page:\footnote{In the API this URL is called the \emph{continuation
URL}.} URL}.}
@ -384,7 +381,7 @@ This \surflet can be found in \name{howto/hello-twice.scm}. This
example first displays a web page with the message ``Hello, world!'' example first displays a web page with the message ``Hello, world!''
and a link to the next page labeled with ``Next page --$>$''. When the and a link to the next page labeled with ``Next page --$>$''. When the
user clicks on the provided link, \name{send-html/suspend} returns and user clicks on the provided link, \name{send-html/suspend} returns and
the the next statement after the call to \name{send-html/suspend} is the next statement after the call to \name{send-html/suspend} is
executed. Here it is \name{send-html/finish} which shows a web page executed. Here it is \name{send-html/finish} which shows a web page
with the message ``Hello, again!''. with the message ``Hello, again!''.
@ -402,16 +399,16 @@ effects, \eg if you change a variable via \name{set!}. These
variables keep their modified values, allowing communication between variables keep their modified values, allowing communication between
sessions of the same \surflet.\footnote{If you want to change a sessions of the same \surflet.\footnote{If you want to change a
variable via side effects but you don't want to interfere with other variable via side effects but you don't want to interfere with other
session, you can use \name{set-session-data!} and sessions, you can use \name{set-session-data!} and
\name{get-session-data}. See the API documentation in section \name{get-session-data}. See the API documentation in section
\ref{sec:surflet-api}for further information.} \ref{sec:surflet-api} for further information.}
\subsubsection{Begin and end of sessions} \subsubsection{Begin and end of sessions}
So far I don't have mentioned too much details about sessions. The So far I don't have mentioned too much details about sessions. The
reason is, as mentioned before, that the \surflet handler takes of the reason is, as mentioned before, that the \surflet handler takes care
session automatically as described in the previous paragraph. of the session automatically as described in the previous paragraph.
%, \ie it starts the session automatically when an %, \ie it starts the session automatically when an
%instance of your \surflet starts and takes care of the saving and %instance of your \surflet starts and takes care of the saving and
%restoring of all variable values during suspensions of your \surflet %restoring of all variable values during suspensions of your \surflet
@ -512,8 +509,8 @@ objects. Thus, user interaction elements are first class values in
\surflet, unlike in many other web scripting languages, \eg Java \surflet, unlike in many other web scripting languages, \eg Java
surflets, PHP or Microsoft Active Server Pages, \ie you have a surflets, PHP or Microsoft Active Server Pages, \ie you have a
representation of a user interaction element in your program that you representation of a user interaction element in your program that you
can pass to functions, receive them as return values, etc. You'll see can pass to functions, receive them as return values, etc. You'll
soon the advantages of this approach. soon see the advantages of this approach.
\begin{alltt} \begin{alltt}
(req (send-html/suspend (req (send-html/suspend
@ -559,7 +556,7 @@ add the symbol \name{'POST} after the URL:
\end{alltt} \end{alltt}
The web page \name{send-html/suspend} sends to the browser looks like The web page \name{send-html/suspend} sends to the browser looks like
in figure [missing] in figure [missing].
%\ref{fig:user1-1}. %\ref{fig:user1-1}.
After the user has entered his data into After the user has entered his data into
the web form, \name{send-html/suspend} returns with the request object the web form, \name{send-html/suspend} returns with the request object
@ -593,7 +590,7 @@ know what the user has entered into the \name{text-input-field}.
After we have extracted what the user has entered into the text field, After we have extracted what the user has entered into the text field,
we can show the final page of our \surflet and echo her input. we can show the final page of our \surflet and echo her input.
The scheme for user interaction is thus about the following: Thus, the scheme for user interaction is about the following:
\begin{itemize} \begin{itemize}
\item Create the user interaction elements, \name{input-field}s, you \item Create the user interaction elements, \name{input-field}s, you
@ -615,7 +612,7 @@ found in the API in section \ref{sec:surflet-api}.
As the user interaction elements are first class values in a \surflet, As the user interaction elements are first class values in a \surflet,
they can return other types than strings. For example the \surflets they can return other types than strings. For example the \surflets
come with a number input field, \ie a input field that accepts only come with a number input field, \ie an input field that accepts only
text that can be interpreted as a number. If the user enters text that can be interpreted as a number. If the user enters
something that is not a number, \name{input-field-value} will return something that is not a number, \name{input-field-value} will return
\sharpf as the value of the number input field. If you'd rather want \sharpf as the value of the number input field. If you'd rather want
@ -675,13 +672,13 @@ Let's go through the important part of this \surflet:
Here we define a select input field (a dropdown list). Instead of Here we define a select input field (a dropdown list). Instead of
only providing a list of values that shall show up in the dropdown only providing a list of values that shall show up in the dropdown
list and later examining which one was select and looking up the price list and later examining which one was selected and looking up the
for the sweet, we bind the values in the list with the price while we price for the sweet, we bind the values in the list with the price
create the select input field. When the select input field is shown while we create the select input field. When the select input field
in the browser, it will show the names of the sweets. When we lookup is shown in the browser, it will show the names of the sweets. When
the user's input, we will get the associated price for the sweet. we lookup the user's input, we will get the associated price for the
Again, this works not only with numbers, but with any arbitrary Scheme sweet. Again, this works not only with numbers, but with any
value (\eg functions or records). arbitrary Scheme value (\eg functions or records).
\subsubsection{Sending error messages} \subsubsection{Sending error messages}
@ -691,7 +688,7 @@ has to deal with unexpected values. Usually, a forged \surflet-URL
will result in an error that is raised in one of the \surflet library will result in an error that is raised in one of the \surflet library
functions. If you don't catch this error, the \surflet handler will functions. If you don't catch this error, the \surflet handler will
catch it for you, send an error message to the user catch it for you, send an error message to the user
\emph{and terminating the current session} as your \surflet obviously \emph{and terminate the current session} as your \surflet obviously
encountered an unexpected error and might be in an invalid state. If encountered an unexpected error and might be in an invalid state. If
you don't want this behavior, you can catch this error (like any other you don't want this behavior, you can catch this error (like any other
error that is raised by \scsh) and send your own error message with error that is raised by \scsh) and send your own error message with
@ -703,8 +700,8 @@ previous subsection (modifications emphasized):
\begin{listing} \begin{listing}
(define-structure surflet surflet-interface (define-structure surflet surflet-interface
(open surflets (open surflets
\codemph{ handle-fatal-error \codemph{ handle-fatal-error}
surflets/error} \codemph{ surflets/error}
scheme-with-scsh) scheme-with-scsh)
(begin (begin
(define (main req) (define (main req)
@ -725,14 +722,14 @@ previous subsection (modifications emphasized):
,select-input-field) ,select-input-field)
,(make-submit-button))))))) ,(make-submit-button)))))))
(bindings (get-bindings req)) (bindings (get-bindings req))
\codemph{ (cost (with-fatal-error-handler \codemph{ (cost (with-fatal-error-handler }
(lambda (condition decline) \codemph{ (lambda (condition decline) }
(send-error (status-code bad-request) \codemph{ (send-error (status-code bad-request)}
req \codemph{ req }
"No such option or internal \codemph{ "No such option or internal }
error. Please try again.")) \codemph{ error. Please try again."))}
(raw-input-field-value select-input-field \codemph{ (raw-input-field-value select-input-field }
bindings))))} \codemph{ bindings)))) }
(send-html/finish (send-html/finish
`(html (head (title "Receipt")) `(html (head (title "Receipt"))
(body (body
@ -756,7 +753,7 @@ Let's examine the important part of this example:
As mentioned in \ref{subsec:input-return}, this \surflet uses As mentioned in \ref{subsec:input-return}, this \surflet uses
\name{raw-input-field-value} instead of \name{input-field-value} \name{raw-input-field-value} instead of \name{input-field-value}
because the former raises an error while the latter returns \sharpf in because the former raises an error while the latter returns \sharpf\ in
case of an error. case of an error.
If a user forges a continuation URL, \name{raw-input-field-value} If a user forges a continuation URL, \name{raw-input-field-value}
@ -768,7 +765,7 @@ by the error handler which was installed by
argument is the status code of the error message. See the argument is the status code of the error message. See the
documentation of the \sunet webserver for different status codes. The documentation of the \sunet webserver for different status codes. The
second argument is the request which was processed while the error second argument is the request which was processed while the error
occured. The last argument is a free message text to explain the occured. The last argument is a free text message to explain the
cause of the error to the user. cause of the error to the user.
While in the original \surflet the user will still see the resulting While in the original \surflet the user will still see the resulting
@ -797,7 +794,7 @@ gives you a short overview how to do this. You will find the details
in the \surflet API. in the \surflet API.
Let's have a look at an \surflet that uses its own input field. The Let's have a look at an \surflet that uses its own input field. The
``input field'', called nibble input field, consists of eight check ``input field'', called nibble input field, consists of four check
boxes which represent bits of a nibble (half a byte). The value of boxes which represent bits of a nibble (half a byte). The value of
the input field is the number that the check boxes represent. \Eg, if the input field is the number that the check boxes represent. \Eg, if
the user checks the last two checkboxes, the value of the nibble input the user checks the last two checkboxes, the value of the nibble input
@ -918,7 +915,7 @@ associated to its name.
The transformer function of our nibble input field goes over each The transformer function of our nibble input field goes over each
check box, looks it up in the bindings and adds its value to a sum, if check box, looks it up in the bindings and adds its value to a sum, if
\name{input-field-value} can find it. If it can't find it, a zero is \name{input-field-value} can find it. If it can't find it, zero is
added instead. The value of our nibble input field is the resulting added instead. The value of our nibble input field is the resulting
sum. sum.
@ -1025,8 +1022,8 @@ link the user has clicked by using \name{case-returned-via}.
\name{case-returned-via} works similar to the regular \name{case} of \name{case-returned-via} works similar to the regular \name{case} of
Scheme. It evaluates the body of the form whose initial list contains Scheme. It evaluates the body of the form whose initial list contains
the address that the user used to leave the website. \Eg, if the user the address that the user used to leave the website. \Eg, if the user
has selected ``German'' as her preferred language and thus clicked on has selected ``German'' as her preferred language and clicked on the
the link we have named \name{german} in our \surflet, link we have named \name{german} in our \surflet,
\name{case-returned-via} will evaluate its second form and the \name{case-returned-via} will evaluate its second form and the
\surflet will display the greeting in German. \surflet will display the greeting in German.
@ -1067,11 +1064,11 @@ We modify the previous code example slightly to this \surflet
(body (body
(h2 "Select your language:") (h2 "Select your language:")
(ul (ul
(li (url ,\codemph{(language k-url (li (url ,\codemph{(language k-url }
"Hello, how are you?")} \codemph{ "Hello, how are you?")}
"English") "English")
(li (url ,\codemph{(language k-url (li (url ,\codemph{(language k-url }
"Hallo, wie geht es Ihnen?")} \codemph{ "Hallo, wie geht es Ihnen?")}
"Deutsch"))))))))) "Deutsch")))))))))
(bindings (get-bindings req))) (bindings (get-bindings req)))
(case-returned-via bindings (case-returned-via bindings
@ -1138,7 +1135,7 @@ callbacks. A callback is a function that is called if the user leaves
the web page via an associated link. This is different from the the web page via an associated link. This is different from the
dispatch method where \name{send-html/suspend} returns. You can dispatch method where \name{send-html/suspend} returns. You can
create a web page that only uses callbacks to lead to successor web create a web page that only uses callbacks to lead to successor web
page and thus you don't have to use \name{send-html/suspend}. pages and you don't have to use \name{send-html/suspend}.
Instead, you can use \name{send-html}. Instead, you can use \name{send-html}.
Although it is possible to use several different callbacks in a single Although it is possible to use several different callbacks in a single
@ -1186,7 +1183,8 @@ callbacked function must accept the request from the browser as the
first argument. Furthermore, you don't have to use first argument. Furthermore, you don't have to use
\name{send-html/suspend}, if a user can only leave your web page via \name{send-html/suspend}, if a user can only leave your web page via
callbacks. However, it can be sensible to combine the dispatch and callbacks. However, it can be sensible to combine the dispatch and
the callback method, so you have to use \name{send-html/suspend}. the callback method, in which case you have to use
\name{send-html/suspend}.
Note that is nonsensical to create a callback on top level, \ie the Note that is nonsensical to create a callback on top level, \ie the
call to \name{make-annotated-callback} must occur every time call to \name{make-annotated-callback} must occur every time
@ -1207,7 +1205,7 @@ you can instruct the callback to call different functions like this:
\begin{alltt} \begin{alltt}
(callback function1 arg1 arg2) (callback function1 arg1 arg2)
\dots \dots \\
(callback function2 arg3 arg4 arg5) (callback function2 arg3 arg4 arg5)
\end{alltt} \end{alltt}
@ -1220,15 +1218,15 @@ callback.
When you write web programs, there are usually two kinds of data that When you write web programs, there are usually two kinds of data that
you use: data that is local to each instance of a \surflet, \eg the you use: data that is local to each instance of a \surflet, \eg the
users login, and data that is global to each instance of a \surflet, user's login, and data that is global to each instance of a \surflet,
\eg a port to a logfile. Changes to local data is only visible to \eg a port to a logfile. Changes to local data is only visible to
each instance of a \surflet, while changes to global data is visible each session of a \surflet, while changes to global data is visible
to every instance of a \surflet. to every session of a \surflet.
The \surflet library does not really distinguish between these two The \surflet library does not really distinguish between these two
types of data, but provides ways to realize both of them in a types of data, but provides ways to realize both of them in a
convenient way that is not (really) different from the way you handle convenient way that is not (really) different from the way you handle
this data types in a regular Scheme program. these data types in a regular Scheme program.
If a data item is globally used in your \surflet, define it global If a data item is globally used in your \surflet, define it global
(on top level) and change its values with \name{set!}. If a data (on top level) and change its values with \name{set!}. If a data
@ -1242,7 +1240,7 @@ is that the \surflets are implemented with continuations.
Continuations cannot reflect changes that are done via \name{set!} (or Continuations cannot reflect changes that are done via \name{set!} (or
side effects in general) and thus such changes are globally visible. side effects in general) and thus such changes are globally visible.
On the other hand continuations represent states of a program and a On the other hand continuations represent states of a program and a
reified continuations reifies also the values of all (local) data. reified continuations reifies also the values of all data.
But what to do if you happen to want to change your \emph{local} But what to do if you happen to want to change your \emph{local}
data's value with \name{set!}? The \surflet library provides a place data's value with \name{set!}? The \surflet library provides a place
@ -1359,50 +1357,45 @@ process and some necessary terms we will use in the following.
The translation process from SXML to HTML takes two steps. In the The translation process from SXML to HTML takes two steps. In the
first step, SXML is translated to an intermediate form. This is done first step, SXML is translated to an intermediate form. This is done
by the \textit{translator}. In the second step, the intermediate form by the \textit{translator}. In the second step, the intermediate form
is translated into an HTML string. This is done by the is printed into an HTML string. This is done by the
\textit{printer}. The intermediate form looks very much like SXML, \textit{printer}. The intermediate form looks very much like SXML,
but contains only atoms or, recursively, list of \textit{atoms}. but contains only \textit{atoms} or, recursively, list of atoms.
Atoms are numbers, characters, strings, \sharpf, and the empty list. Atoms are numbers, characters, strings, \sharpf, and the empty list.
We call the intermediate form an \textit{atom tree} and the list from We call the intermediate form an \textit{atom tree} and the list from
which we've started an \textit{SXML tree}. which we've started an \textit{SXML tree}.
The basic unit in the translation process is a \textit{conversion The basic unit in the translation process is a \textit{conversion
rule}. A conversion rule consists of a trigger and a conversion rule}. A conversion rule consists of a trigger and a conversion
function. The translator calls the conversion function when it sees function. As its first element, the trigger identifies the list for
the trigger at the beginning of a list in the SXML tree, \ie at a which the translator shall call the conversion function. The
node. It calls the conversion function with the all list elements as translator calls the conversion function with all list elements as
parameters and replaces the whole list by the result of the conversion parameters and replaces the whole list by the result of the conversion
function. The result of the conversion function is supposed to be an function. The result of the conversion function is supposed to be an
atom tree. atom tree.
The translator gets the SXML tree and a list of conversion rules as The translator takes the SXML tree and a list of conversion rules as
arguments. It then traverses the SXML tree depth first and calls the arguments. It then traverses the SXML tree depth first and calls the
conversion functions according to the triggers it encounters, conversion functions according to the triggers it encounters,
replacing the nodes in the SXML tree with the result of the conversion replacing the nodes in the SXML tree with the return values of each
functions it called for each node. The result of this translation conversion function called. The result of this translation step will
step will be an atom tree, which the printer will print to a port. be an atom tree, which the printer will print into a string or port.
There are exceptions to this basic rules. First, the translator might The translator calls the conversion function in two different modes,
not traverse the whole SXML tree. If the translator traverses the depending on the conversion rule. The regular mode is the
whole tree, every argument to a conversion function is first \textit{preprocess} mode: the translator translates every argument of
translated before it is passed to the conversion function. This is the conversion function before calling it. The other mode is the
the regular case and we say the conversion function gets its arguments \textit{unprocessed} mode: the translator calls the conversion
\textit{preprocessed}. However, the conversion rule can instruct the function directly without preprocessing the arguments. This is, the
translator not to preprocess the conversion function's arguments and translator stops traversing the SXML tree at nodes that trigger a
pass the arguments as they are in the SXML tree, \ie conversion rule in unprocessed mode.
\textit{unprocessed}. In that case, the translator will stop
traversing the SXML tree at that node and replacing the whole node by
the result of the conversion function called for this node.
Second, there are two default triggers which you can't use in your There are two default triggers which you can't use in your translation
translation rules: \typew{*default*} and \typew{*text*}. The rules: \typew{*default*} and \typew{*text*}. \typew{*default*} as the
conversion rule that uses \typew{*default*} as its trigger is the trigger marks the default conversion rule which the translator uses if
default conversion rule which the translator uses if no other no other conversion rule triggers. \typew{*text*} marks the text
conversion rule triggers for a node in the SXML tree. The conversion conversion rule and triggers, if the node in the SXML tree is a
rule that uses \typew{*text*} as its trigger is the text conversion string. In the standard conversion rule set the text conversion rule
rule and triggers, if the node in the SXML tree is a string. In the performs HTML escaping, \eg for the ampersand (\&).
standard conversion rule set the text conversion rule performs HTML
escaping, \eg for the ampersand (\&).
\subsubsection{Outlook} \subsubsection{Outlook}

2
doc/latex/surflets.tex
View File

@ -6,7 +6,7 @@ The \surflet server enables you to write server side scripted web
programs in Scheme. programs in Scheme.
%Currently, there is only the howto available. %Currently, there is only the howto available.
%The complete API is supposed to come soon. %The complete API is supposed to come soon.
There are lot of example files in There are lots of example files in
\typew{scheme/httpd/surflet/webserver/root/surflets} from which you \typew{scheme/httpd/surflet/webserver/root/surflets} from which you
can copy freely. can copy freely.