START-INFO-DIR-ENTRY
* kawa: (kawa).         Kawa, the Java-based Scheme system
END-INFO-DIR-ENTRY



The Kawa Scheme system, by Per Bothner
**************************************

Kawa is a Scheme environment, written in Java, and that compiles Scheme
code into Java byte-codes.

This documents version 1.6.66, updated 22 March 2000.

See the summary of recent changes
(http://www.gnu.org/software/kawa/NEWS).

The author of Kawa is Per Bothner <per@bothner.com>.  It is a re-write
of Kawa 0.2, which was written by R. Alexander Milowski
<alex@copsol.com>.

The Kawa home page (which is currently just an on-line version of this
document) is `http://www.gnu.org/software/kawa/'.  The old Kawa home
page (http://www.cygnus.com/~bothner/kawa.html) should also work.

JEmacs is included in the Kawa distribution.  It is a project to
re-implement Emacs, allowing a mix of Java. Scheme, and Emacs Lisp.  It
has its own home-page (http://jemacs.sourceforge.net/).

The Scheme repository
(http://www.cs.indiana.edu/scheme-repository/home.html) has various
useful information on Scheme.  but it is not very actively updated.  A
new repository has been started at www.schemers.org
(http://www.schemers.org/).  It includes pointer to an online copy of
R5RS (http://www.schemers.org/Documents/Standards/).

A nice quick introduction to Scheme can be found in Greg Badros's
lecture notes
(http://www.cs.washington.edu/education/courses/341/99su/lectures/scheme/).
A more in-depth tutorial which also discusses Scheme implementation is
Paul Wilson's "An Introduction to Scheme and its Implementation"
(http://www.cs.utexas.edu/users/wilson/schintro/schintro_toc.html).

Javadoc generated documentation of the Kawa classes
(http://sourceware.cygnus.com/kawa/api/) is also available.

For copyright information on the software and documentation, see *Note
License::.

This package has nothing to do with the Kawa commercial Java IDE
(http://www.tek-tools.com/kawa/).

The packages `gnu.bytecode'
(http://sourceware.cygnus.com/kawa/api/gnu/bytecode/package-summary.html),
`gnu.math'
(http://sourceware.cygnus.com/kawa/api/gnu/math/package-summary.html),
`gnu.expr'
(http://sourceware.cygnus.com/kawa/api/gnu/expr/package-summary.html),
`gnu.mapping'
(http://sourceware.cygnus.com/kawa/api/gnu/mapping/package-summary.html),
and `gnu.text'
(http://sourceware.cygnus.com/kawa/api/gnu/text/package-summary.html),
are used by Kawa, and distributed with it, but may be independently
useful.

For a technical overview of Kawa, see these papers
(http://sourceware.cygnus.com/kawa/papers/).

Features
********

Kawa is a full Scheme implementation.  It implements almost all of R5RS
(for exceptions *note Restrictions::), plus some extensions.  By
default, symbols are case sensitive.

It is completely written in Java.  Scheme functions and files are
automatically compiled into Java byte-codes.  Kawa does some
optimizations, and the compiled code runs at reasonable speed.

Kawa provides the usual read-eval-print loop, as well as batch modes.

Kawa is written in an object-oriented style.

Kawa implements most of the features of the expression language of
DSSSL, the Scheme-derived ISO-standard Document Style Semantics and
Specification Language for SGML.  Of the core expression language, the
only features missing are character properties, `external-procedure',
the time-relationed procedures, and character name escapes in string
literals.  Also, Kawa is not generally tail-recursive.  From the full
expression language, Kawa additionally is missing `format-number',
`format-number-list', and language objects.  Quantities, keyword
values, and the expanded `lambda' form (with optional and keyword
parameters) are supported.

Getting Kawa
************

To get the Kawa sources, you have choice between the current stable
version (ftp://ftp.gnu.org/pub/gnu/kawa/kawa-stable.tar.gz) (possibly
quite old), or the newer latest snapshot of the development tree
(ftp://ftp.gnu.org/pub/gnu/kawa/kawa-newest.tar.gz) (builds and passes
the testsuite but less extensively tested).

A ready-to-run `.zip' archive of the pre-compiled classes is in
<ftp://ftp.gnu.org/pub/gnu/kawa/kawa-stable-compiled.zip>.

These are all in the Kawa ftp site (ftp://ftp.gnu.org/pub/gnu/kawa/),
which includes other versions and files, including a `.deb' Debian
package file of Kawa.

You can also check out the very latest version via anonymous cvs.
     cvs -d :pserver:anoncvs@anoncvs.cygnus.com:/cvs/kawa login
          (password is ``anoncvs'')
     cvs -d :pserver:anoncvs@anoncvs.cygnus.com:/cvs/kawa co kawa

Once you have it checked out, you can update it with `cvs update'.

You can also view the cvs archive
(http://anoncvs.cygnus.com/cgi-bin/cvsweb.cgi/kawa/?cvsroot=kawa) via
cvsweb.

Building and installing Kawa
****************************

Before installing Kawa, you must have Java working on your system.

You can compile Kawa from the source distribution.  Alternatively, you
can install the pre-compiled binary distribution.

Getting and running Java
========================

You will need a working Java system.  The discussion below assumes you
are using the Java Developer's Kit (JDK) version 1.1.x from JavaSoft
(Sun).  (Kawa has also been reported to work with Kaffe, Symantec Cafe,
J++, and JDK 1.2beta.)  You can download free copies of JDK 1.1.x for
various platforms from
<http://java.sun.com/products/jdk/1.1/index.html/index.html>.

If you want to run Kawa on a Macintosh, see
`http://home.earthlink.net/~athene/2/scheme/mackawa.html'.

The program `java' is the Java interpreter.  The program `javac' is the
Java compiler, and is needed if you want to compile the source release
yourself.  Both programs must be in your `PATH'.

You also need to set `CLASSPATH' so it includes both the current
directory, and the standard Java library.  After you have installed
Kawa, the `CLASSPATH' needs to include wherever you installed Kawa.

If you have the JDK in directory `$JDK', and you are using a
Bourne-shell compatible shell (/bin/sh, ksh, bash, and some others) you
can set both variables thus:
     PATH=$JDK/bin:$PATH
     CLASSPATH=.:$JDK/lib/classes.zip
     export PATH CLASSPATH

Installing and using the binary distribution
============================================

The binary release includes only the binary compiled `.class' versions
of the same `.java' source files in the source release.  It does not
include any documentation, so you probably want the source release in
addition to the binary release.  The purpose of the binary release is
just to save you time and trouble of compiling the sources.

The binary release comes as a `.jar' archive `kawa-1.6.66-compiled.jar'.

You can unzip the archive, or you can use it as is.  Assuming the
latter, copy the archive to some suitable location, such as
`/usr/local/lib/kawa-compiled.jar'.

Then, before you can actually run Kawa, you need to set `CLASSPATH' so
it includes the Kawa archive.  On Unix, using a Bourne-style shell:
     CLASSPATH=/usr/local/lib/kawa-compiled.jar
     export CLASSPATH

On Windows95/WindowsNT, you need to set `classpath' in a DOS console.
For example:
     set classpath=\kawa\kawa-1.6.66-compiled.jar

Then to run Kawa do:
     java kawa.repl

To run Kawa in a fresh window, you can do:
     java kawa.repl -w
On Windows, you probably do want to use the `-w' flag, because if you
run Kawa under the MS-DOS prompt, you won't see commands echoed until
you hit Enter.  (If anyone knows a way to fix this problem, please let
me know.)

Installing and using the source distribution
============================================

The Kawa release normally comes as a gzip-compressed tar file named
`kawa-1.6.66.tar.gz' .

In your build directory do:
     tar xzf kawa-1.6.66.tar.gz
     cd kawa-1.6.66

Then you must configure the sources.  This you can do the same way you
configure most other GNU software.  Normally you can just run the
configure script with no arguments:

     ./configure

This will specify that a later `make install' will install the compiled
`.class' files into `/usr/local/share/java'.  If you want them to be
installed someplace else, such as `$PREFIX/share/java', then specify
that when you run configure:
     ./configure --prefix $PREFIX

If you have the GNU `readline' library installed, you might try adding
the `--enable-kawa-frontend' flag.  This will build the `kawa'
front-end program, which provides input-line editing and an input
history.  You can get `readline' from archives of GNU programs,
including `ftp://www.gnu.org/'.

If you have installed Kawa before, make sure your `CLASSPATH' does not
include old versions of Kawa, or other classes that may conflict with
the new ones.

Thus you need to compile all the .java source files.  Just run make:
     make
This assumes that `java' and `javac' are the java interpreter and
compiler, respectively.  For example, if you are using the Kaffe Java
interpreter, you need to instead say:
     make JAVA=kaffe

You can now test the system by running Kawa in place:
     java kawa.repl

or you can run the test suite:
     (cd testsuite;  make check)

or you can install the compiled files:
     make install

This will install your classes into `$PREFIX/share/java' (and its
sub-directories).  Here `$PREFIX' is the directory you specified to
configure with the `--prefix' option, or `/usr/local' if you did not
specify a `--prefix' option.

To use the installed files, you need to set `CLASSPATH' so that
`$PREFIX/share/java' is on the path:
     CLASSPATH=$PREFIX/share/java
     export CLASSPATH
This is done automatically if you use the `kawa' script.

Building Kawa under Windows
---------------------------

The Kawa `configure' and `make' process assumes a Unix-like
environment.  If you want to build Kawa from source under Windows (95,
98, or NT), you could use a Unix empulation package, such as the free
Cygwin (http://sourceware.cygnus.com/cygwin/).  However, there are some
problems with filenames that make this more complicated than it should
be.

The Kawa source distribution now includes a simple batch file for
building Kawa under Windows.  You can do the following:

  1. Download the Kawa source distribution `kawa-1.6.66.tar.gz'.

  2. Extract the files using an appropriate tool.  (I did `tar xzf
     kawa-1.6.66.tar.gz', using the `tar' that is part of Cygwin
     (http://sourceware.cygnus.com/cygwin/).  If there are alternative
     commonly-available tools, please let me know about them.)

  3. In an MS-DOS window, `cd kawa-1.6.66'.

  4. Edit `makekawa.bat' if need be to specify the location of your
     Java tools.

  5. Execute `makekawa.bat'.

  6. If this succeeded, you should have a working kawa.  For example
     you can do `java kawa.repl -w', assuming `java' is in your `PATH'.

If you use an integrated Java development environment, you should be
able to import all the Java source files, and have it compile all of
them.  You then need to compile the builtin Scheme procedures:
     cd kawa\lib
     %KAWA% -d ..\.. -P kawa.lib. -C *.scm

How to start up and run Kawa
****************************

The easiest way to start up Kawa is to run the `kawa' program.  This
finds your java interpreter, and sets up `CLASSPATH' correctly.  If you
have installed Kawa such `$PREFIX/bin' is in your `$PATH', just do:
     kawa
However, `kawa' only works if you have a Unix-like environment.  On
some platforms, `kawa' is a program that uses the GNU `readline'
library to provide input line editing.

To run Kawa manually, you must start a Java interpreter.  How you do
this depends on the Java interpreter.  For JavaSoft's JDK, you must
have the Java interpreter in your `PATH'.  You must also make sure that
the `kawa/repl.class' file, the rest of the Kawa packages, and the
standard Java packages can be found by searching CLASSPATH.  *Note
Running Java::.

Then you do:
     java kawa.repl

In either case, you will then get the `#|kawa:1|#' prompt, which means
you are in the Kawa read-eval-print-loop.  If you type a Scheme
expression, Kawa will evaluate it.  Kawa will then print the result (if
there is a non-"void" result).

Command-line arguments
======================

You can pass various flags to Kawa, for example:
     kawa -e '(display (+ 12 4))(newline)'
or:
     java kawa.repl -e '(display (+ 12 4))(newline)'
Either causes Kawa to print `16', and then exit.

At startup, Kawa executes an init file from the user's home directory.
The init file is named `.kawarc.scm' on Unix-like systems (those for
which the file separator is `'/''), and `kawarc.scm' on other systems.
This is done before the read-eval-print loop or before the first `-f'
or `-c' argument.  (It is not run for a `-e' command, to allow you to
set options to override the defaults.)

`-e EXPR'
     Kawa evaluates EXPR, which contains one or more Scheme expressions.
     Does not cause the `~/.kawarc.scm' init file to be run.

`-c EXPR'
     Same as `-e EXPR', except that it does cause the `~/.kawarc.scm'
     init file to be run.

`-f FILENAME'
     Kawa reads and evaluates expressions from the file named by
     FILENAME.  If FILENAME is `-', standard input is read (with no
     prompting).  Otherwise, is equivalent to evaluating `(load
     "FILENAME")'.

`-s'
`--'
     The global variable `command-line-arguments' is set to the
     remaining arguments (if any), and an interactive read-eval-print
     loop is started.  This uses the same "console" as where you
     started up Kawa; use `-w' to get a new window.

`-w'
     Creates a new top-level window, and runs an interactive
     read-eval-print in the new window.  See *Note New-Window::.  Same
     as `-e (scheme-window #t)'.  You can specify multiple `-w'
     options, and also use `-s'.

`--version'
     Prints out the Kawa version number, and then exits.

`--server PORTNUM'
     Start a server listening from connections on the specified PORTNUM.
     Each connection using the Telnet protocol causes a new
     read-eval-print-loop to started.  This option allows you to
     connect using any Telnet client program to a remote "Kawa server".

`--scheme'
     Set the default language to Scheme.  (This is the default unless
     you select another language.)

`--elisp'
     Set the default language to Emacs Lisp.  (The implementation is
     quite incomplete.)

The following options control which calling conventions are used:
`--full-tailcalls'
     Use a calling convention that supports proper tail recursion.

`--no-full-tailcalls'
     Use a calling convention that does not support proper tail
     recursion.  Self-tail-recursion (i.e. a recursive call to the
     current function) is still implemented correctly, assuming that
     the called function is known at compile time.

The default is currently `--no-full-tailcalls' because I believe it is
faster (though I have not done any measurements yet).  It is also
closer to the Java call model, so may be better for people primarily
interested in using Kawa for scripting Java systems.

Both calling conventions can co-exist:  Code compiled with
`--full-tailcalls' can call code compiled with `--no-full-tailcalls'
and vice versa.

The options `-C', `-d', `-T', `-P', `--main' and `--applet' are used to
compile a Scheme file; see *Note Files compilation::.  The option
`--connect PORTNUM' is only used by the `kawa' front-end program.

If there are further command-line arguments after the options have been
processed, then the first remaining argument names a file that is read
and evaluated.  If there is no such argument, then Kawa enters an
interactive read-eval-print loop, but only if none of the `-c', `-e',
`-f', `-s', `-C', or `--' options were specified.

Running a Command Interpreter in a new Window
=============================================

An alternative interface runs the Java read-eval-print-loop inside a
new window. This is in some ways nicer.  One reason is that it provides
better editing.  You can also create new windows.  They can either have
different top-level environments or they can share environments.  To
try it, do:
     java kawa.repl -w

Exiting Kawa
============

Kawa normally keeps running as long as there is an active
read-eval-print loop still awaiting input or there is an unfinished
other computation (such as requested by a `-e' of `-f' option).

To close a read-eval-print-loop, you can type the special literal
`#!eof' at top level.  This is recognized as end-of-file.
Unfortunately, due to thread-related complications, just typing an
end-of-file character (normally ctrl/D until Unix), will not work.

If the read-eval-print-loop is in a new window, you can select `Close'
from the `File' menu.

To exit the entire Kawa session, call the `exit' procedure (with 0 or 1
integer arguments).

Features of R5RS not implemented
********************************

Kawa implements all the required and optional features of R5RS, with
the following exceptions.

The entire "numeric tower" is implemented.  However, some
transcendental function only work on reals.  Integral function do not
necessarily work on inexact (floating-point) integers.  (The whole idea
of "inexact integer" in R5RS seems rather pointless ...)

Also, `call-with-current-continuation' is only "upwards" (?).  I.e.
once a continuation has been exited, it cannot be invoked.  These
restricted continuations can be used to implement catch/throw (such as
the examples in R4RS), but not co-routines or backtracking.

Kawa now does general tail-call elimination, but only if you use the
flag `--full-tail-calls'.  (Currently, the `eval' function itself is
not fully tail-recursive, in violation of R5RS.)   The
`--full-tail-calls' flag is not on by default, partly because it is
noticably slower (though I have not measured how much), and partly I
think it is more useful for Kawa to be compilatible with standard Java
calling conventions and tools.  Code compiled with `--full-tail-calls'
can call code  compiled without it and vice versa.

