\documentclass[a4paper]{article}

\usepackage[latin1]{inputenc}

\usepackage{a4wide}

\begin{document}

\thispagestyle{empty}
\title{lisp-cgi-utils, examples documentation}
\author{Alexander Schreiber $<als@thangorodrim.de>$}
\maketitle

Short documentation for the example programs for the
\texttt{lisp-cgi-utils} package.
\thispagestyle{empty}
\pagebreak

\section{Supported Lisp implementations}

For testing and demonstration purpose, the full package contains
examples for all currently explizitly supported Lisp
implementations. These are:
\begin{itemize}
\item CLisp,
\item CMU Common Lisp (CMUCL),
\item Steel Bank Common Lisp (SBCL).
\end{itemize}

Since \texttt{lisp-cgi-utils} is written in straight Common Lisp (with
currently only one implementation specific function - the one for
reading environment variables), no special adaptions for each
implementation are needed and the test programs for all
implementations share the same Lisp code. The only difference is the
way the Lisp environments are invoked for running as CGI programs.

Therefore, the example CGIs always consist of two parts: a simple
shell script for invoking the specific Lisp environment with specified
Lisp source file to run as CGI process and the Lisp source file
implementing the program.

\section{The examples}

\subsection{simple web page example - \texttt{simple.lisp}}

As the name implies, this is a very simple example. It loads the two
Lisp files (and packages) which make up the \texttt{lisp-cgi-utils}
library, sends the standard HTML headers to the client and generates a
very simple web page with a title, two headlines, a short list and two
very short paragraphs of text. It is both an very basic introduction
examples and a simple test to check if \texttt{lisp-cgi-utils}
works at all.

\subsection{HTML forms example - \texttt{forms.lisp}}

As stated in the general advertisement for the \texttt{lisp-cgi-utils}
package, it has special support for HTML forms. The forms example is
here to demonstrate some of this. It contains a simple HTML forms
input line as well as a multiple selector box. Forms that post their
results back to the CGI sending them are made very simple with the
\texttt{html:form-self-post} function which supports exactly this kind
of self-referential forms.

The form also lists all environment variables of the CGIs execution
environment. 

\subsection{HTTP cookie example - \texttt{cookies.lisp}}

Since \texttt{lisp-cgi-utils} also supports HTTP cookies for easily
keeping state across several HTTP request, this example shows the
cookie support. It sends a set of cookies to the client and lists all
cookies it received from the client, showing how to use the functions
for cookie-support.

\section{Lisp running as CGI}

\subsection{General considerations}

Using the CGI interface for web based Lisp applications is rather
unusual as most applications seem to use the application server
concept (either with a Lisp running behind a webserver or with the
Lisp handling HTTP directly).

Since we'll be using Lisp environments for scripting and most of them
aren't really with scripting as a primary use, we need to employ some
tricks.


\subsection{Scripting with CMUCL}

For scripting wih CMUCL, we use a shell script that invokes CMUCL with
the specified main Lisp file:

\begin{figure}[htbp]
  \centering
\begin{verbatim}
#!/bin/sh
#
# Script for CMUCL

exec lisp -batch -quiet -load simple.lisp
\end{verbatim}
  \caption{Shell script wrapper for CMUCL}
  \label{fig:cmucl-script}
\end{figure}

Here the \texttt{-quiet} and \texttt{-batch} options to CMUCL suppress
further output from the Lisp environment that would normaly occur and
disrupt the CGI output.

\subsection{Scripting with SBCL}

Steel Bank Common Lisp is handled similiar to CMUCL - which is not
much of a surprise, considering that SBCL is an offspring from CMUCL.

\begin{figure}[htbp]
  \centering
\begin{verbatim}
#!/bin/sh
#

export HOME=/

exec sbcl --noinform  --end-runtime-options --noprogrammer --load simple.lisp 
\end{verbatim}
  \caption{Shell script wrapper for SBCL}
  \label{fig:sbcl-script}
\end{figure}

Again, there are options to shut up the normal flood of informational
messages the Lisp environment would spew to the standard output. With
\texttt{--noinform} and \texttt{--noprogrammer} it keeps acceptably
quiet (although it still makes noise on standard error).

If you are familiar with the workings of SBCL, you might at that point
wonder what the hell I'm up to. Everybody else running the SBCL CGI
examples might wonder why the SBCL example is slow as molasses
compared to the other two. 

To calm the first ones, I know that this is
not the way one uses SBCL - but building an image with the full
compiled code would be too much for just a short test and
demonstration. 

The enlighten the others: SBCL has no real interpreter,
it always compiles. So it starts up, loads the \texttt{lisp-cgi-utils}
library, compiles it, loads the example code, compiles it and finally
runs the CGI. For every request. Of course that's slow. It's also not
the way one does things normally with SBCL. Normally, one would build
an image for deployment and run from this image. Consult the SBCL
documentation for more.

\subsection{Scripting with Clisp}

Using Clisp for scripting is very simple. Just put it at the first
line of the script, using the UNIX \texttt{\#!}-Magic, write Lisp code
below and you are done.

\begin{figure}[htbp]
  \centering
\begin{verbatim}
#!/usr/bin/clisp -Efile ISO-8859-1 -Eterminal ISO-8859-1 -Emisc ISO-8859-1
;;;;
;;;; 

(load "simple.lisp")
\end{verbatim}
  \caption{Scripting with CLisp}
  \label{fig:clisp-script}
\end{figure}

That's it, nothing more. You can even drop off all the options I used
in this example since they are only there to force CLisp to run in
the ISO Latin-1 character set instead of the default (which {\em
  might}, but is not guaranteed to, be UTF-8).

\section{Closing remarks}

The examples documented here only show the general usage of the
\texttt{lisp-cgi-utils} library. More documentation is available
in the \texttt{doc} directory of the distribution and as docstrings
attached to the symbols of the library.

\end{document}
