The first xml-element-constructor variant uses a literal QName, and looks like standard non-empty XML element, where the starting QName and the ending QName must match exactly:

#<a href="next.html">Next</a>

As a convenience, you can leave out the ending tag(s):

<para>This is a paragraph in <emphasis>DocBook</> syntax.</>

You can use an expression to compute the element tag at runtime - in that case you must leave out the ending tag:

#<p>This is <(if be-bold 'strong 'em)>important</>!</p>

You can use arbitrary expression inside curly braces, as long as it evaluates to a symbol. You can leave out the curly braces if the expression is a simple parenthesised compound expression. The previous example is equivalent to:

#<p>This is <{(if be-bold 'strong 'em)}>important</>!</p>

The third xml-element-constructor variant above is an XML “empty element”; it is equivalent to the second variant when there are no xml-element-datum items.

(Note that every well-formed XML element, as defined in the XML specifications, is a valid xml-element-constructor, but not vice versa.)

The “contents” (children) of an element are a sequence of character (text) data, and nested nodes. The characters &, <, and > are special, and need to be escaped.

Here is an example shows both hex and decimal character references:

#<p>A&#66;C&#x44;E</p>  ⇒  <p>ABCDE</p>

Currently, the only supported values for xml-entity-name are the builtin XML names lt, gt, amp, quot, and apos, which stand for the characters <, >, &, ", and ', respectively. The following two expressions are equivalent:

#<p>&lt; &gt; &amp; &quot; &apos;</p>
#<p>&{"< > & \" '"}</p>

If the xml-name-form is either xmlns or a compound named with the prefix xmlns, then technically we have a namespace declaration, rather than an attribute.

The names of elements and attributes are qualified names (QNames), which are represented using compound symbols (see the section called “Namespaces and compound symbols”). The lexical syntax for a QName is either a simple identifier, or a (prefix,local-name) pair:

An xml-prefix is an alias for a namespace-uri, and the mapping between them is defined by a namespace-declaration. You can either use a define-namespace form, or you can use a namespace declaration attribute:

The former declares xml-prefix as a namespace alias for the namespace-uri specified by xml-attribute-value (which must be a compile-time constant). The second declares that xml-attribute-value is the default namespace for simple (unprefixed) element tags. (A default namespace declaration is ignored for attribute names.)