Even without `--full-tail-calls', if the compiler can prove that the
procedure being called is the current function, then the tail call will
be replaced by a jump.  This means the procedure must be defined using
a letrec, not a define (because the compiler does not know if someone
might re-define a global definition), and there must be no assignments
(using `set!') to the procedure binding.

Compiling Scheme code to byte-codes
***********************************

All Scheme functions and source files are invisibly compiled into
internal Java byte-codes.  A traditional evaluator is only used for
top-level directly entered expressions _outside_ a lambda.  (It would
have been simpler to also byte-compile top-level expressions by
surrounding them by a dummy lambda.  However, this would create a new
Class object in the Java VM for every top-level expression.  This is
undesirable unless you have a VM that can garbage collect Class
objects.)

To save speed when loading large Scheme source files, you probably want
to pre-compile them and save them on your local disk.  There are two
ways to do this.

You can compile a Scheme source file to a single archive file.  You do
this using the `compile-file' function.  The result is a single file
that you can move around and `load' just like the `.scm' source file.
You just specify the name of the archive file to the `load' procedure.
Currently, the archive is a "zip" archive and has extension ".zip"; a
future release will probably use "Java Archive" (jar) files.  The
advantage of compiling to an archive is that it is simple and
transparent.  A minor disadvantage is that it causes the Java
"verifier" to be run when functions are loaded from it, which takes a
little extra time.

Alternatively, you can compile a Scheme source file to a collection of
`.class' files.  You then use the standard Java class loading mechanism
to load the code.  The Java "verifier" does not need to get run, which
makes loading a little faster.  The compiled class files do have to be
installed be installed somewhere in the `CLASSPATH'.

Compiling Scheme to an archive file
===================================

To byte-compile a file `foo.scm' do:
     (compile-file "foo.scm" "foo")

This will create `foo.zip', which contains byte-compiled "j-code" that
implements `foo.scm'.

You can later do:
     (load "foo")

This will load `foo.zip', which should have the same effect as loading
`foo.scm', except you will get the byte-compiled versions.

Compiling Scheme to a set of .class files
=========================================

Invoking `kawa' (or `java kawa.repl') with the `-C' flag will compile a
`.scm' source file into one or more `.class' files.

You run it as follows:
     kawa [-d OUTDIRECTORY] [-P PREFIX] [-T TOPNAME] [--main | --spplet] -C INFILE ...

Note the `-C' must come last, because `Kawa' processes the arguments
and options in order,

Here:
`-C INFILE ...'
     The Scheme source files we want to compile.

`-d OUTDIRECTORY'
     The directory under which the resulting `.class' files will be.
     The default is the current directory.

`-P PREFIX'
     A string to prepend to the generated class names.  The default is
     the empty string.

`-T TOPNAME'
     The name of the "top" class - i.e. the one that contains the code
     for the top-level expressions and definitions.  The default is
     generated from the INFILE and PREFIX.

`--main'
     Generate a `main' method so that the resulting "top" class can be
     used as a stand-alone application. *Note Application compilation::.

`--applet'
     The resulting class inherits from `java.applet.Applet', and can be
     used as an applet.  *Note Applet compilation::.

When you actually want to load the classes, the OUTDIRECTORY must be in
your `CLASSPATH'.  You can use the standard `load' function to load the
code, by specifying the top-level class, either as a file name
(relative to OUTDIRECTORY) or a class name.  E.g. if you did:
     kawa -d /usr/local/share/java -P my.lib. -T foo -C foosrc.scm
you can use either:
     (load "my.lib.foo")
or:
     (load "my/lib/foo.class")

If you are compiling a Scheme source file (say `foosrc.scm') that uses
macros defined in some other file (say `macs.scm'), you need to make
sure the definitions are visible to the compiler.  One way to do that
is with the `-f':
     kawa -f macs.scm -C foosrc.scm

Compiling Scheme to a standalone application
============================================

A Java application is a Java class with a special method (whose name is
`main').  The application can be invoked directly by naming it in the
Java command.  If you want to generate an application from a Scheme
program, create a Scheme source file with the definitions you need, plus
the top-level actions that you want the application to execute.  You
can compile in the regular way decribed in the previous section, but add
the `--main' option.  For example, assuming your Scheme file is
`MyProgram.scm':
     kawa --main -C MyProgram.scm
This will create a `MyProgram.class' which you can either `load' (as
decribed in the previous section), or invoke as an application:
     java MyProgram [ARGS]
Your Scheme program can access the command-line arguments ARGS by using
the global variable `command-line-arguments'.

Compiling Scheme to an applet
=============================

An applet is a Java class that inherits from `java.applet.Applet'.  The
applet can be downloaded and run in a Java-capable web-browser.  To
generate an applet from a Scheme program, write the Scheme program with
appropriate definitions of the functions `init', `start', `stop' and
`destroy'.  You must declare these as zero-argument functions with a
`<void>' return-type.