(let ((qn (element-name #<gnu:b xmlns:gnu="http://gnu.org/"/>)))
  (list (symbol-local-name qn)
        (symbol-prefix qn)
        (symbol-namespace-uri qn)))
⇒ ("b" "gnu" "http://gnu.org/")

An xml-PI-constructor can be used to create an XML processing instruction, which can be used to pass instructions or annotations to an XML processor (or tool). (Alternatively, you can use the processing-instruction type constructor.)

For example, the DocBook XSLT stylesheets can use the dbhtml instructions to specify that a specific chapter should be written to a named HTML file:

#<chapter><?dbhtml filename="intro.html" ?>
<title>Introduction</title>
...
</chapter>

You can cause XML comments to be emitted in the XML output document. Such comments can be useful for humans reading the XML document, but are usually ignored by programs. (Alternatively, you can use the comment type constructor.)

A CDATA section can be used to avoid excessive use of xml-entity-ref such as & in element content.

The following are equivalent:

#<p>Specal characters <![CDATA[< > & ' "]]> here.</p>
#<p>Specal characters &lt; &gt; &amp; &quot; &apos; here.</p>

Kawa remembers that you used a CDATA section in the xml-element-constructor and will write it out using a CDATA constructor.

The easiest way to run a Kawa web server is to use the web server built in to JDK 6 or later.

kawa --http-auto-handler context-path appdir --http-start port

This starts a web server that listens on the given port, using the files in directory appdir to handle requests that start with the given context-path. The context-path must start with a "/" (one is added if needed), and it is recommended that it also end with a "/" (otherwise you might get some surprising behavior).

You can specify multiple --http-auto-handler options.

For example use the files in the current directory to handle all requests on the standard port 80 do:

kawa --http-auto-handler / . --http-start 80

There are some examples in the testsuite/webtest directory the Kawa source distribution. You can start the server thus:

bin/kawa --http-auto-handler / testsuite/webtest/ --http-start 8888

and then for example browse to http://localhost:8888/adder.scm.

For lots of information about the HTTP request, browse to http://localhost:8888/info/anything.

You can also can use a “servlet container” such as Tomcat or Glassfish with self-configuring script. See the section called “Installing web page scripts as Servlets” for information on how to install these servers, and the concept of web applications. Once you have these server installed, you create a web application with the following in the appdir/WEB-INF/web.xml configuration file:

<web-app>
  <display-name>Kawa auto-servlet</display-name>
  <servlet>
    <servlet-name>KawaPageServlet</servlet-name>
    <servlet-class>gnu.kawa.servlet.KawaPageServlet</servlet-class>
  </servlet>
  <servlet-mapping>
    <servlet-name>KawaPageServlet</servlet-name>
    <url-pattern>/*</url-pattern>
  </servlet-mapping>
</web-app>

This creates a web application where all URLs are handled by the gnu.kawa.servlet.KawaPageServlet servlet class, which is included in the Kawa jar file. The KawaPageServlet class handles the searching and compiling described in this page.

When Kawa receives a request for:

http://host:port/appname/a/b/anything

it will look for a file:

appdir/a/b/anything

If such a file exists, the script will be executed, as described below. If not, it will look for a file name +default+ in the same directory. If that desn't exist either, it will look for +default+ in the parent directory, then the grand-parent directory, and so on until it gets to the appname web application root directory. So the default script is this: appdir/+default.

If that doesn't exist then Kawa returns a 404 "page not found" error.

Once Kawa has found a script file corresponding to a request URL, it needs to determine if this is a data file or a web page script, and in the latter case, what language it is written in.

Kawa recognizes the following "magic strings" in the first line of a script:

Kawa also recognizes Emacs-style "mode specifiers":

Also, it also recognizes comments in the first two columns of the line:

If Kawa doesn't recognize the language of a script (and it isn't named +default+) then it assumes the file is a data file. It asks the servlet engine to figure out the content type (using the getMimeType method of ServletContext), and just copies the file into the response.

Kawa automatically compiles a script into a class. The class is internal to the server, and is not written out to disk. (There is an unsupported option to write the compiled file to a class file, but there is no support to use previously-compiled classes.) The server then creates a module instance to handle the actual request, and runs the body (the run method) of the script class. On subsequence requests for the same script, the same class and instance are reused; only the run is re-executed.

If the script is changed, then it is re-compiled and a new module instance created. This makes it very easy to develop and modify a script. (Kawa for performance reasons doesn't check more than once a second whether a script has been modified.)

A web application is a group of data, servlets, and configuration files to handle a related set of URLs. The servlet specification specifies the directory structure of a web application.

Assume the web application is called myapp, and lives in a directory with the same name. The application normally handles requests for URLs that start with http://example.com/myapp. Most files in the application directory are used to handle requests with corresponding URL. For example, a file myapp/list/help.html would be the response to the request http://example.com/myapp/list/help.html.

The directory WEB-INF is special. It contains configuration files, library code, and other server data.

So to create the myapp application, start with:

mkdir myapp
cd myapp
mkdir WEB-INF WEB-INF/lib WEB-INF/classes

Copy the Kawa jar from the lib direcory. (You can also use a “hard” link, but symbolic links may not work, for security systems.)

cp kawa-home/kawa-1.14.1.jar WEB-INF/lib/kawa.jar

You should also create the file WEB-INF/web.xml. For now, this is is just a place-holder:

<web-app>
  <display-name>My Application</display-name>
</web-app>

Assume for simplicity that the source files are in the WEB-INF/classes directory, and make that the current directory:

cd .../myapp/WEB-INF/classes

Depending on the source language, you compile your script sing the --servlet switch:

kawa --servlet -C hello.scm

or:

kawa --servlet --krl -C hello.krl

or:

kawa --servlet --xquery -C hello.xql

This lets the web-application find the compiled servlets. Finally, you just need to add the new servlet to the WEB-INF/web.xml file:

<web-app>
  <display-name>My Application</display-name>

  <servlet>
    <servlet-name>MyHello</servlet-name>
    <servlet-class>hello</servlet-class>
  </servlet>

  <servlet-mapping>
    <servlet-name>MyHello</servlet-name>
    <url-pattern>/hello</url-pattern>
  </servlet-mapping>
</web-app>

The <servlet> clause says that the servlet named MyHello is implemented by the Java class hello. The <servlet-mapping> clause says that a request URL /hello should be handled by the servlet named MyHello. The URL is relative to the application context path, so the actual URL would be http://example.com/myapp/hello.

Apache's Tomcat is an open-source implementation of the servlet specifications. After you download it, uncompress it in some convenient location, which is commonly referred to as $CATALINA_HOME.

To install your web application, copy/move its directory to be in the $CATALINA_HOME/webapps directory. Thus for the example above you would have a $CATALINA_HOME/webapps/myapp directory.

To start or stop Tomcat use the scripts in $CATALINA_HOME/bin. For example to start Tomcat on a GNU/Linux system run $CATALINA_HOME/bin/startup.sh. This will start a web server that listens on the default port of 8080, so you can browse the above example at http://localhost:8080/myapp/hello.

If you're running Fedora GNU/Linux, you can use the tomcat6 package:

# yum install tomcat6
# export CATALINA_HOME=/usr/share/tomcat6

You can the manage Tomcat like other system services. You can install webapps under $CATALINA_HOME/webapps.

Glassfish from Oracle/Sun is a open-source “application server” that implements Java EE 6, including the 3.0 servlet specification. After you download it, uncompress it in some convenient location. This location is called as-install-parent in the Quick Start Guide. The commands you will use is most in as-install/bin, where as-install is as-install/glassfish.

To start the server, do:

as-install/bin/startserv

or under under Windows:

as-install\bin\startserv.bat

The default post to listen to is 8080; you can the port (and lots of other properties) using the adminstration console at port 4848.

A web application does not need to be any particular location, instead you just install it with this command:

as-install/bin/adadmin deploy appdir

where appdir is the application directory - myapp in the example. (Use asadmin.bat under Windows.)

The following functions only work within a servlet container. To use these functions, first do:

(require 'servlets)

You can conditionalize your code to check for servlets, like this:

(cond-expand
 (in-servlet
   (require 'servlets)
   (format "[servlet-context: ~s]" (current-servlet-context)))
 (else
   "[Not in a servlet]"))

Request parameters are used for data returned from forms, and for other uses. They may be encoded in the query string or in the request body.

The request headers are a set of (keyword, string)-pairs transmitted as part of the HTTP request, before the request body.

Information about the interface and port on which the request was received.

Information about the interface and port of the remote client that invoked the request.

Bundled with Kawa is a fairly complete implementation of W3C's new XML Query language. If you start Kawa with the --xquery it selects the "XQuery" source language; this also prints output using XML syntax. See the Qexo (Kawa-XQuery) home page for examples and more information.

There is an experimental implementation of the XSLT (XML Stylesheet Language Transformations) language. Selecting --xslt at the Kawa command line will parse a source file according to the syntax on an XSLT stylesheet. See the Kawa-XSLT page for more information.

KRL (the "Kawa Report Language") is powerful Kawa dialect for embedding Scheme code in text files such as HTML or XML templates. You select the KRL language by specifying --krl on the Kawa command line.

KRL is based on on BRL, Bruce Lewis's "Beautiful Report Language", and uses some of BRL's code, but there are some experimental differences, and the implementation core is different. You can run KRL in BRL-compatility-mode by specifying --brl instead of --krl.

This section summarizes the known differences between KRL and BRL. Unless otherwise specified, KRL in BRL-compatibility mode will act as BRL.