Here is an example, based on the scribble applet in Flanagan's "Java
Examples in a Nutshell" (O'Reilly, 1997):
     (define-private last-x 0)
     (define-private last-y 0)
     
     (define (init) <void>
       (let ((applet :: <java.applet.Applet> (this)))
         (invoke applet 'addMouseListener
     	    (object (<java.awt.event.MouseAdapter>)
     		    ((mousePressed (e :: <java.awt.event.MouseEvent>)) <void>
     		     (set! last-x (invoke e 'getX))
     		     (set! last-y (invoke e 'getY)))))
         (invoke applet 'addMouseMotionListener
     	    (object (<java.awt.event.MouseMotionAdapter>)
     		    ((mouseDragged (e :: <java.awt.event.MouseEvent>)) <void>
     		     (let ((g :: <java.awt.Graphics>
     			      (invoke applet 'getGraphics))
     			   (x :: <int> (invoke e 'getX))
     			   (y :: <int> (invoke e 'getY)))
     		       (invoke g 'drawLine last-x last-y x y)
     		       (set! last-x x)
     		       (set! last-y y)))))))
     
     (define (start) <void> (format #t "called start.~%~!"))
     (define (stop) <void> (format #t "called stop.~%~!"))
     (define (destroy) <void> (format #t "called destroy.~%~!"))

You compile the program with the `--applet' flag in addition to the
normal `-C' flag:
     java kawa.repl --applet -C scribble.scm

You can then create a `.jar' archive containing your applet.  You also
need to include the Kawa classes in the `.jar', or you can include a
`MANIFEST' file that specifies `Class-Path' to use a Java 2 download
extension
(http://java.sun.com/docs/books/tutorial/ext/basics/download.html).
     jar cf scribble.jar scribble*.class other-classes ...

Finally, you create an `.html' page referencing your applet:
     <html><head><title>Scribble testapp</title></head>
     <body><h1>Scribble testapp</h1>
     You can scribble here:
     <br>
     <applet code="scribble.class" archive="scribble.jar" width=200 height=200>
     Sorry, Java is needed.</applet>
     </body></html>

Extensions
**********

Multiple values
===============

The multiple-value feature was added in R5RS.

 - Function: values object ...
     Delivers all of its arguments to its continuation.

 - Function: call-with-values thunk receiver
     Call its THUNK argument with a continuation that, when passed some
     values, calls the RECEIVER procedure with those values as
     arguments.

Special named constants
=======================

 - Constant: #!optional
     Special self-evaluating literal used in lambda parameter lists
     before optional parameters.

 - Constant: #!rest
     Special self-evaluating literal used in lambda parameter lists
     before the rest parameter.

 - Constant: #!key
     Special self-evaluating literal used in lambda parameter lists
     before keyword parameters.

 - Constant: #!eof
     The end-of-file object.

     Note that if the Scheme reader sees this literal at top-level, it
     is returned literally.  This is indistinguishable from coming to
     the end of the input file.  If you do not want to end reading, but
     want the actual value of `#!eof', you should quote it.

 - Constant: #!void
     The void value.  Same as `(values)'.  If this is the value of an
     expression in a read-eval-print loop, nothing is printed.

 - Constant: #!null
     The Java `null' value.  This is not really a Scheme value, but is
     useful when interfacing to low-level Java code.

Keywords
========

Keywords are similar to symbols.  The main difference is that keywords
are self-evaluating and therefore do not need to be quoted in
expressions.  They are used mainly for specifying keyword arguments.

     KEYWORD = IDENTIFIER:

An alternative syntax, with the colon first, is supported for
compatibility with Common Lisp and some other Scheme implementations:

     KEYWORD = :IDENTIFIER

Putting the colon first has exactly the same effect as putting it last;
putting is last is recommended, and is how keywords are printed.

A keyword is a single token; therefore no whitespace is allowed between
the IDENTIFIER and the colon (which is not considered part of the name
of the keyword).

 - Function: keyword? obj
     Return `#t' if OBJ is a keyword, and otherwise returns `#f'.

 - Function: keyword->string keyword
     Returns the name of KEYWORD as a string.  The name does not
     include the final `#\:'.

 - Function: string->keyword string
     Returns the keyword whose name is STRING.  (The STRING does not
     include a final `#\:'.)

Extended Formal Arguments List
==============================

The formal arguments list of a lambda expression has two extendsions
over standard Scheme: Kawa borrows the extended formal argument list of
DSSSL, and Kawa allows you to declare the type of the parameter.

     LAMBDA-EXPRESSION = (lambda FORMALS [RTYPE] BODY)
where
     FORMALS = (FORMAL-ARGUMENTS) | REST-ARG
You can of course also use the extended format in a `define':
     (define (NAME FORMAL-ARGUMENTS) [RTYPE] BODY)

     FORMAL-ARGUMENTS =
     REQ-OPT-ARGS (REST-KEY-ARGS | . REST-ARG)

     REQ-OPT-ARGS = REQ-ARG ... [#!optional OPT-ARG ...]
     REST-KEY-ARGS = [#!rest REST-ARG] [#key KEY-ARG ...]
     REQ-ARG = VARIABLE [:: TYPE] | (VARIABLE TYPE)
     OPT-ARG = ARG-WITH-DEFAULT
     KEY-ARG =  ARG-WITH-DEFAULT
     ARG-WITH-DEFAULT = VARIABLE [:: TYPE] | (VARIABLE INITIALIZER [TYPE]) | (VARIABLE :: TYPE [INITIALIZER])
     REST-ARG = VARIABLE

When the procedure is applied to a list of actual arguments, the formal
and actual arguments are processed from left to right as follows:

   * The REQ-ARGs are bound to actual arguments starting with the first
     actual argument.  It shall be an error if there are fewer actual
     arguments then there are REQ-ARGs.

   * Next the OPT-ARGs are bound to remaining actual arguemnts.  If
     there are fewer remaining actual arguments than there are
     OPT-ARGs, then the remaining VARIABLEs are bound to the
     corresponding INITIALIZER, if one was specified, and otherwise to
     `#f'.  The INITIALIZER is evaluated in an environment in which all
     the previous formal parameters have been bound.

   * If there is a REST-ARG, it is bound to a list of all the remaining
     actual arguments.  These remaining actual arguments are also
     eligible to be bound to keyword arguments.   If there is no
     REST-ARG and there are no KEY-ARGs, then it shall be an error if
     there are any remaining actual arguments.

   * If `#!key' was specified, then there shall be an even number of
     remaining actual arguments.  These are interpreted as a series of
     pairs, where the first member of each pair is a keyword specifying
     the argument name, and the second is the corresponding value.  It
     shall be an error if the first member of a pair is not a keyword.
     It shall be an error if the argument name is not the same as a
     variable in a KEY-ARGs, unless there is a REST-ARG.  If the same
     argument name occurs more than once in the list of actual
     arguments, then the first value is used.  If there is no actual
     argument for a particular KEY-ARG, then the variable is bound to
     the corresponding INITIALIZER, if one was specified, and otherwise
     to `#f'.  The INITIALIZER is evaluated in an environment in which
     all the previous formal parameters have been bound.

If a TYPE is specified, the corresponding actual argument (or the
INITIALIZER default value) is coerced to the specified TYPE.  In the
function body, the parameter has the specified type.

If RTYPE (the first form of the function body) is an unbound identifier
of the form `<TYPE>' (that is the first character is `<' and the last
is `>'), then tha specifies the functions return type.  It is syntactic
sugar for `(as <TYPE> (begin BODY))'.

Quantities
==========

As a super-class of numbers, Kawa also provides quantities.  A
"quantity" is a product of a "unit" and a pure number.  The number part
can be an arbitrary complex number.  The unit is a product of integer
powers of base units, such as meter or second.

Kawa quantities are a generalization of the quantities in DSSSL, which
only has length-derived quantities.

The precise syntax of quantity literals may change, but some examples
are `10pt' (10 points), `5s' (5 seconds), and `4cm2' (4 square
centimeters).

 - Function: quantity? object
     True iff OBJECT is a quantity.  Note that all numbers are
     quantities, but not the other way round.  Currently, there are no
     quantities that re not numbers.  To distinguish a plain unit-less
     number from a quantity, you can use `complex?'.

 - Function: quantity->number q
     Returns the pure number part of the quantity Q, relative to
     primitive (base) units.  If Q is a number, returns Q.  If Q is a
     unit, yields the magitude of Q relative to base units.

 - Function: quantity->unit q
     Returns the unit of the quantity Q.  If Q is a number, returns the
     empty unit.

 - Function: make-quantity x unit
     Returns the product of X (a pure number) and UNIT.  You can
     specify a string instead of UNIT, such as `"cm"' or `"s"'
     (seconds).

 - Syntax: define-unit unit-name expression
     Define UNIT-NAME as a unit (that can be used in literals) equal to
     the quantity EXPRESSION.

Logical Number Operations
=========================

These functions operate on the 2's complement binary representation of
an exact integer.

 - Function: logand i ...
     Returns the bit-wise logical "and" of the arguments.  If no
     argument is given, the result is -1.

 - Function: logior i ...
     Returns the bit-wise logical "(inclusive) or" of the arguments.
     If no argument is given, the result is 0.

 - Function: logxor i ...
     Returns the bit-wise logical "exclusive or" of the arguments.  If
     no argument is given, the result is 0.

 - Function: lognot i
     Returns the bit-wise logical inverse of the argument.

 - Function: logop op x y
     Perform one of the 16 bitwise operations of X and Y, depending on
     OP.

 - Function: bittest i j
     Returns true if the arguments have any bits in common.  Same as
     `(not (zero? (logand I J)))', but is more efficient.

 - Function: logbit? i pos
     Returns `#t' iff the bit numbered POS in I is one.

 - Function: arithmetic-shift i j
     Shifts I by J.  It is a "left" shift if `J>0', and a "right" shift
     if `J<0'.

     The result is equal to `(floor (* I (expt 2 J)))'.

 - Function: ash i j
     Alias for `arithmetic-shift'.

 - Function: logcount i
     Count the number of 1-bits in I, if it is non-negative.  If I is
     negative, count number of 0-bits.

 - Function: integer-length i
     Return number of bits needed to represent I in an unsigned field.
     Regardless of the sign of I, return one less than the number of
     bits needed for a field that can represent I as a two's complement
     integer.

 - Function: bit-extract n start end
     Return the integer formed from the (unsigned) bit-field starting
     at START and ending just before END.  Same as `(arithmetic-shift
     (bitand n (bitnot (arithmetic-shift -1 end))) (- start))'.

Strings
=======

 - Function: string-upcase str
     Return a new string where the letters in STR are replaced by their
     upper-case equivalents.

 - Function: string-downcase str
     Return a new string where the letters in STR are replaced by their
     lower-case equivalents.

 - Function: string-capitalize str
     Return a new string where the letters in STR that start a new word
     are replaced by their title-case equivalents, while non-initial
     letters are replaced by their lower-case equivalents.

 - Function: string-upcase! str
     Destructively modify STR, replacing the letters by their
     upper-case equivalents.

 - Function: string-downcase! str
     Destructively modify STR, replacing the letters by their
     upper-lower equivalents.

 - Function: string-capitalize! str
     Destructively modify STR, such that the letters that start a new
     word are replaced by their title-case equivalents, while
     non-initial letters are replaced by their lower-case equivalents.

Uniform vectors
===============

Uniform vectors are vectors whose elements are of the same numeric type.
The are defined by SRFI-4 (http://srfi.schemers.org/srfi-4/srfi-4.html).
However, the type names (such as `<s8vector>') are a Kawa extension.

 - Variable: <s8vector>
     The type of uniform vectors where each element can contain a
     signed 8-bit integer.  Represented using an array of `<byte>'.

 - Variable: <u8vector>
     The type of uniform vectors where each element can contain an
     unsigned 8-bit integer.  Represented using an array of `<byte>',
     but each element is treated as if unsigned.

 - Variable: <s16vector>
     The type of uniform vectors where each element can contain a
     signed 16-bit integer.  Represented using an array of `<short>'.

 - Variable: <u16vector>
     The type of uniform vectors where each element can contain an
     unsigned 16-bit integer.  Represented using an array of `<short>',
     but each element is treated as if unsigned.

 - Variable: <s32vector>
     The type of uniform vectors where each element can contain a
     signed 32-bit integer.  Represented using an array of `<int>'.

 - Variable: <u32vector>
     The type of uniform vectors where each element can contain an
     unsigned 32-bit integer.  Represented using an array of `<int>',
     but each element is treated as if unsigned.

 - Variable: <s64vector>
     The type of uniform vectors where each element can contain a
     signed 64-bit integer.  Represented using an array of `<long>'.

 - Variable: <u64vector>
     The type of uniform vectors where each element can contain an
     unsigned 64-bit integer.  Represented using an array of `<long>',
     but each element is treated as if unsigned.

 - Variable: <f32vector>
     The type of uniform vectors where each element can contain a
     32-bit floating-point real.  Represented using an array of
     `<float>'.

 - Variable: <f64vector>
     The type of uniform vectors where each element can contain a
     64-bit floating-point real.  Represented using an array of
     `<double>'.

 - Function: s8vector? value
 - Function: u8vector? value
 - Function: s16vector? value
 - Function: u16vector? value
 - Function: s32vector? value
 - Function: u32vector? value
 - Function: s64vector? value
 - Function: u64vector? value
 - Function: f32vector? value
 - Function: f64vector? value
     Return true iff VALUE is a uniform vector of the specified type.

 - Function: make-s8vector n [value]
 - Function: make-u8vector n [value]
 - Function: make-s16vector n [value]
 - Function: make-u16vector n [value]
 - Function: make-s32vector n [value]
 - Function: make-u32vector n [value]
 - Function: make-s64vector n [value]
 - Function: make-u64vector n [value]
 - Function: make-f32vector n [value]
 - Function: make-f64vector n [value]
     Create a new uniform vector of the specified type, having room for
     N elements.  Initialize each element to VALUE if it is specified;
     zero otherwise.

 - Function: s8vector value ...
 - Function: u8vector value ...
 - Function: s16vector value ..
 - Function: u16vector value ...
 - Function: s32vector value ...
 - Function: u32vector value ...
 - Function: s64vector value ...
 - Function: u64vector value ...
 - Function: f32vector value ...
 - Function: f64vector value ...
     Create a new uniform vector of the specified type, whose length is
     the number of VALUEs specified, and initialize it using those
     VALUEs.

 - Function: s8vector-length v
 - Function: u8vector-length v
 - Function: s16vector-length v
 - Function: u16vector-length v
 - Function: s32vector-length v
 - Function: u32vector-length v
 - Function: s64vector-length v
 - Function: u64vector-length v
 - Function: f32vector-length v
 - Function: f64vector-length v
     Return the length (in number of elements) of the uniform vector V.

 - Function: s8vector-ref v i
 - Function: u8vector-ref v i
 - Function: s16vector-ref v i
 - Function: u16vector-ref v i
 - Function: s32vector-ref v i
 - Function: u32vector-ref v i
 - Function: s64vector-ref v i
 - Function: u64vector-ref v i
 - Function: f32vector-ref v i
 - Function: f64vector-ref v i
     Return the element at index I of the uniform vector V.

 - Function: s8vector-set! v i x
 - Function: u8vector-set! v i x
 - Function: s16vector-set! v i x
 - Function: u16vector-set! v i x
 - Function: s32vector-set! v i x
 - Function: u32vector-set! v i x
 - Function: s64vector-set! v i x
 - Function: u64vector-set! v i x
 - Function: f32vector-set! v i x
 - Function: f64vector-set! v i x
     Set the element at index I of uniform vector V to the value X,
     which must be a number coercible to the appropriate type.

 - Function: s8vector->list v
 - Function: u8vector->list v
 - Function: s16vector->list v
 - Function: u16vector->list v
 - Function: s32vector->list v
 - Function: u32vector->list v
 - Function: s64vector->list v
 - Function: u64vector->list v
 - Function: f32vector->list v
 - Function: f64vector->list v
     Convert the uniform vetor V to a list containing the elments of V.

 - Function: list->s8vector l
 - Function: list->u8vector l
 - Function: list->s16vector l
 - Function: list->u16vector l
 - Function: list->s32vector l
 - Function: list->u32vector l
 - Function: list->s64vector l
 - Function: list->u64vector l
 - Function: list->f32vector l
 - Function: list->f64vector l
     Create a uniform vector of the appropriate type, initializing it
     with the elements of the list L.  The elements of L must be
     numbers coercible the new vector's element type.

File System Interface
=====================

 - Function: file-exists? filename
     Returns true iff the file named FILENAME actually exists.

 - Function: file-directory? filename
     Returns true iff the file named FILENAME actually exists and is a
     directory.

 - Function: file-readable? filename
     Returns true iff the file named FILENAME actually exists and can
     be read from.

 - Function: file-writable? filename
     Returns true iff the file named FILENAME actually exists and can
     be writen to.  (Undefined if the FILENAME does not exist, but the
     file can be created in the directory.)

 - Function: delete-file filename
     Delete the file named FILENAME.

 - Function: rename-file oldname newname
     Renames the file named OLDNAME to NEWNAME.

 - Function: copy-file oldname newname-from path-to
     Copy the file named OLDNAME to NEWNAME.  The return value is
     unspecified.

 - Function: create-directory dirname
     Create a new directory named DIRNAME.  Unspecified what happens on
     error (such as exiting file with the same name).  (Currently
     returns `#f' on error, but may change to be more compatible with
     scsh.)

 - Function: system-tmpdir
     Return the name of the default directory for temporary files.

 - Function: make-temporary-file [format]
     Return a file with a name that does not match any existing file.
     Use FORMAT (which defaults to `"kawa~d.tmp"') to generate a unique
     filename in `(system-tmpdir)'.  The current implementation is
     _not_ safe from race conditions; this will be fixed in a future
     release (using Java2 features).

Ports
=====

 - Function: read-line [port [handle-newline]]
     Reads a line of input from PORT.  The HANDLE-NEWLINE parameter
     determines what is done with terminating end-of-line delimiter.
     The default, `'trim', ignores the delimiter; `'peek' leaves the
     delimiter in the input stream; `'concat' appends the delimiter to
     the returned value; and `'split' returns the delimiter as a second
     value.  You can use the last three options to tell if the string
     was terminated by end-or-line or by end-of-file.

 - Function: open-input-string string
     Takes a string and returns an input port that delivers characters
     from the string. The port can be closed by `close-input-port',
     though its storage will be reclaimed by the garbage collector if
     it becomes inaccessible.

          (define p
            (open-input-string "(a . (b c . ())) 34"))
          
          (input-port? p)                 -->  #t
          (read p)                        -->  (a b c)
          (read p)                        -->  34
          (eof-object? (peek-char p))     -->  #t

 - Function: open-output-string
     Returns an output port that will accumulate characters for
     retrieval by `get-output-string'.  The port can be closed by the
     procedure `close-output-port', though its storage will be
     reclaimed by the garbage collector if it becomes inaccessible.
          (let ((q (open-output-string))
            (x '(a b c)))
              (write (car x) q)
              (write (cdr x) q)
              (get-output-string q))        -->  "a(b c)"

 - Function: get-output-string output-port
     Given an output port created by `open-output-string', returns a
     string consisting of the characters that have been output to the
     port so far.

 - Function: call-with-input-string string proc
     Create an input port that gets its data from STRING, call PROC
     with that port as its one argument, and return the result from the
     call of PROC

 - Function: call-with-output-string proc
     Create an output port that writes its data to a STRING, and call
     PROC with that port as its one argument.  Return a string
     consisting of the data written to the port.

 - Function: force-output [port]
     Forces any pending output on PORT to be delivered to the output
     device and returns an unspecified value.  If the PORT argument is
     omitted it defaults to the value returned by
     `(current-output-port)'.

An interactive input port has a prompt procedure associated with it.
The prompt procedure is called before a new line is read.  It is passed
the port as an argument, and returns a string, which gets printed as a
prompt.

 - Function: input-port-prompter port
     Get the prompt procedure associated with PORT.

 - Function: set-input-port-prompter! port prompter
     Set the prompt procedure associated with PORT to PROMPTER, which
     must be a one-argument procedure taking an input port, and
     returning a string.

 - Function: default-prompter port
     The default prompt procedure.  It returns `"#|kawa:L|# "', where L
     is the current line number of PORT.  When reading a continuation
     line, the result is `"#|C---:L|# "', where `C' is the character
     returned by `(input-port-read-state PORT)'.  The prompt has the
     form of a comment to make it easier to cut-and-paste.

 - Function: port-column input-port
 - Function: port-line input-port
     Return the current column number or line number of INPUT-PORT,
     using the current input port if none is specified.  If the number
     is unknown, the result is `#f'.  Otherwise, the result is a
     0-origin integer - i.e. the first character of the first line is
     line 0, column 0.  (However, when you display a file position, for
     example in an error message, we recommend you add 1 to get
     1-origin integers.  This is because lines and column numbers
     traditionally start with 1, and that is what non-programmers will
     find most natural.)

 - Function: set-port-line! port line
     Set (0-origin) line number of the current line of PORT to NUM.

 - Function: input-port-line-number port
     Get the line number of the current line of PORT, which must be a
     (non-binary) input port.  The initial line is line 1.  Deprecated;
     replaced by `(+ 1 (port-line PORT))'.

 - Function: set-input-port-line-number! port num
     Set line number of the current line of PORT to NUM.  Deprecated;
     replaced by `(set-port-line PORT (- NUM 1))'.

 - Function: input-port-column-number port
     Get the column number of the current line of PORT, which must be a
     (non-binary) input port.  The initial column is column 1.
     Deprecated; replaced by `(+ 1 (port-column PORT))'.

 - Function: input-port-read-state port
     Returns a character indicating the current `read' state of the
     PORT.  Returns `#\Return' if not current doing a READ, `#\"' if
     reading a string;  `#\|' if reading a comment;  `#\(' if inside a
     list; and `#\Space' when otherwise in a `read'.  The result is
     intended for use by prompt prcedures, and is not necessarily
     correct except when reading a new-line.

 - Variable: symbol-read-case
     A symbol that controls how `read' handles letters when reading a
     symbol.  If the first letter is `U', then letters in symbols are
     upper-cased.  If the first letter is `D' or `L', then letters in
     symbols are down-cased.  If the first letter is `I', then the case
     of letters in symbols is inverted.  Otherwise (the default), the
     letter is not changed.  (Letters following a `\' are always
     unchanged.)

 - Variable: port-char-encoding
     Controls how bytes in external files are converted to/from internal
     Unicode characters.  Can be either a symbol or a boolean.  If
     `port-char-encoding' is `#f', the file is assumed to be a binary
     file and no conversion is done.  Otherwise, the file is a text
     file.  The default is `#t', which uses a locale-dependent
     conversion.  If `port-char-encoding' is a symbol, it must be the
     name of a character encoding known to Java.  For all text files
     (that is if `port-char-encoding' is not `#f'), on input a
     `#\Return' character or a `#\Return' followed by `#\Newline' are
     converted into plain `#\Newline'.

     This variable is checked when the file is opened;  not when
     actually reading or writing.  Here is an example of how you can
     safely change the encoding temporarily:
          (define (open-binary-input-file name)
            (fluid-let ((port-char-encoding #f)) (open-input-file name)))

Formatted Output (Common-Lisp-style)
====================================

 - Function: format destination fmt . arguments
     An almost complete implementation of Common LISP format description
     according to the CL reference book `Common LISP' from Guy L.
     Steele, Digital Press.  Backward compatible to most of the
     available Scheme format implementations.

     Returns `#t', `#f' or a string; has side effect of printing
     according to FMT.  If DESTINATION is `#t', the output is to the
     current output port and `#t' is returned.  If DESTINATION is `#f',
     a formatted string is returned as the result of the call.  If
     DESTINATION is a string, DESTINATION is regarded as the format
     string; FMT is then the first argument and the output is returned
     as a string. If DESTINATION is a number, the output is to the
     current error port if available by the implementation. Otherwise
     DESTINATION must be an output port and `#t' is returned.

     FMT must be a string or an instance of `gnu.text.MessageFormat' or
     `java.text.MessageFormat'.  If FMT is a string, it is parsed as if
     by `parse-format'.

 - Function: parse-format format-string
     Parses `format-string', which is a string of the form of a Common
     LISP format description.  Returns an instance of
     `gnu.text.ReportFormat', which can be passed to the `format'
     function.

A format string passed to `format' or `parse-format' consists of format
directives (that start with `~'), and regular characters (that are
written directly to the destination).  Most of the Common Lisp (and
Slib) format directives are implemented.  Neither justification, nor
pretty-printing are supported yet.

Plus of course, we need documentation for `format'!

Implemented CL Format Control Directives
----------------------------------------

Documentation syntax: Uppercase characters represent the corresponding
control directive characters. Lowercase characters represent control
directive parameter descriptions.

`~A'
     Any (print as `display' does).
    `~@A'
          left pad.

    `~MINCOL,COLINC,MINPAD,PADCHARA'
          full padding.

`~S'
     S-expression (print as `write' does).
    `~@S'
          left pad.

    `~MINCOL,COLINC,MINPAD,PADCHARS'
          full padding.

`~C'
     Character.
    `~@C'
          prints a character as the reader can understand it (i.e. `#\'
          prefixing).

    `~:C'
          prints a character as emacs does (eg. `^C' for ASCII 03).

Formatting Integers
-------------------

`~D'
     Decimal.
    `~@D'
          print number sign always.

    `~:D'
          print comma separated.

    `~MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHD'
          padding.

`~X'
     Hexadecimal.
    `~@X'
          print number sign always.

    `~:X'
          print comma separated.

    `~MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHX'
          padding.

`~O'
     Octal.
    `~@O'
          print number sign always.

    `~:O'
          print comma separated.

    `~MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHO'
          padding.

`~B'
     Binary.
    `~@B'
          print number sign always.

    `~:B'
          print comma separated.

    `~MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHB'
          padding.

`~NR'
     Radix N.
    `~N,MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHR'
          padding.

`~@R'
     print a number as a Roman numeral.

`~:@R'
     print a number as an "old fashioned" Roman numeral.

`~:R'
     print a number as an ordinal English number.

`~:@R'
     print a number as a cardinal English number.

`~P'
     Plural.
    `~@P'
          prints `y' and `ies'.

    `~:P'
          as `~P but jumps 1 argument backward.'

    `~:@P'
          as `~@P but jumps 1 argument backward.'

COMMAWIDTH is the number of characters between two comma characters.

Formatting floating-point (real) numbers
----------------------------------------

`~F'
     Fixed-format floating-point (prints a flonum like MMM.NNN).
    `~WIDTH,DIGITS,SCALE,OVERFLOWCHAR,PADCHARF'

    `~@F'
          If the number is positive a plus sign is printed.

`~E'
     Exponential floating-point (prints a flonum like MMM.NNN`E'EE)
    `~WIDTH,DIGITS,EXPONENTDIGITS,SCALE,OVERFLOWCHAR,PADCHAR,EXPONENTCHARE'

    `~@E'
          If the number is positive a plus sign is printed.

`~G'
     General floating-point (prints a flonum either fixed or
     exponential).
    `~WIDTH,DIGITS,EXPONENTDIGITS,SCALE,OVERFLOWCHAR,PADCHAR,EXPONENTCHARG'

    `~@G'
          If the number is positive a plus sign is printed.  A slight
     difference from Common Lisp:  If the number is printed in fixed
     form and the fraction is zero, then a zero digit is printed for
     the fraction, if allowed by the WIDTH and DIGITS is unspecified.

`~$'
     Dollars floating-point (prints a flonum in fixed with signs
     separated).
    `~DIGITS,SCALE,WIDTH,PADCHAR$'

    `~@$'
          If the number is positive a plus sign is printed.

    `~:@$'
          A sign is always printed and appears before the padding.

    `~:$'
          The sign appears before the padding.

Miscellaneous formatting operators
----------------------------------

`~%'
     Newline.
    `~N%'
          print N newlines.

`~&'
     print newline if not at the beginning of the output line.
    `~N&'
          prints `~&' and then N-1 newlines.

`~|'
     Page Separator.
    `~N|'
          print N page separators.

`~~'
     Tilde.
    `~N~'
          print N tildes.

`~'<newline>
     Continuation Line.
    `~:'<newline>
          newline is ignored, white space left.

    `~@'<newline>
          newline is left, white space ignored.

`~T'
     Tabulation.
    `~@T'
          relative tabulation.

    `~COLNUM,COLINCT'
          full tabulation.

`~?'
     Indirection (expects indirect arguments as a list).
    `~@?'
          extracts indirect arguments from format arguments.

`~(STR~)'
     Case conversion (converts by `string-downcase').
    `~:(STR~)'
          converts by `string-capitalize'.

    `~@(STR~)'
          converts by `string-capitalize-first'.

    `~:@(STR~)'
          converts by `string-upcase'.

`~*'
     Argument Jumping (jumps 1 argument forward).
    `~N*'
          jumps N arguments forward.

    `~:*'
          jumps 1 argument backward.

    `~N:*'
          jumps N arguments backward.

    `~@*'
          jumps to the 0th argument.

    `~N@*'
          jumps to the Nth argument (beginning from 0)

`~[STR0~;STR1~;...~;STRN~]'
     Conditional Expression (numerical clause conditional).
    `~N['
          take argument from N.

    `~@['
          true test conditional.

    `~:['
          if-else-then conditional.

    `~;'
          clause separator.

    `~:;'
          default clause follows.

`~{STR~}'
     Iteration (args come from the next argument (a list)).
    `~N{'
          at most N iterations.

    `~:{'
          args from next arg (a list of lists).

    `~@{'
          args from the rest of arguments.

    `~:@{'
          args from the rest args (lists).

`~^'
     Up and out.
    `~N^'
          aborts if N = 0

    `~N,M^'
          aborts if N = M

    `~N,M,K^'
          aborts if N <= M <= K

Not Implemented CL Format Control Directives
--------------------------------------------

`~:A'
     print `#f' as an empty list (see below).

`~:S'
     print `#f' as an empty list (see below).

`~<~>'
     Justification.

`~:^'
Extended, Replaced and Additional Control Directives
....................................................

These are not necesasrily implemented in Kawa!

`~I'
     print a R4RS complex number as `~F~@Fi' with passed parameters for
     `~F'.

`~Y'
     Pretty print formatting of an argument for scheme code lists.

`~K'
     Same as `~?.'

`~!'
     Flushes the output if format DESTINATION is a port.

`~_'
     Print a `#\space' character
    `~N_'
          print N `#\space' characters.

`~NC'
     Takes N as an integer representation for a character. No arguments
     are consumed. N is converted to a character by `integer->char'.  N
     must be a positive decimal number.

`~:S'
     Print out readproof.  Prints out internal objects represented as
     `#<...>' as strings `"#<...>"' so that the format output can always
     be processed by `read'.

`~:A'
     Print out readproof.  Prints out internal objects represented as
     `#<...>' as strings `"#<...>"' so that the format output can always
     be processed by `read'.

`~F, ~E, ~G, ~$'
     may also print number strings, i.e. passing a number as a string
     and format it accordingly.

Signalling and recovering from exceptions
=========================================

 - Function: catch key thunk handler
     Invoke THUNK in the dynamic context of HANDLER for exceptions
     matching KEY.  If thunk throws to the symbol KEY, then HANDLER is
     invoked this way:

          (handler key args ...)

     KEY may be a symbol.  The THUNK takes no arguments.  If THUNK
     returns normally, that is the return value of `catch'.

     Handler is invoked outside the scope of its own `catch'.  If
     HANDLER again throws to the same key, a new handler from further
     up the call chain is invoked.

     If the key is `#t', then a throw to _any_ symbol will match this
     call to `catch'.

 - Function: throw key &rest args ...
     Invoke the catch form matching KEY, passing ARGS to the HANDLER.

     If the key is a symbol it will match catches of the same symbol or
     of #t.

     If there is no handler at all, an error is signaled.

 - procedure: error message args ...
     Raise an error with key `misc-error' and a message constructed by
     displaying MSG and writing ARGS.  This normally prints a stack
     trace, and brings you back to the top level, or exits kawa if you
     are not running interactively.

 - Function: primitive-throw exception
     Throws the EXCEPTION, which must be an instance of a sub-class of
     `<java.lang.Throwable>'.

 - Syntax: try-finally body handler
     Evaluate BODY, and return its result.  However, before it returns,
     evaluate HANDLER.  Even if BODY returns abnormally (by throwing an
     exception), HANDLER is evaluated.

     (This is implemented just like Java's `try'-`finally'.)

 - Syntax: try-catch body handler ...
     Evaluate BODY, in the conect of the given HANDLER-SPECs.  Each
     HANDLER has the form:
          VAR TYPE EXP ...
     If an exception is thrown in BODY, the first HANDLE-SPEC is
     selected such that the thrown exception is an instance of the
     HANDLER's TYPE. If no HANDLER is selected, the exception is
     propagated through the dynamic execution context until a matching
     HANDLER is found.  (If no matching HANDLER is found, then an error
     message is printed, and the computation terminated.)

     Once a HANDLER is selected, the VAR is bound to the thrown
     exception, and the EXP in the HANDLER are executed.  The result of
     the `try-catch' is the result of BODY if no exception is thrown,
     or the value of the last EXP in the selected HANDLER if an
     exception is thrown.

     (This is implemented just like Java's `try'-`catch'.)

 - Function: dynamic-wind in-guard thunk out-guard
     All three arguments must be 0-argument procedures.  First calls
     IN-GUARD, then THUNK, then OUT-GUARD.  The result of the
     expression is that of THUNK.  If THUNK is exited abnormally (by
     throwing an exception or invoking a continuation), OUT-GUARD is
     called.

     If the continuation of the dynamic-wind is re-entered (which is
     not yet possible in Kawa), the IN-GUARD is called again.

     This function was added in R5RS.

Locations
=========

A "location" is a place where a value can be stored.  An "lvalue" is an
expression that refers to a location.  (The name "lvalue" refers to the
fact that the left operand of `set!' is an lvalue.)  The only kind of
lvalue in standard Scheme is a "variable".  Kawa also allows "computed
lvalues".  These are procedure calls used in "lvalue context", such as
the left operand of `set!'.

You can only use procedures that have an associated "setter".  In that
case, `(set! (f arg ...) value)' is equivalent to `((setter f) value
arg ...)' (It is possible the definition will change to `((setter f)
arg ... value)' if Guile goes for that.)  Currently, only a few
procedures have associated `setter's, and only builtin procedures
written in Java can have `setter's.

For example:
     (set! (car x) 10)
is equivalent to:
     (set-car! x 10)

Kawa also gives you access to locations as first-class values:

 - Syntax: location lvalue
     Returns a location object for the given LVALUE.  You can get its
     value (by applying it, as if it were a procedure), and you can set
     its value (by using `set!' on the application).  The LVALUE can be
     a local or global variable, or a procedure call using a procedure
     that has a `setter'.
          (define x 100)
          (define lx (location x))
          (set! (lx) (cons 1 2)) ;; set x to (1 . 2)
          (lx)  ;; returns (1 . 2)
          (define lc (location (car x)))
          (set! (lc) (+ 10 (lc)))
          ;; x is now (11 . 2)

 - Syntax: define-alias variable lvalue
     Define VARIABLE as an alias for LVALUE.  In other words, makes it
     so that `(location VARIABLE)' is equivalent to `(location LVALUE)'.
     This works both top-level and inside a function.

Some people mind find it helpful to think of a location as a settable
"thunk".  Others may find it useful to think of the `location' syntax
as similar to the C `&' operator; for the `*' indirection operator,
Kawa uses procedure application.

Eval and Environments
=====================

 - Function: eval expression [environment]
     `eval' evaluates EXPRESSION in the environment indicated by
     ENVIRONMENT.

     The default for ENVIRONMENT is the result of
     `(interaction-environment)'.

 - Function: null-environment
     This procedure returns an environment that contains no variable
     bindings, but contains (syntactic) bindings for all the syntactic
     keywords.

     The effect of assigning to a variable in this environment (such as
     `let') is undefined.

 - Function: scheme-report-environment version
     The VERSION must be an exact non-negative inetger corresponding to
     a version of one of the RevisedVERSION Reports on Scheme.  The
     procedure returns an environment that contains exactly the set of
     bindings specified in the corresponding report.

     This implementation supports VERSION that is 4 or 5.

     The effect of assigning to a variable in this environment (such as
     `car') is undefined.

 - Function: interaction-environment
     This procedure return an environment that contains
     implementation-defined bindings, as well as top-level user
     bindings.

 - Function: environment-bound? environment symbol
     Return true `#t' if there is a binding for SYMBOL in ENVIRONMENT;
     otherwise returns `#f'.

 - Syntax: fluid-let ((variable init) ...) body ...
     Evaluate the INIT expressions.  Then modify the dynamic bindings
     for the VARIABLES to the values of the INIT expressions, and
     evaluate the BODY expressions.  Return the result of the last
     expression in BODY.  Before returning, restore the original
     bindings.  The temporary bindings are only visible in the current
     thread, and its descendent threads.

Debugging
=========

 - Syntax: trace procedure
     Cause PROCEDURE to be "traced", that is debugging output will be
     written to the standard error port every time PROCEDURE is called,
     with the parameters and return value.

 - Syntax: untrace procedure
     Turn off tracing (debugging output) of PROCEDURE.

Threads
=======

There is a very preliminary interface to create parallel threads.  The
interface is similar to the standard `delay'/`force', where a thread is
basically the same as a promise, except that evaluation may be in
parallel.

So far, little or no effort has been made into making Kawa thread-safe.
There are no per-thread bindings, and the current input and output
parts are global.  That needs to change.

 - Syntax: future expression
     Creates a new thread that evaluates EXPRESSION.

 - Function: force thread
     The standard `force' function has generalized to also work on
     threads.  If waits for the thread's EXPRESSION to finish
     executing, and returns the result.

 - Function: sleep time
     Suspends the current thread for the specified time.  The TIME can
     be either a pure number (in secords), or a quantity whose unit is
     a time unit (such as `10s').

Processes
=========

 - Function: make-process command envp
     Creates a `<java.lang.Process>' object, using the specified
     COMMAND and ENVP.  The COMMAND is converted to an array of Java
     strings (that is an object that has type `<java.lang.String[]>'.
     It can be a Scheme vector or list (whose elements should be Java
     strings or Scheme strings);  a Java array of Java strings; or a
     Scheme string.  In the latter case, the command is converted using
     `command-parse'.  The ENVP is process environment;  it should be
     either a Java array of Java strings, or the special `#!null' value.

 - Function: system command
     Runs the specified COMMAND, and waits for it to finish.  Returns
     the return code from the command.  The return code is an integer,
     where 0 conventionally means successful completion.  The COMMAND
     can be any of the types handled by `make-process'.

 - Variable: command-parse
     The value of this variable should be a one-argument procedure.  It
     is used to convert a command from a Scheme string to a Java array
     of the constituent "words".  The default binding, on Unix-like
     systems, returns a new command to invoke `"/bin/sh" "-c"'
     concatenated with the command string; on non-Unix-systems, it is
     bound to `tokenize-string-to-string-array'.

 - Function: tokenize-string-to-string-array command
     Uses a `java.util.StringTokenizer' to parse the COMMAND string
     into an array of words.  This splits the COMMAND using spaces to
     delimit words; there is no special processing for quotes or other
     special characters.  (This is the same as what
     `java.lang.Runtime.exec(String)' does.)

Miscellaneous
=============

 - Function: scheme-implementation-version
     Returns the Kawa version number as a string.

 - Function: gentemp
     Returns a new (interned) symbol each time it is called.  The
     symbol names are implementation-dependent.

 - Syntax: defmacro name lambda-list form ...
     Defines an old-style macro a la Common Lisp, and installs `(lambda
     LAMBDA-LIST FORM ...)' as the expansion function for NAME.  When
     the translator sees an application of NAME, the expansion function
     is called with the rest of the application as the actual
     arguments.  The resulting object must be a Scheme source form that
     is futher processed (it may be repeatedly macro-expanded).

     If you define a macro with `defmacro', you (currently) cannot use
     the macro in the same compilation as the definition.  This
     restriction does not apply to macros defined by `define-syntax'.

 - Variable: command-line-arguments
     Any command-line arguments (following flags processed by Kawa
     itself) are assigned to the global variable
     `command-line-arguments', which is a vector of strings.

 - Variable: home-directory
     A string containing the home directory of the user.

 - Function: exit [code]
     Exits the Kawa interpreter, and ends the Java session.  The
     integer value CODE is returned to the operating system.  If CODE
     is not specified, zero is returned, indicating normal (non-error)
     termination.

 - Function: scheme-window [shared]
     Create a read-eval-print-loop in a new top-level window.  If
     SHARED is true, it uses the same environment as the current
     `(interaction-environment)';  if not (the default), a new
     top-level environment is created.

     You can create multiple top-level window that can co-exist.  They
     run in separate threads.

 - Function: apply proc [arg1 ...] args
     ARGS must be a sequence (list, vector, or string) or a primitive
     Java array.  (This is an extension over standard Scheme, which
     requires that ARGS be a list.)  Calls the PROC (which must be a
     procedure), using as arguments the ARG1... values plus all the
     elements of ARGS.

 - Syntax: constant-fold proc arg1 ...
     Same as `(PROC ARG1 ...)', unless PROC and all the following
     arguments are compile-time constants.  (That is:  They are either
     constant, or symbols that have a global binding and no lexical
     binding.)  In that case, PROC is applied to the arguments at
     compile-time, and the result replaces the `constant-fold' form.
     If the application raises an exception, a compile-time error is
     reported.  For example:
          (constant-fold vector 'a 'b 'c)
     is equivalent to `(quote #(a b c))', assuming `vector' has not
     been re-bound.

 - Syntax: when condition form...
     If CONDITION is true, evaluate each FORM in order, returning the
     value of the last one.

 - Syntax: unless condition form...
     If CONDITION is false, evaluate each FORM in order, returning the
     value of the last one.

 - Function: vector-append ARG...
     Creates a new vector, containing the elements from all the ARGs
     appended together.   Each ARG may be a vector or a list.

 - Function: instance? value type
     Returns `#t' iff VALUE is an instance of type TYPE.  (Undefined if
     TYPE is a primitive type, such as `<int>'.)

 - Function: as type value
     Converts or coerces VALUE to a value of type TYPE.  Throws an
     exception if that cannot be done.  Not supported for TYPE to be a
     primitive type such as `<int>'.

 - Syntax: synchronized object form ...
     Synchronize on the given OBJECT.  (This means getting an exclusive
     lock on the object, by acquiring its "monitor".)  Then execute the
     FORMs while holding the lock.  When the FORMs finish (normally or
     abnormally by throwing an exception), the lock is released.
     Returns the result of the last FORM.  Equivalent to the Java
     `synchronized' statement, except that it may return a result.

Types
*****

A "type" is a set of values, plus an associated set of operations valid
on those values.  Types are useful for catching errors
("type-checking"), documenting the programmer's intent, and to help the
compiler generate better code.  Types in some languages (such as C)
appear in programs, but do not exist at run-time.  In such languages,
all type-checking is done at compile-time.  Other languages (such as
standard Scheme) do not have types as such, but they have "predicates",
which allow you to check if a value is a member of certain sets;  also,
the primitive functions will check at run-time if the arguments are
members of the allowed sets.  Other languages, including Java and
Common Lisp, provide a combination:  Types may be used as specifiers to
guide the compiler, but also exist as actual run-time values.  In Java,
for each class, there is a corresponding `java.lang.Class' run-time
object, as well as an associated type (the set of values of that class,
plus its sub-classes, plus `null').

Kawa, like Java, has first-class types, that is types exist as objects
you can pass around at run-time.  For each Java type, there is a
corresponding Kawa type (but not necessarily vice versa).  It would be
nice if we could represent run-time type values using `java.lang.Class'
objects, but unfortunately that does not work very well.  One reason is
that we need to be able to refer to types and classes that do not exist
yet, because we are in the processing of compiling them.  Another
reason is that we want to be able to distinuish between different types
that are implemented using the same Java class.

Various Kawa constructs require or allow a type to be specified.  Those
specifications consist of "type expressions", which is evaluated to
yield a type value.  The current Kawa compiler is rather simple-minded,
and in many places only allows simple types that the compiler can
evaluate at compile-time.  More specifically, it only allows simple
"type names" that map to primitive Java types or java classes.

Standard Types
==============

These types are bound to identifiers having the form `<TYPENAME>'.
(This syntax and most of the names are as in RScheme.)

To find which Java classes these types map into, look in
`kawa/standard/Scheme.java'.

Note that the value of these variables are instances of
`gnu.bytecode.Type', not (as you might at first expect)
`java.lang.Class'.

 - Variable: <object>
     An arbitrary Scheme value - and hence an arbitrary Java object.

 - Variable: <number>
     The type of Scheme numbers.

 - Variable: <quantity>
     The type of quantities optionally with units.  This is a sub-type
     of `<number>'.

 - Variable: <complex>
     The type of complex numbers.  This is a sub-type of `<quantity>'.

 - Variable: <real>
     The type of real numbers.  This is a sub-type of `<complex>'.

 - Variable: <rational>
     The type of complex numbers.  This is a sub-type of `<real>'.

 - Variable: <integer>
     The type of Scheme integers.  This is a sub-type of `<rational>'.

 - Variable: <symbol>
     The type of Scheme symbols.

 - Variable: <keyword>
     The type of keyword values.  *Note Keywords::.

 - Variable: <list>
     The type of Scheme lists (pure and impure, including the empty
     list).

 - Variable: <pair>
     The type of Scheme pairs.  This is a sub-type of `<list>'.

 - Variable: <string>
     The type of (mutable) Scheme strings.  This is _not_ the same as
     (non-mutable) Java strings (which happen to be the same as
     `<symbol>').

 - Variable: <character>
     The type of Scheme character values.  This is a sub-type of
     `<object>', in contrast to type `<char>', which is the primitive
     Java `char' type.

 - Variable: <vector>
     The type of Scheme vectors.

 - Variable: <function>
     The type of Scheme procedures.

 - Variable: <input-port>
     The type of Scheme input ports.

 - Variable: <output-port>
     The type of Scheme output ports.

 - Variable: <String>
     This type name is a special case.  It specifies the class
     `<java.lang.String>' (just as `<symbol>' does).  However, coercing
     a value to `<String>' is done by invoking the `toString' method on
     the value to be coerced.  Thus it "works" for all objects.
     However, it does not work for `#!null'.  (Using the
     fully-qualified `<java.lang.String>' does work for `#!null', but
     does not work for non-`String' objects.)

More will be added later.

A type specifier can also be one of the primitive Java types.  The
numeric types `<long>', `<int>', `<short>', `<byte>', `<float>', and
`<double>' are converted from the corresponding Scheme number classes.
Similarly, `<char>' can be converted to and from Scheme characters.
The type `boolean' matches any object, and the result is `false' if and
only if the actual argument is `#f'.  The return type `<void>'
indicates that no value is returned.

A type specifier can also be a fully-qualified Java class name (for
example `<java.lang.StringBuffer>').  In that case, the actual argument
is cast at run time to the named class.  Also,
`<java.lang.StringBuffer[]>' represents an array of references to
`java.lang.StringBuffer' objects.

Declaring Types of Variables
============================

 - Syntax: let ((name [:: type] init) ...) body
     Declare new locals variables with the given NAME, initial value
     INIT, and optional type specification TYPE.  If TYPE is specified,
     then the expression INIT is evaluated, the result coerced to TYPE,
     and then assigned to the variable.  If TYPE is not specified, it
     defaults to `<object>'.

 - Syntax: let* ((name [:: type] init) ...) body

 - Syntax: letrec ((name [:: type] init) ...) body

Object, Classes and Modules
***************************

Kawa provides various ways to define, create, and access Java objects.
Here are the currently supported features.

The Kawa module system is based on the features of the Java class
system.

 - Syntax: this
     Returns the "this object" - the current instance of the current
     class.  The current implementation is incomplete, not robust, and
     not well defined.  However, it will have to do for now.  Note:
     "`this'" is a macro, not a variable, so you have to write it using
     parentheses: `(this)'.  A planned extension will allow an optional
     class specifier (needed for nested clases).

Records
=======

The Record package provides a facility for users to define their own
record data types.  Records are extensions of the class `Record'.
These procedures use the Java 1.1 reflection facility.

 - Function: make-record-type type-name field-names
     Returns a "record-type descriptor", a value representing a new data
     type disjoint from all others.  The TYPE-NAME argument must be a
     string, but is only used for debugging purposes (such as the
     printed representation of a record of the new type).  The
     FIELD-NAMES argument is a list of symbols naming the "fields" of a
     record of the new type.  It is an error if the list contains any
     duplicates.

 - Function: record-constructor rtd [field-names]
     Returns a procedure for constructing new members of the type
     represented by RTD.  The returned procedure accepts exactly as
     many arguments as there are symbols in the given list,
     FIELD-NAMES; these are used, in order, as the initial values of
     those fields in a new record, which is returned by the constructor
     procedure.  The values of any fields not named in that list are
     unspecified.  The FIELD-NAMES argument defaults to the list of
     field names in the call to `make-record-type' that created the
     type represented by RTD; if the FIELD-NAMES argument is provided,
     it is an error if it contains any duplicates or any symbols not in
     the default list.


 - Function: record-predicate rtd
     Returns a procedure for testing membership in the type represented
     by RTD.  The returned procedure accepts exactly one argument and
     returns a true value if the argument is a member of the indicated
     record type; it returns a false value otherwise.


 - Function: record-accessor rtd field-name
     Returns a procedure for reading the value of a particular field of
     a member of the type represented by RTD.  The returned procedure
     accepts exactly one argument which must be a record of the
     appropriate type; it returns the current value of the field named
     by the symbol FIELD-NAME in that record.  The symbol FIELD-NAME
     must be a member of the list of field-names in the call to
     `make-record-type' that created the type represented by RTD.

 - Function: record-modifier rtd field-name
     Returns a procedure for writing the value of a particular field of
     a member of the type represented by RTD.  The returned procedure
     accepts exactly two arguments: first, a record of the appropriate
     type, and second, an arbitrary Scheme value; it modifies the field
     named by the symbol FIELD-NAME in that record to contain the given
     value.  The returned value of the modifier procedure is
     unspecified.  The symbol FIELD-NAME must be a member of the list
     of field-names in the call to `make-record-type' that created the
     type represented by RTD.

 - Function: record? obj
     Returns a true value if OBJ is a record of any type and a false
     value otherwise.

 - Function: record-type-descriptor record
     Returns a record-type descriptor representing the type of the given
     record.  That is, for example, if the returned descriptor were
     passed to `record-predicate', the resulting predicate would return
     a true value when passed the given record.

 - Function: record-type-name rtd
     Returns the type-name associated with the type represented by rtd.
     The returned value is `eqv?' to the TYPE-NAME argument given in
     the call to `make-record-type' that created the type represented by
     RTD.

 - Function: record-type-field-names rtd
     Returns a list of the symbols naming the fields in members of the
     type represented by RTD.  The returned value is `equal?' to the
     field-names argument given in the call to `make-record-type' that
     created the type represented by RTD.

Mapping Scheme names to Java names
==================================

Programs use "names" to refer to various values and procedures.  The
definition of what is a "name" is different in different programming
languages.  A name in Scheme (and other Lisp-like languages) can be
principle contain any character (if using a suitable quoting
convention), but typically names consist of "words" (one or more
letters) separated by hyphens, such as `make-temporary-file'.  Digits
and some special symbols are also used.  Standard Scheme is
case-insensitive;  this means that the names `loop', `Loop', and `LOOP'
are all the same name.  Kawa is by default case-sensitive, but we
recommend that you avoid using upper-case letters as a general rule.

The Java language and the Java virtual machine uses names for classes,
variables, fields and methods.  These names can contain upper- and
lower-case letters, digits, and the special symbols `_' and `$'.

Given a name in a Scheme program, Kawa needs to map that name into a
valid Java name.  A typical Scheme name such as `make-temporary-file'
is not a valid Java name.  The convention for Java names is to use
"mixed-case" words, such as `makeTemporaryFile'.  So Kawa will
translate a Scheme-style name into a Java-style name.  The basic rule
is simple:  Hyphens are dropped, and a letter that follows a hyphen is
translated to its upper-case (actually "title-case") equivalent.
Otherwise, letters are translated as is.

Some special characters are handled specially.  A final `?' is replaced
by an _initial_ `is', with the following letter converted to titlecase.
Thus `number?' is converted to `isNumber' (which fits with Java
conventions), and `file-exists?' is converted to `isFileExists' (which
doesn't really).  The pair `->' is translated to `To', and if followed
by a letter, that is is converted to titlecase.  For example
`list->string' is translated to `listToString'.

Some symbols are mapped to a mnemonic sequence, starting with a
dollar-sign, followed by a two-character abbreviation.  For example,
the less-than symbol `<' is mangled as `$Ls'.  See the source code to
the `mangleName' method in the `gnu.expr.Compilation' class for the
full list.  Characters that do not have a mnemonic abbreviation are
mangled as `$' followed by a four-hex-digit unicode value.  For example
`Tamil vowel sign ai' is mangled as `$0bc8'.

Note that this mapping may map different Scheme names to the same Java
name.  For example `string?', `String?', `is-string', `is-String', and
`isString' are all mapped to the same Java identifier `isString'.  Code
that uses such "Java-clashing" names is _not_ supported.  There is very
partial support for renaming names in the case of a clash, and there
may be better support in the future.  However, some of the nice
features of Kawa depend on being able to map Scheme name to Java names
naturally, so we urge you to _not_ write code that "mixes" naming
conventions by using (say) the names `open-file' and `openFile' to name
two different objects.

Allocating objects
==================

 - Function: make type args ...
     Constructs a new object instance of the specified TYPE, which must
     be either a `java.lang.Class' or a `<gnu.bytecode.ClassType>'.

     The ARGS ... are passed to the constructor of the class type.  If
     there is no applicable constructor, and the ARGS ...  consist of a
     set of (KEYWORD,VALUE)-pairs, then the default constructor is
     called, and each (KEYWORD,VALUE)-pair is used to set the
     correspdong slot of the result, as if by: `(slot-set! RESULT
     KEYWORD VALUE)'.

     For example, the following are all equivalent:
          (set! p (make <java.awt.Point> 3 4))
          
          (set! p (make <java.awt.Point> y: 4 x: 3))
          
          (set! p (make <java.awt.Point>))
          (slot-set! p 'x 3)
          (set! (slot-ref p 'y) 4)


Calling Java methods from Scheme
================================

Kawa has both a low-level and a high-level "Foreign Function Interface",
which allows you to call any (virtual or static) Java method as if it
were a Scheme procedure.

 - Function: invoke-static class name args ...
     The CLASS can be a `<java.lang.Class>', a
     `<gnu.bytecode.ClassType>', or a `<symbol>' or `<string>' that
     names a Java class.  The NAME can be `<symbol>' or `<string>' that
     names one or more methods in the Java class.  The name is
     "mangled" (*note Mangling::) into a valid Java name.

     Any public methods (static or instance) in the specified CLASS (or
     its super-classes) that match "NAME" or "NAME$V" collectively form
     a generic procedure.  When the procedure is applied to the
     argument list, the most specific applicable method is chosen
     depending on the argument list;  that method is then called with
     the given arguments.  Iff the method is an instance method, the
     first actual argument is used as the `this' argument.  If there are
     no applicable methods (or no methods at all!), or there is no
     "best" method, `WrongType' is thrown.

     ("NAME$V" is used for procedures with `#!rest' or keyword args;
     the last argument must be an array type;  all the "extra" arguments
     must be compatible with the type of the array elements.)

     An example (derived from the Skij FAQ):
          (invoke-static <java.lang.Thread> 'sleep 100)

     The behavior of interpreted code and compiled code is not
     indentical, though you should get the same result either way
     unless you have designed the classes rather strangely.  The
     details will be nailed down later, but the basic idea is that the
     compiler will "inline" the `invoke-static' call if it can pick a
     single "best" matching method.

 - Function: invoke object name args ...
     The NAME can be `<symbol>' or `<string>' that names one or more
     methods in the Java class.  The name is "mangled" (*note
     Mangling::) into a valid Java name.

     Any public methods (static or instance) in the specified CLASS (or
     its super-classes) that match "NAME" or "NAME$V" collectively form
     a generic procedure.  When the procedure is applied to the
     argument list, the most specific applicable method is chosen
     depending on the argument list;  that method is then called with
     the given arguments.  Iff the method is an instance method, the
     OBJECT is used as the `this' argument; otherwise OBJECT is
     prepended to the ARGS list.  If there are no applicable methods
     (or no methods at all!), or there is no "best" method, `WrongType'
     is thrown.

     ("NAME$V" is used for procedures with `#!rest' or keyword args;
     the last argument must be an array type;  all the "extra" arguments
     must be compatible with the type of the array elements.)

     The behavior of interpreted code and compiled code is not
     indentical, though you should get the same result either way
     unless you have designed the classes rather strangely.  The
     details will be nailed down later, but the basic idea is that the
     compiler will "inline" the `invoke-static' call if it can pick a
     single "best" matching method.

 - Function: class-methods class name
     Return a generic function containing those methods of CLASS that
     match the name NAME, in the sense of `invoke-static'.  Same as:
          (lambda args (apply invoke-static (cons class (cons name args))))

Some examples using these functions are `vectors.scm' and
`characters.scm' the directory `kawa/lib' in the Kawa sources.

Accessing fields of Java objects
================================

Kawa has both a high-level interface and a low-level interface for
accessing the fields of Java objects and static fields.  The
lower-level interfaces are macros that return functions.  These
functions can be inlined, producing efficient code.  The higher-level
functions are less verbose and more convenient.  However, they can only
access public fields.

 - Function: field object fieldname
     Get the instance field with the given FIELDNAME from the given
     OBJECT.  Returns the value of the field, which must be public.
     This procedure has a `setter', and so can be used as the first
     operand to `set!'.

     The field name is "mangled" (*note Mangling::) into a valid Java
     name.  If there is no accessible field whose name is `"FIELDNAME"',
     we look for a no-argument method whose name is `"getFIELDNAME"'.


 - Function: static-field class fieldname
     Get the static field with the given FIELDNAME from the given
     CLASS.  Returns the value of the field, which must be public.
     This procedure has a `setter', and so can be used as the first
     operand to `set!'.

Examples:
     (static-field <java.lang.System> 'err)
     ;; Copy the car field of b into a.
     (set! (field a 'car) (field b 'car))

 - Function: slot-ref object fieldname
     A synonym for `(field OBJECT FIELDNAME)'.

 - Function: slot-set! object fieldname value
     A synonym for `(set! (field OBJECT FIELDNAME) VALUE)'.

Anonymous classes
=================

 - Syntax: object (supers ...) field-or-method-decl ...
     Returns a new instance of an anonymous (inner) class.
          FIELD-OR-METHOD = FIELD-DECL | METHOD-DECL
          FIELD-DECL = (FIELD-NAME [[FIELD-TYPE] FIELD-INIT])
          METHOD-DECL = ((METHOD-NAME FORMAL-ARGUMENTS) [RTYPE] BODY)

     Returns a new instance of a unique (anonymous) class.  The class
     inherits from the list of SUPERS, where at most one of the
     elements should be the base class being extended from, and the rest
     are interfaces.

     Each FIELD-DECL declares a public instance field.  If FIELD-TYPE
     is given, it specifies the type of the field.  If FIELD-INIT is
     given, it is an expression whose value becomes the initial value
     of the field.  The FIELD-INIT is evaluated at the same time as the
     `object' expression is evaluated, in a scope where all the
     FIELD-NAMEs are visible.

     Each METHOD-DECL declares a public non-static method, whose name
     is METHOD-NAME.  (If METHOD-NAME is not a valid Java method name,
     it is mapped to something reasonable.  For example `foo-bar?' is
     mapped to `isFooBar'.)  The types of the method arguments can be
     specified in the FORMAL-ARGUMENTS.  The return type can be
     specified by RTYPE, or is otherwise the type of the BODY.
     Currently, the FORMAL-ARGUMENTS cannot contain optional, rest, or
     keyword parameters.  (The plan is to allow optional parameters,
     implemented using multiple overloaded methods.)

     The scope of the BODY of a method includes the FIELD-DECLs of the
     object.  It does include the surrounding lexical scope.  It
     sort-of also includes the declared methods, but this is not
     working yet.

Modules and how they are compiled to classes
============================================

(The Kawa module system is under construction.  There are undoubtedly
bugs, not all of the planned features are implemented yet, and the
design may change as we get more experience with it.)

A "module" is a set of definitions that the module "exports", as well
as some "actions" (expressions evaluated for their side effect).  The
top-level forms in a Scheme source file compile a module; the source
file is the "module source".  When Kawa compiles the module source, the
result is the "module class".  Each exported definition is translated to
a public field in the module class.

There are two kinds of module class: A "static module" is a class (or
gets compiled to a class) all of whose public fields a static, and that
does not have a public constructor.  A JVM can only have a single
global instance of a static module.  (Static modules are not yet
implemented.)  An "instance module" has a public default constructor,
and usually has at least one non-static public field.  There can be
multiple instances of an instance module; each instance is called a
"module instance".  However, only a single instance of a module can be
"registered" in an environment, so in most cases there is only a single
instance of instance modules.  Registering an instance in an environment
means creating a binding mapping a magic name (derived from the class
name) to the instance.

In fact, any Java class class that has the properties of either an
instance module or a static module, is a module, and can be loaded or
imported as such;  the class need not have written using Scheme.

How a module becomes a class
----------------------------

If you want to just use a Scheme module as a module (i.e. `load' or
`require' it), you don't care how it gets translated into a module
class.  However, Kawa gives you some control over how this is done, and
you can use a Scheme module to define a class which you can use with
other Java classes.  This style of class definition is an alternative
to `define-class' [not yet implemented] which lets you define classes
and instances fairly conveniently.

The default name of the module class is the main part of the filename
of the Scheme source file (with directories and extensions sripped
off).  That can be overridden by the `-T' Kawa command-line flag.  The
package-prefix specified by the `-P' flag is prepended to give the
fully-qualified class name.

 - module-name: <name>
     Sets the name of the generated class, overriding the default.  If
     there is no `.' in the NAME, the package-prefix (specified by the
     `-P' Kawa command-line flag) is prepended.

The base class of the generated module class is unspecified; you cannot
count on it being more specific than `Object'.  However, you can
override it with `module-extends'.

 - module-extends: <class>
     Specifies that the class generated from the immediately surrounding
     module should extend (be a sub-class of) the class `<CLASS>'.

 - module-implements: <interface> ...
     Specifies that the class generated from the immediately surrounding
     module should implement the interfaces listed.

Note that the compiler does _not_ currently check that all the abstract
methods requires by the base class or implemented interfaces are
actually provided, and have the correct signatures.  This will
hopefully be fixed, but for now, if you are forgot a method, you will
probably get a verifier error

For each top-level non-private definition the compiler creates a
corresponding public field with a similar (mangled) name.  By default,
there is some indirection:  The value of the Scheme variable is not
that of the field itself.  Instead, the field is a
`gnu.mapping.Binding' object, and the value Scheme variable is defined
to be the value stored in the `Binding'.

If the Scheme definition defines a procedure (which is not re-assigned
in the module), then the compiler assumes the variable as bound as a
constant procedure.  The compiler generates one or more methods
corresponding to the body of the Scheme procedure. It also generates a
public field with the same name; the value of the field is an instance
of a subclass of `<gnu.mapping.Procedure>' which when applied will
execute the correct method (depending on the actual arguments).  The
field is used when the procedure used as a value (such as being passed
as an argument to `map'), but when the compiler is able to do so, it
will generate code to call the correct method directly.

You can control the signature of the generated method by declaring the
parameter types and the return type of the method.  See the applet
(*note Applet compilation::) example for how this can be done.  If the
procedures has optional parameters, then the compiler will generate
multiple methods, one for each argument list length.  (In rare cases
the default expression may be such that this is not possible, in which
case an "variable argument list" method is generated instead.  This
only happens when there is a nested scope _inside_ the default
expression, which is very contrived.)  If there are `#!keyword' or
`#!rest' arguments, the compiler generate a "variable argument list"
method.  This is a method whose last parameter is either an array or a
`<list>', and whose name has `$V' appended to indicate the last
parameter is a list.

A method will be static iff it doesn't need to reference non-static
fields or methods of the module instance.  In that case, the
corresponding field will also be static.   A future extension will
support for precise control over which components are static, and will
support creation of static modules (all of whose public fields are
static).  For now, you can only generate instance methods.

Top-leval macros (defined using either `define-syntax' or `defmacro')
create a field whose type is currently a sub-class of
`kawa.lang.Syntax';  this allows importing modules to detect that the
field is a macro and apply the macro at compile time.

Unfortuntely, the Java class verifier does not allow fields to have
arbitrary names.  Therefore, the name of a field that represents a
Scheme variable is "mangled" (*note Mangling::) into an acceptable Java
name.  The implementation can recover the original name of a field `X'
as `((gnu.mapping.Named) X).getName()' because all the standard
compiler-generate field types implemented the `Named' interface.

The top-level actions of a module will get compiled to a `run' method.
If there is an explicit `method-extends', then the module class will
also automatically implement `java.lang.Runnable'.  (Otherwise, the
class does not implement `Runnable', since in that case the `run'
method return an `Object' rather than `void'.  This will likely change.)

Requiring (importing) a module
------------------------------

You can import a module into the current namespace with `require'.

 - Syntax: require modulespec
     The MODULESPEC can be either a `<CLASSNAME>' or a `'FEATURENAME'.
     In either case the names exported by the specified module (class)
     are added to the current set of visible names.

     If MODULESPEC is `<CLASSNAME>' where CLASSNAME is an instance
     module (it has a public default constructor), and if no module
     instance for that class has been registered in the current
     environment, then a new instance is created and registered (using
     a "magic" identifier).  If the module class either inherits from
     `gnu.expr.ModuleBody' or implements `java.lang.Runnable' then the
     corresponding `run' method is executed.  (This is done _after_ the
     instance is registered so that cycles can be handled.)  These
     actions (creating, registering, and running the module instance)
     are done both at compile time and at run time, if necessary.

     All the public fields of the module class are then incorporated in
     the current set of local visible names in the current module.
     This is done at compile time - no new bindings are created at
     run-time (except for the magic binding used to register the module
     instance), and the imported bindings are private to the current
     module.  References to the imported bindings will be compiled as
     field references, using the module instance (except for static
     fields).

     If the MODULESPEC is `'FEATURENAME' then the FEATURENAME is looked
     up (at compile time) in the "feature table" which yields the
     implementing `<CLASSNAME>'.

For some examples, you may want to look in the `gnu/kawa/slib'
directory.

The Scheme-Java interface
*************************

Kawa has extensive features so you can work with Java objects and call
Java methods.

Scheme types in Java
====================

All Scheme values are implemented by sub-classes of `java.lang.Object'.

Scheme symbols are implemented using `java.lang.String'.  (Don't be
confused by the fact the Scheme sybols are represented using Java
Strings, while Scheme strings are represented by `kawa.lang.Scheme'.
It is just that the semantics of Java strings match Scheme symbols, but
do not match mutable Scheme strings.)  Interned symbols are presented
as interned Strings.  (Note that with JDK 1.1 string literals are
automatically interned.)

Scheme integers are implemented by `gnu.math.IntNum'.  Use the make
static function to create a new IntNum from an int or a long.  Use the
intValue or longValue methods to get the int or long value of an IntNum.

A Scheme "flonum" is implemented by `gnu.math.DFloNum'.

A Scheme pair is implemented by `kawa.lang.Pair'.

A Scheme vector is implemented by `kawa.lang.Vector'.

Scheme characters are implemented using `kawa.lang.Char'.

Scheme strings are implemented using `kawa.lang.FString'.

Scheme procedures are all sub-classes of `kawa.lang.Procedure'.
Normally each function (lambda expression) in the source code is
compiled to a separate sub-class of `Procedure'.  The "action" of a
`Procedure' is invoked by using one of the `apply*' methods:  `apply0',
`apply1', `apply2', `apply3', `apply4', or `applyN'.  Various sub-class
of `Procedure' provide defaults for the various `apply*' methods.  For
example, a `Procedure2' is used by 2-argument procedures.  The
`Procedure2' class provides implementations of all the `apply*' methods
_except_ `apply2', which must be provided by any class that extends
`Procedure2'.

Low-level Operations on Java Arrays
===================================

The following macros evaluate to procedures that can be used to
manipulate primitive Java array objects.  The compiler can inline each
to a single bytecode instruction (not counting type conversion).

 - Syntax: primitive-array-new element-type
     Evaluates to a one-argument procedure.  Applying the resulting
     procedure to an integer count allocates a new Java array of the
     specified length, and whose elements have type ELEMENT-TYPE.

 - Syntax: primitive-array-set element-type
     Evaluates to a three-argument procedure.  The first argument of
     the resulting procedure must be an array whose elements have type
     ELEMENT-TYPE;  the second argument is an index;  and the third
     argument is a value (coercible to ELEMENT-TYPE) which replaces the
     value specified by the index in the given array.

 - Syntax: primitive-array-get element-type
     Evaluates to a two-argument procedure.  The first argument of the
     resulting procedure must be an array whose elements have type
     ELEMENT-TYPE;  the second argument is an index.  Applying the
     procedure returns the element at the specified index.

 - Syntax: primitive-array-new element-type
     Evaluates to a one-argument procedure.  The argument of the
     resulting procedure must be an array whose elements have type
     ELEMENT-TYPE.  Applying the procedure returns the length of the
     array.

Low-level Method invocation
===========================

The following lower-level primitives require you to specify the
parameter and return types explicitly.  Type specifications are
currently required to be string literals or one of the standard types
(*note Standard Types::).

 - Syntax: primitive-constructor class (argtype ...)
     Returns a new anonymous procedure, which when called will create a
     new object of the specified class, and will then call the
     constructor matching the specified argument types.

 - Syntax: primitive-virtual-method class method rtype (argtype ...)
     Returns a new anonymous procedure, which when called will invoke
     the instance method whose name is the string METHOD in the class
     whose name is CLASS.

 - Syntax: primitive-static-method class method rtype (argtype ...)
     Returns a new anonymous procedure, which when called will invoke
     the static method whose name is the string METHOD in the class
     whose name is CLASS.

 - Syntax: primitive-interface-method interface method rtype (argtype
          ...)
     Returns a new anonymous procedure, which when called will invoke
     the matching method from the interface whose name is INTERFACE.

The macros return procedure values, just like `lambda'.  If the macros
are used directly as the procedure of a procedure call, then kawa can
inline the correct bytecodes to call the specified methods.  (Note also
that neither macro checks that there really is a method that matches
the specification.)  Otherwise, the Java reflection facility is used.

Low-level Operations on Object Fields
=====================================

The following macros evaluate to procedures that can be used to access
or change the fields of objects or static fields.  The compiler can
inline each to a single bytecode instruction (not counting type
conversion).

These macros are deprecated.  The `fields' and `static-field' functions
(*note Field operations::) are easier to use, more powerful, and just
as efficient.  (One exception is for `primitive-set-static'; while its
functionality can be expressed using `(set! (static-field ...) ...)',
that idiom is currently less efficient.)  Also, the high-level
functions currently do not provide access to private fields.

 - Syntax: primitive-get-field class fname ftype
     Use this to access a field named FNAME having type TYPE in class
     CLASS.  Evaluates to a new one-argument procedure, whose argument
     is a reference to an object of the specified CLASS.  Calling that
     procedure returns the value of the specified field.

 - Syntax: primitive-set-field class fname ftype
     Use this to change a field named FNAME having type TYPE in class
     CLASS.  Evaluates to a new two-argument procedure, whose first
     argument is a reference to an object of the specified CLASS, and
     the second argument is the new value.  Calling that procedure sets
     the field to the specified value.  (This macro's name does not end
     in a `!', because it does not actually set the field.  Rather, it
     returns a function for setting the field.)

 - Syntax: primitive-get-static class fname ftype
     Like `primitive-get-field', but used to access static fields.
     Returns a zero-argument function, which when called returns the
     value of the static field.

 - Syntax: primitive-set-static class fname ftype
     Like `primitive-set-field', but used to modify static fields.
     Returns a one-argument function, which when called sets the value
     of the static field to the argument.

Loading a ModuleBody
====================

The "top" class created by `kawa -C' (*note Files compilation::)
extends the `ModuleBody' class.  It is actually fairly easy to write a
`ModuleBody' by hand in Java, and you can then use the Scheme `load'
procedure to cause arbitrary actions.  Here is an example.  _(Note that
the details are subject to change!)_

     package MyDev;
     import kawa.lang.*;
     class MyDevFunc extends Procedure2
     {
       public Object apply2 (Object arg1, Object arg2)
       {
         ... stuff to control my device ...;
       }
     }
     
     public class MyDevice extends ModuleBody
     {
       public Object run (Environment env)
         throws WrongArguments, WrongType, GenericError, UnboundSymbol
       {
         ... initialize my device here ...;
     
         // Declare (handle-my-device x y) to call MyDevFunc.apply2 (x, y):
         env.define ("handle-my-device", new MyDevFunc ());
     
         // Return the void value (i.e. no value).
         return Interpreter.voidObject;
       }
     }

If this text is in the file `MyDev/MyDevice.java', and you compile it
with `javac', you will get `MyDev/MyDevice.class' and
`MyDev/MyDevFunc.class'.  Assuming the current directory is in your
`CLASSPATH', you can now do the following in Kawa:
     (load "MyDev/MyDevice.class")
or:
     (load "MyDev.MyDevice")

This will cause the actions in `MyDevice.run' to be executed.  The
current environment is passed in as the parameter `env'.  One of those
actions is to define the procedure `handle-my-device'.

Evaluating Scheme expressions from Java
=======================================

The following methods are recommended if you need to evaluate a Scheme
expression from a Java method.  (Some details (such as the `throws'
lists) may change.)

 - Static method: Object Scheme.eval (InPort PORT, Environment ENV)
     Read expressions from PORT, and evaluate them in the ENV
     environment, until end-of-file is reached.  Return the value of
     the last expression, or `Interpreter.voidObject' if there is no
     expression.

 - Static method: Object Scheme.eval (String STRING, Environment ENV)
     Read expressions from STRING, and evaluate them in the ENV
     environment, until the end of the string is reached.  Return the
     value of the last expression, or `Interpreter.voidObject' if there
     is no expression.

 - Static method: Object Scheme.eval (Object SEXPR, Environment ENV)
     The SEXPR is an S-expression (as may be returned by `read').
     Evaluate it in the ENV environment, and return the result.

For the `Environment' in most cases you could use
`Environment.current()'.  Before you start, you need to initialize the
global environment, which you can with
     Environment.setCurrent(new Scheme().getEnvironment());

Alternatively, rather than setting the global environment, you can use
this style:
     Scheme scm = new Scheme();
     Object x = scm.eval("(+ 3 2)");
     System.out.println(x);

Reporting Bugs and the Kawa Mailing List
****************************************

If you have a problem installing or using Kawa, send mail to
`kawa@sourceware.cygnus.com'

This mailing list is used for reporting bugs, patches, discussing
changes to Kawa, and announcing snapshots.  If you wish to subscribe,
send a blank message request to `kawa-subscribe@sourceware.cygnus.com'.
To unsubscribe, send a blank message to
`kawa-unsubscribe@sourcware.cygnus.com'.  (If your mail is forwarded,
send mail to the address following `mailto:' in the `List-Unsubscribe'
line in the messages you get form the list.)

Messages to the mailing list are now archived
(http://sourceware.cygnus.com/ml/kawa/).

License
*******

License for the Kawa software
=============================

The license for Kawa and the packages it depends on is a "modified Gnu
Public License".  You can find it in the file `COPYING' in the Kawa
sources, and also quoted here:.

     The Java classes (with related files and documentation) in these packages
     are copyright (C) 1996, 1997, 1998, 1999  Per Bothner.
     
     These classes are distributed in the hope that they will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     GNU General Public License for more details.
     
     These classes are free software.  You can use and re-distribute a class
     without restriction (in source or binary form) as long as you use a
     version has not been modified in any way from a version released
     by Per Bothner, Cygnus Solutions, or the Free Software Foundation.
     You may make and distribute a modified version, provided you follow
     the terms of the GNU General Public License; either version 2,
     or (at your option) any later version.

The file `COPYING' also contains a copy of the GNU General Public
License version 2.

People have asked what the Kawa license means in practice.  Informally,
you get to pick between these choices:
  1. Use Kawa as distributed by Per Bothner, Cygnus Solutions, or the
     Free Software Foundation (or their approved agents), with no
     modifications.  In that case, you can use Kawa for any purpose you
     like, and distribute your application with any license you like.
     (This basically gives you the same rights as a typical commercial
     royalty-free re-distribution license.)

  2. Obey the terms of the standard Gnu Public License.  (See
     `http://www.gnu.org/copyleft/gpl.html').  Informally, this means
     that if you distribute any application that is based on Kawa, you
     must also make available to all your recipients (customers) the
     source code for your entire application, giving them the
     modification and re-distribution rights they have under the GPL.
     In a Java context, I take "entire application" to mean all classes
     (and native code) that run in the same Java virtual machine,
     except for the Java runtime system itself (the virtual machine,
     low-level run-time system, and any classes in a `java' or `javax'
     package).

  3. If you need to make a change to Kawa, you can submit them to Per
     Bothner, and convince him to include them in future Kawa releases.

  4. You can negotiate some other (commercial) license with Per Bothner.

In general, if the license of Kawa or associated packages causes
difficulties, let me know.

Copyright for this manual
=========================

Here is the license for this manual:

Copyright (C) 1996, 1997, 1998, 1999 Per Bothner
Parts of this manual were derived from the SLIB manual, copyright (C)
1993-1998 Todd R. Eigenschink and Aubrey Jaffer.
Parts of this manual were derived from ISO/EIC 10179:1996(E) (Document
Style and Specifical Language) - unknown copyright.

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the author.

This manual has quoted from SRFI-6, which is Copyright (C) William D
Clinger (1999). All Rights Reserved.

The following notice applies to SRFI-6, which is quoted in this manual,
but it does not apply to the manual as a whole:

     This document and translations of it may be copied and furnished to
     others, and derivative works that comment on or otherwise explain
     it or assist in its implementation may be prepared, copied,
     published and distributed, in whole or in part, without
     restriction of any kind, provided that the above copyright notice
     and this paragraph are included on all such copies and derivative
     works. However, this document itself may not be modified in any
     way, such as by removing the copyright notice or references to the
     Scheme Request For Implementation process or editors, except as
     needed for the purpose of developing SRFIs in which case the
     procedures for copyrights defined in the SRFI process must be
     followed, or as required to translate it into languages other than
     English.

Index
*****

#!eof:
          See ``Special named constants''.
#!key:
          See ``Special named constants''.
#!null:
          See ``Special named constants''.
#!optional:
          See ``Special named constants''.
#!rest:
          See ``Special named constants''.
#!void:
          See ``Special named constants''.
<character>:
          See ``Standard Types''.
<class>:
          See ``Modules and how they are compiled to classes''.
<complex>:
          See ``Standard Types''.
<f32vector>:
          See ``Uniform vectors''.
<f64vector>:
          See ``Uniform vectors''.
<function>:
          See ``Standard Types''.
<input-port>:
          See ``Standard Types''.
<integer>:
          See ``Standard Types''.
<interface>:
          See ``Modules and how they are compiled to classes''.
<keyword>:
          See ``Standard Types''.
<list>:
          See ``Standard Types''.
<name>:
          See ``Modules and how they are compiled to classes''.
<number>:
          See ``Standard Types''.
<object>:
          See ``Standard Types''.
<output-port>:
          See ``Standard Types''.
<pair>:
          See ``Standard Types''.
<quantity>:
          See ``Standard Types''.
<rational>:
          See ``Standard Types''.
<real>:
          See ``Standard Types''.
<s16vector>:
          See ``Uniform vectors''.
<s32vector>:
          See ``Uniform vectors''.
<s64vector>:
          See ``Uniform vectors''.
<s8vector>:
          See ``Uniform vectors''.
<String>:
          See ``Standard Types''.
<string>:
          See ``Standard Types''.
<symbol>:
          See ``Standard Types''.
<u16vector>:
          See ``Uniform vectors''.
<u32vector>:
          See ``Uniform vectors''.
<u64vector>:
          See ``Uniform vectors''.
<u8vector>:
          See ``Uniform vectors''.
<vector>:
          See ``Standard Types''.
apply:
          See ``Miscellaneous''.
arithmetic-shift:
          See ``Logical Number Operations''.
as:
          See ``Miscellaneous''.
ash:
          See ``Logical Number Operations''.
bit-extract:
          See ``Logical Number Operations''.
bittest:
          See ``Logical Number Operations''.
call-with-input-string:
          See ``Ports''.
call-with-output-string:
          See ``Ports''.
call-with-values:
          See ``Multiple values''.
catch:
          See ``Signalling and recovering from exceptions''.
class-methods:
          See ``Calling Java methods from Scheme''.
command-line-arguments:
          See ``Miscellaneous''.
command-parse:
          See ``Processes''.
constant-fold:
          See ``Miscellaneous''.
copy-file:
          See ``File System Interface''.
create-directory:
          See ``File System Interface''.
default-prompter:
          See ``Ports''.
define-alias:
          See ``Locations''.
define-unit:
          See ``Quantities''.
defmacro:
          See ``Miscellaneous''.
delete-file:
          See ``File System Interface''.
dynamic-wind:
          See ``Signalling and recovering from exceptions''.
environment-bound?:
          See ``Eval and Environments''.
error:
          See ``Signalling and recovering from exceptions''.
eval:
          See ``Eval and Environments''.
exit:
          See ``Miscellaneous''.
f32vector:
          See ``Uniform vectors''.
f32vector->list:
          See ``Uniform vectors''.
f32vector-length:
          See ``Uniform vectors''.
f32vector-ref:
          See ``Uniform vectors''.
f32vector-set!:
          See ``Uniform vectors''.
f32vector?:
          See ``Uniform vectors''.
f64vector:
          See ``Uniform vectors''.
f64vector->list:
          See ``Uniform vectors''.
f64vector-length:
          See ``Uniform vectors''.
f64vector-ref:
          See ``Uniform vectors''.
f64vector-set!:
          See ``Uniform vectors''.
f64vector?:
          See ``Uniform vectors''.
field:
          See ``Accessing fields of Java objects''.
file-directory?:
          See ``File System Interface''.
file-exists?:
          See ``File System Interface''.
file-readable?:
          See ``File System Interface''.
file-writable?:
          See ``File System Interface''.
fluid-let:
          See ``Eval and Environments''.
force:
          See ``Threads''.
force-output:
          See ``Ports''.
format:
          See ``Formatted Output (Common-Lisp-style)''.
future:
          See ``Threads''.
gentemp:
          See ``Miscellaneous''.
get-output-string:
          See ``Ports''.
home-directory:
          See ``Miscellaneous''.
input-port-column-number:
          See ``Ports''.
input-port-line-number:
          See ``Ports''.
input-port-prompter:
          See ``Ports''.
input-port-read-state:
          See ``Ports''.
instance?:
          See ``Miscellaneous''.
integer-length:
          See ``Logical Number Operations''.
interaction-environment:
          See ``Eval and Environments''.
invoke:
          See ``Calling Java methods from Scheme''.
invoke-static:
          See ``Calling Java methods from Scheme''.
keyword->string:
          See ``Keywords''.
keyword?:
          See ``Keywords''.
let:
          See ``Declaring Types of Variables''.
let*:
          See ``Declaring Types of Variables''.
letrec:
          See ``Declaring Types of Variables''.
list->f32vector:
          See ``Uniform vectors''.
list->f64vector:
          See ``Uniform vectors''.
list->s16vector:
          See ``Uniform vectors''.
list->s32vector:
          See ``Uniform vectors''.
list->s64vector:
          See ``Uniform vectors''.
list->s8vector:
          See ``Uniform vectors''.
list->u16vector:
          See ``Uniform vectors''.
list->u32vector:
          See ``Uniform vectors''.
list->u64vector:
          See ``Uniform vectors''.
list->u8vector:
          See ``Uniform vectors''.
location:
          See ``Locations''.
logand:
          See ``Logical Number Operations''.
logbit?:
          See ``Logical Number Operations''.
logcount:
          See ``Logical Number Operations''.
logior:
          See ``Logical Number Operations''.
lognot:
          See ``Logical Number Operations''.
logop:
          See ``Logical Number Operations''.
logxor:
          See ``Logical Number Operations''.
make:
          See ``Allocating objects''.
make-f32vector:
          See ``Uniform vectors''.
make-f64vector:
          See ``Uniform vectors''.
make-process:
          See ``Processes''.
make-quantity:
          See ``Quantities''.
make-record-type:
          See ``Records''.
make-s16vector:
          See ``Uniform vectors''.
make-s32vector:
          See ``Uniform vectors''.
make-s64vector:
          See ``Uniform vectors''.
make-s8vector:
          See ``Uniform vectors''.
make-temporary-file:
          See ``File System Interface''.
make-u16vector:
          See ``Uniform vectors''.
make-u32vector:
          See ``Uniform vectors''.
make-u64vector:
          See ``Uniform vectors''.
make-u8vector:
          See ``Uniform vectors''.
null-environment:
          See ``Eval and Environments''.
object:
          See ``Anonymous classes''.
open-input-string:
          See ``Ports''.
open-output-string:
          See ``Ports''.
options:
          See ``Command-line arguments''.
parse-format:
          See ``Formatted Output (Common-Lisp-style)''.
port-char-encoding:
          See ``Ports''.
port-column:
          See ``Ports''.
port-line:
          See ``Ports''.
primitive-array-get:
          See ``Low-level Operations on Java Arrays''.
primitive-array-new:
          See ``Low-level Operations on Java Arrays''.
primitive-array-set:
          See ``Low-level Operations on Java Arrays''.
primitive-constructor:
          See ``Low-level Method invocation''.
primitive-get-field:
          See ``Low-level Operations on Object Fields''.
primitive-get-static:
          See ``Low-level Operations on Object Fields''.
primitive-interface-method:
          See ``Low-level Method invocation''.
primitive-set-field:
          See ``Low-level Operations on Object Fields''.
primitive-set-static:
          See ``Low-level Operations on Object Fields''.
primitive-static-method:
          See ``Low-level Method invocation''.
primitive-throw:
          See ``Signalling and recovering from exceptions''.
primitive-virtual-method:
          See ``Low-level Method invocation''.
quantity->number:
          See ``Quantities''.
quantity->unit:
          See ``Quantities''.
quantity?:
          See ``Quantities''.
read-line:
          See ``Ports''.
record-accessor:
          See ``Records''.
record-constructor:
          See ``Records''.
record-modifier:
          See ``Records''.
record-predicate:
          See ``Records''.
record-type-descriptor:
          See ``Records''.
record-type-field-names:
          See ``Records''.
record-type-name:
          See ``Records''.
record?:
          See ``Records''.
rename-file:
          See ``File System Interface''.
require:
          See ``Modules and how they are compiled to classes''.
s16vector:
          See ``Uniform vectors''.
s16vector->list:
          See ``Uniform vectors''.
s16vector-length:
          See ``Uniform vectors''.
s16vector-ref:
          See ``Uniform vectors''.
s16vector-set!:
          See ``Uniform vectors''.
s16vector?:
          See ``Uniform vectors''.
s32vector:
          See ``Uniform vectors''.
s32vector->list:
          See ``Uniform vectors''.
s32vector-length:
          See ``Uniform vectors''.
s32vector-ref:
          See ``Uniform vectors''.
s32vector-set!:
          See ``Uniform vectors''.
s32vector?:
          See ``Uniform vectors''.
s64vector:
          See ``Uniform vectors''.
s64vector->list:
          See ``Uniform vectors''.
s64vector-length:
          See ``Uniform vectors''.
s64vector-ref:
          See ``Uniform vectors''.
s64vector-set!:
          See ``Uniform vectors''.
s64vector?:
          See ``Uniform vectors''.
s8vector:
          See ``Uniform vectors''.
s8vector->list:
          See ``Uniform vectors''.
s8vector-length:
          See ``Uniform vectors''.
s8vector-ref:
          See ``Uniform vectors''.
s8vector-set!:
          See ``Uniform vectors''.
s8vector?:
          See ``Uniform vectors''.
scheme-implementation-version:
          See ``Miscellaneous''.
scheme-report-environment:
          See ``Eval and Environments''.
scheme-window:
          See ``Miscellaneous''.
Scheme.eval:
          See ``Evaluating Scheme expressions from Java''.
set-input-port-line-number!:
          See ``Ports''.
set-input-port-prompter!:
          See ``Ports''.
set-port-line!:
          See ``Ports''.
sleep:
          See ``Threads''.
slot-ref:
          See ``Accessing fields of Java objects''.
slot-set!:
          See ``Accessing fields of Java objects''.
static-field:
          See ``Accessing fields of Java objects''.
string->keyword:
          See ``Keywords''.
string-capitalize:
          See ``Strings''.
string-capitalize!:
          See ``Strings''.
string-downcase:
          See ``Strings''.
string-downcase!:
          See ``Strings''.
string-upcase:
          See ``Strings''.
string-upcase!:
          See ``Strings''.
symbol-read-case:
          See ``Ports''.
synchronized:
          See ``Miscellaneous''.
system:
          See ``Processes''.
system-tmpdir:
          See ``File System Interface''.
this:
          See ``Object, Classes and Modules''.
throw:
          See ``Signalling and recovering from exceptions''.
tokenize-string-to-string-array:
          See ``Processes''.
trace:
          See ``Debugging''.
try-catch:
          See ``Signalling and recovering from exceptions''.
try-finally:
          See ``Signalling and recovering from exceptions''.
u16vector:
          See ``Uniform vectors''.
u16vector->list:
          See ``Uniform vectors''.
u16vector-length:
          See ``Uniform vectors''.
u16vector-ref:
          See ``Uniform vectors''.
u16vector-set!:
          See ``Uniform vectors''.
u16vector?:
          See ``Uniform vectors''.
u32vector:
          See ``Uniform vectors''.
u32vector->list:
          See ``Uniform vectors''.
u32vector-length:
          See ``Uniform vectors''.
u32vector-ref:
          See ``Uniform vectors''.
u32vector-set!:
          See ``Uniform vectors''.
u32vector?:
          See ``Uniform vectors''.
u64vector:
          See ``Uniform vectors''.
u64vector->list:
          See ``Uniform vectors''.
u64vector-length:
          See ``Uniform vectors''.
u64vector-ref:
          See ``Uniform vectors''.
u64vector-set!:
          See ``Uniform vectors''.
u64vector?:
          See ``Uniform vectors''.
u8vector:
          See ``Uniform vectors''.
u8vector->list:
          See ``Uniform vectors''.
u8vector-length:
          See ``Uniform vectors''.
u8vector-ref:
          See ``Uniform vectors''.
u8vector-set!:
          See ``Uniform vectors''.
u8vector?:
          See ``Uniform vectors''.
unless:
          See ``Miscellaneous''.
untrace:
          See ``Debugging''.
values:
          See ``Multiple values''.
vector-append:
          See ``Miscellaneous''.
when:
          See ``Miscellaneous''.
