This is kawa.info, produced by makeinfo version 4.0f from
/home/bothner/Kawa/kawa/doc/kawa.texi.

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


File: kawa.info,  Node: Top,  Next: Features,  Prev: (dir),  Up: (dir)



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.98, updated 16 February 2002.

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

   The author of Kawa is Per Bothner (http://www.bothner.com/per/)
<per@bothner.com>.  Kawa 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 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://www.gnu.org/software/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.allaire.com/products/kawa/).

   The packages `gnu.bytecode'
(http://www.gnu.org/software/kawa/api/gnu/bytecode/package-summary.html),
`gnu.math'
(http://www.gnu.org/software/kawa/api/gnu/math/package-summary.html),
`gnu.lists'
(http://www.gnu.org/software/kawa/api/gnu/lists/package-summary.html),
`gnu.xml'
(http://www.gnu.org/software/kawa/api/gnu/xml/package-summary.html),
`gnu.expr'
(http://www.gnu.org/software/kawa/api/gnu/expr/package-summary.html),
`gnu.mapping'
(http://www.gnu.org/software/kawa/api/gnu/mapping/package-summary.html),
and `gnu.text'
(http://www.gnu.org/software/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://sources.redhat.com/kawa/papers/).

   Kawa is partly sponsored by Brainfood (http://www.brainfood.com/).

* Menu:

* Features::
* Getting Kawa::
* Installation::         Building and installing Kawa
* Running::              How to start up and run Kawa
* Restrictions::         Features of R5RS not implemented
* Compiling::            Compiling Scheme code to byte-code or an executable
* Extensions::           Various Kawa features not in standard Scheme
* Input-Output::         Input, output, and file handling
* Types::
* Objects Classes and Modules::
* Low-level functions::  The Scheme-Java interface
* XML tools::            Tools for working with XML and HTML
* KRL::                  The Kawa Report Language for generating XML/HTML
* Mailing lists::        Where to report bugs, discuss changes, etc
* Support::              Technical support for Kawa
* Projects::             Projects using Kawa
* License::
* Index::


File: kawa.info,  Node: Features,  Next: Getting Kawa,  Prev: Top,  Up: Top

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 uses Unicode internally, and uses the Java facilities to convert
files using other character encodings.

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

   Kawa provides a framework for implementing other progressing
languages, and comes with incomplete support for CommonLisp, Emacs
Lisp, and EcmaScript, and the draft XML Query language
(http://www.gnu.org/software/kawa/xquery/).

   Kawa is written in an object-oriented style.

   Kawa has builtin pretty-printer support, and fancy formatting.

   Kawa supports class-definition facilities, and separately-compiled
modules.

   Kawa implements the full numeric tower, including infinite-precision
rational numbers and complex numbers.  It also supports "quantities"
with units, such as `3cm'.

   You can optionally declare the types of variables.

   You can conveniently access Java objects, methods, fields, and
classes.

   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.


File: kawa.info,  Node: Getting Kawa,  Next: Installation,  Prev: Features,  Up: Top

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

   You can get Kawa sources and binaries from the Kawa ftp site
`ftp://ftp.gnu.org/pub/gnu/kawa/', or from a mirror site
(http://www.gnu.org/order/ftp.html).

   The latest release of the Kawa source code is
`ftp://ftp.gnu.org/pub/gnu/kawa/kawa-1.6.98.tar.gz'.  The same sources
are available as a zip file
`ftp://ftp.gnu.org/pub/gnu/kawa/kawa-1.6.98-src.zip'.

   A ready-to-run `.jar' archive of the pre-compiled classes is in
`ftp://ftp.gnu.org/pub/gnu/kawa/kawa-1.6.98.jar'.

   You can also check out the very latest version via anonymous cvs.
     cvs -d :pserver:anoncvs@sources.redhat.com:/cvs/kawa login
          (password is ``anoncvs'')
     cvs -d :pserver:anoncvs@sources.redhat.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://sources.redhat.com/cgi-bin/cvsweb.cgi/kawa/?cvsroot=kawa) via
cvsweb.


File: kawa.info,  Node: Installation,  Next: Running,  Prev: Getting Kawa,  Up: Top

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.

* Menu:

* Running Java::                Getting and running Java
* Binary distribution::         Installing and using the binary distribution
* Source distribution::         Installing and using the source distribution


File: kawa.info,  Node: Running Java,  Next: Binary distribution,  Up: Installation

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

   You will need a working Java system.  Kawa has been reported to work
with JDK 1.1, JDK 1.2, JDK 1.3, Kaffe, Symantec Cafe, J++, and GCJ.

   The discussion below assumes you are using the Java Developer's Kit
(JDK) from JavaSoft (Sun).  You can download free copies of JDK 1.3
(http://java.sun.com/j2se/1.3/) for various platforms.

   If you want to run Kawa on a Macintosh, see
`http://home.earthlink.net/%7Eathene/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'.  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
`PATH' thus:
     PATH=$JDK/bin:$PATH
     export PATH


File: kawa.info,  Node: Binary distribution,  Next: Source distribution,  Prev: Running Java,  Up: Installation

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.98.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.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.jar
     export CLASSPATH

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

   Then to run Kawa do:
     java kawa.repl

   To run Kawa in a fresh window, you can do:
     java kawa.repl -w


File: kawa.info,  Node: Source distribution,  Prev: Binary distribution,  Up: Installation

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

   The Kawa release normally comes as a gzip-compressed tar file named
`kawa-1.6.98.tar.gz'.  The same sources are available as a zip file
`kawa-1.6.98-src.zip'.  Two methods are supporting for compiling the
Kawa sources; choose whichever is most convenient for you.

   One method uses the traditional GNU `configure' script, followed by
running `make'.  This works well on Unix-like systems, such as
GNU/Linux.  It does not work well under Microsoft Windows. (Even when
using the CygWin Unix-emulation package there are some problems with
file paths.)

   The other method uses the `ant' command, a Java-based build system
released by Apache's Jakarta project.  This uses an `build.xml' file in
place of `Makefile's, and works on non-Unix systems such as Microsoft
Windows.  However, the `ant' method is relatively new, and does not
support all the features of the `configure'+`make' method.

Build Kawa using `configure' and `make'
---------------------------------------

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

   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 Swing installed, and want to use JEmacs (Emacs in Java),
also pass the `--with-swing' flag to `configure'.

   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/kawa.jar' is in the path:
     CLASSPATH=$PREFIX/share/java/kawa.jar
     export CLASSPATH
   This is done automatically if you use the `kawa' script.

Build Kawa using `ant'
----------------------

   Kawa now includes an Ant buildfile (`build.xml').  Ant
(http://jakarta.apache.org/ant/) is a part of the Apache Jakarta
project.  If you don't hava Ant installed, get it from
`http://jakarta.apache.org/builds/jakarta-ant/release/'.  The buildfile
should work with Ant 1.3, but has only been tested with 1.4.1.  The
build is entirely Java based and works equally well on *nix, Windows,
and presumably most any other operating system.

   Once Ant has been installed and configured (don't forget to set the
`JAVA_HOME', and `ANT_HOME' environment variables), you should be able
to change to the directory containing the `build.xml' file, and invoke
the `ant' command.  With the default settings, a successful build will
result in a `kawa-1.6.98.jar' in the current directory

   There are a few Ant "targets" of interest (they can be supplied on
the Ant command line):

`all'
     This is the default, it does `classes' and `jar'.

`classes'
     Compiles all the files into `*.class' files into the directory
     specified by the `build.dir' property.

`jar'
     Builds a jar into into the directory specified by the `dist.dir'
     property.

`runw'
     Run Kawa in a GUI window.

`clean'
     Deletes all files generated by the build, including the jar.

   There is not yet a `test' target for running the testsuite.

   The are various "properties" that control what `ant' does.  You can
override the on the command line or by editing the `build.properties'
file in the same directory as `build.xml'.  For example the `build.dir'
directory tells `ant' where to build temporary files, and where to
leave the resulting `.jar' file.  For example, to leave the generated
files in the sub-directory named `BUILD' do:
     ant -Dbuild.dir=BUILD
   A sample `build.properties' is provided and it contains comments
explaining many of the options.

   Here are a few general properties that help to customize your build:
`build.dir'
     Path to put the temporary files used for building.

`dist.dir'
     Path to put the resulting jar file.

`version.local'
     A suffix to add to the version label for your customized version.

`debug'
     Whether (true/false) the Javac "-g" option is enabled.

`optimize'
     Whether (true/false) the Javac "-O" option is enabled.

   Here are some Kawa-specific ones (all `true'/`false'):
`with-collections', `with-references', `with-awt', `with-swing',
`enable-jemacs', and `enable-servlet'> See the sample
`build.properties' for more information on these.

   If you change any of the build properties, you will generally want
to do an `ant clean' before building again as the build is often not
able to notice that kind of change.  In the case of changing a
directory path, you would want to do the `clean' before changing the
path.

   A special note for NetBeans users: For some reason the build-tools
target which compiles an Ant task won't compile with the classpath
provided by NetBeans.  You may do `ant build-tools' from the command
line outside of NetBeans, in which case you will not want to use the
`clean' target as that will delete the tool files as well.  You can use
the `clean-build' and/or `clean-dist' targets as appropriate.
Alternatively you can add `ant.jar' to the `build-tools' classpath by
copying or linking it into a `lib/ext' directory in Kawa's source
directory (the one containing the `build.xml' file).

Using the Jikes compiler
------------------------

   Jikes
(http://oss.software.ibm.com/developerworks/opensource/jikes/project/)
is a Java source-to-bytecode compiler that is much faster than Sun's
`javac'.  (Note that this only speeds up building Kawa from source, not
actually running Kawa.)  The instructions for using jikes are as above,
except that you need to specify Jikes at `configure' time, setting the
`JAVAC' environment variable.  If `jikes' is in your execution path, do:
     JAVAC=jikes ./configure

   You also need to inform Jikes where it should find the standard Java
classes (since Jikes is a compiler only).  For example:
     CLASSPATH=.:/opt/jdk1.3/jre/lib/rt.jar
     export CLASSPATH

Compiling Kawa to native code with GCJ
--------------------------------------

   The GNU Compiler for the Java(tm) Programming Language (GCJ
(http://gcc.gnu.org/java/)) is part of the GNU Compiler Collection (GCC
(http://gcc.gnu.org/)).  It can compile Java source or bytecode files
into native code on supported systems.  You need gcc-3.0 or later, and
only Intel x86-based Linux/GNU system have been tested with Kawa.

   First, get and install GCC 3.0.  Set `PREFIX' to where you want to
install GCJ, and configure it with these options:
     ./configure --enable-threads --enable-languages=c++,java --prefix $PREFIX
     make bootstrap
     make install
   Make sure `gcj' is in your path and refers to the newly-installed
version, and if needed, set `LD_LIBRARY_PATH' to point to the directory
where `libgcj.so' was installed:
     PATH=$PREFIX/bin:$PATH
     LD_LIBRARY_PATH=$PREFIX/lib
     export LD_LIBRARY_PATH

   To build Kawa, you need to specify `--with-gcj' to `configure' which
tells it to use GCJ.  Currently you also need to specify `--without-awt
--without-swing' because GCJ does not yet support AWT or Swing:
     ./configure --with-gcj --without-awt --without-swing --prefix $PREFIX
   Then as before:
     make
     make install

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

   Using the `ant' method is recommended for building Kawa under
Microsoft Windows.  You may get an error message "`Out of environment
space'."  See
`http://support.microsoft.com/support/kb/articles/Q230/2/05.ASP' for a
solution.  Alternatively you can run the class
`org.apache.tools.ant.Main' directly from the Ant jar.

   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://sources.redhat.com/cygwin/).  However, there are some
problems with filenames that make this more complicated than it should
be.  It should be possible to build Kawa under Cygwin using `gcj' as
descibed above.

   The `makekawa.bat' script in the Kawa source distribution can be
used for building Kawa under Windows, but it is no longer being
maintained.


File: kawa.info,  Node: Running,  Next: Restrictions,  Prev: Installation,  Up: Top

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).

* Menu:

* Options::      Command-line arguments
* Scripts::      Running Command Scripts
* New-Window::   Running a Command Interpreter in a new Window
* Exiting::      Exiting Kawa


File: kawa.info,  Node: Options,  Next: Scripts,  Prev: Running,  Up: Running

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'.

`--help'
     Prints out some help.

`--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, or you name a file with a known
     extension on the command-line.)

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

`--lisp'
`--clisp'
`--clisp'
`--commonlisp'
`--common-lisp'
     Set the default language to CommonLisp.  (The implementation is
     _very_ incomplete.)

`--krl'
     Set the default language to KRL.  See *Note KRL::.

`--brl'
     Set the default language to KRL, in BRL-compatibility mode.  See
     *Note KRL::.

`--xquery'
     Set the default language to the draft XML Query language.  See the
     Kawa-XQuery page (http://www.gnu.org/software/kawa/xquery/) for
     more information.

   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.

`--output-format FORMAT'
`--format FORMAT'
     Change the default output format to that specified by FORMAT.  See
     *Note Named output formats:: for more information and a list.

   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' `--applet', and
`--servlet' are used to compile a Scheme file; see *Note Files
compilation::.  The option `--connect PORTNUM' is only used by the
`kawa' front-end program.

   The following options are useful if you want to debug or understand
how Kawa works.
`--debug-dump-zip'
     Normally, when Kawa loads a soyrce file, or evaluates a
     non-trivial expression, it generates new internal Java classes but
     does not write them out.  This option asks it to write out
     generated classes in a `.zip' archive whose name has the prefix
     `kawa-zip-dump-'.

`--debug-print-expr'
     Kawa translates source language forms into an internal `Expression'
     data structure.  This option causes that data structure to be
     written out in a readable format to the standard output.

`--debug-print-final-expr'
     Similar to the previous option, but prints out the `Expression'
     after various transformations and optimizations have been done,
     and just before code generation.

   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.


File: kawa.info,  Node: Scripts,  Next: New-Window,  Prev: Options,  Up: Running

Running Command Scripts
=======================

   Unix-like systems support a mechanism where a "script" can specify a
programs that should execute it.  The convention is that the first line
of the file should start with the two characters `#!' followed by the
absolute path of the program that should process (interpret) the script.

   This is convention works well for script languages that use `#' to
indicate the start of a comment, since the interpreter will
automatically ignore the line specifying the interpreter filename.
Scheme, however, uses `#' for various special objects, and Kawa
specifically uses `#!' as a prefix for various *Note Special named
constants:: such as `#!optional'.

   Kawa does recognize the three-character sequence `#!/' at the
beginning of a file as special, and ignores it.  So you can specify
command interpreters, as long as you don't put a space between the `#!'
and the interpreter filename.  Here is an example:
     #!/usr/local/bin/kawa
     (format #t "The time is ~s~%" (make <java.util.Date>))

   If this file has the execute permission set and is in your `PATH',
then you can execute it just my naming it on command line.  The system
kernel will automatically execute `kawa', passing it the filename as an
argument.

   Note that the full path-name of the `kawa' interpreter must be
hard-wired into the script.  This means you may have to edit the script
depending on where Kawa is installed on your system.  Another possible
problem is that the interpreter must be an actual program, not a shell
script. Depending on how you configure and install Kawa, `kawa' can be
a real program or a script.  You can avoid both problems by the `env'
program, available on most modern Unix-like systems:

     #!/usr/bin/env kawa
     (format #t "The time is ~s~%" (make <java.util.Date>))


File: kawa.info,  Node: New-Window,  Next: Exiting,  Prev: Scripts,  Up: Running

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


File: kawa.info,  Node: Exiting,  Prev: New-Window,  Up: Running

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).


File: kawa.info,  Node: Restrictions,  Next: Compiling,  Prev: Running,  Up: Top

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.


File: kawa.info,  Node: Compiling,  Next: Extensions,  Prev: Restrictions,  Up: Top

Compiling Scheme code to byte-code or an executable
***************************************************

   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'.

   You can also compile your Scheme program to native code using GCJ.

* Menu:

* Archive compilation::         Compiling Scheme to an archive file
* Files compilation::           Compiling Scheme to a set of .class files
* Application compilation::     Compiling Scheme to a standalone application
* Applet compilation::          Compiling Scheme to an applet
* Compiling to executable::     Compiling Scheme to a native executable


File: kawa.info,  Node: Archive compilation,  Next: Files compilation,  Prev: Compiling,  Up: Compiling

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.


File: kawa.info,  Node: Files compilation,  Next: Application compilation,  Prev: Archive compilation,  Up: Compiling

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:
     kawa --main -C myprog.scm

   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::.

`--servlet'
     The resulting class implements `javax.servlet.http.HttpServlet',
     and can be used as an servlet in a servlet container like Tomcat.

`--module-static'
     If no `module-static' is specified, generate a static module (as
     if `(module-static #t)' were specified. *Note Module classes::.

   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


File: kawa.info,  Node: Application compilation,  Next: Applet compilation,  Prev: Files compilation,  Up: Compiling

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'.


File: kawa.info,  Node: Applet compilation,  Next: Compiling to executable,  Prev: Application compilation,  Up: Compiling

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>


File: kawa.info,  Node: Compiling to executable,  Prev: Applet compilation,  Up: Compiling

Compiling Scheme to a native executable
=======================================

   You can compile your Scheme program to native code using GCJ, as
long as you have built Kawa using GCJ.

   First, you need to compile the Scheme code to a set of `.class'
files; see *Note Files compilation::.
     kawa --main -C myprog.scm

   Then to create an executable `myprog' do:
     gckawa --main=myprog myprog*.class -o myprog

   The `gckawa' is a simple shell script that calls `gcj'.  The reason
for the wildcard in `myprog*.class' is that sometimes Kawa will
generate some helper classes in addition to `myprog.class'.  The
`--main' option tell `gcj' which class contains the `main' method it
should use.  The `-o' option names the resulting executable program.
The `-lkawa' option tells the linker it should link with the kawa
shared library, and the `-L$PREFIX/bin' option tells the linker where
it can find that library.


File: kawa.info,  Node: Extensions,  Next: Input-Output,  Prev: Compiling,  Up: Top

Extensions
**********

* Menu:

* Multiple values::
* Special named constants::
* Keywords::
* Procedures::
* Quantities::
* Logical Number Operations::
* Strings::
* Uniform vectors::
* Exceptions:: Signalling and recovering from exceptions
* Locations::
* Eval and Environments::
* Debugging::
* Threads::
* Processes::
* Miscellaneous::


File: kawa.info,  Node: Multiple values,  Next: Special named constants,  Prev: Extensions,  Up: 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.

 - Syntax: let-values ((formals expression) ...) body
     Each FORMALS should be a formal arguments list as for a `lambda',
     cf section 4.1.4 of the R5RS.

     The EXPRESSIONs are evaluated in the current environment, the
     variables of the FORMALS are bound to fresh locations, the return
     values of the EXPRESSIONs are stored in the variables, the BODY is
     evaluated in the extended environment, and the values of the last
     expression of BODY are returned. The BODY is a "tail body", cf
     section 3.5 of the R5RS.

     The matching of each FORMALS to values is as for the matching of
     FORMALS to arguments in a `ambda' expression, and it is an error
     for an EXPRESSION to return a number of values that does not match
     its corresponding FORMALS.
          (let-values ((a b . c) (values 1 2 3 4)))
            (list a b c))            --> (1 2 (3 4))
          
          (let ((a 'a) (b 'b) (x 'x) (y 'y))
            (let-values (((a b) (values x y))
                         ((x y) (values a b)))
              (list a b x y)))       --> (x y a b)

 - Syntax: let*-values ((formals expression) ...) body
     Each FORMALS should be a formal arguments list as for a `lambda'
     expression, cf section 4.1.4 of the R5RS.

     `let*-values' is similar to `let-values', but the bindings are
     performed sequentially from left to right, and the region of a
     binding indicated by (FORMALS EXPRESSION) is that part of the
     `let*-values' expression to the right of the binding. Thus the
     second binding is done in an environment in which the first
     binding is visible, and so on.
          (let ((a 'a) (b 'b) (x 'x) (y 'y))
            (let*-values (((a b) (values x y))
                          ((x y) (values a b)))
              (list a b x y)))       --> (x y x y)

 - Function: values-append arg1 ...
     The values resulting from evaluating each argument are appended
     together.


File: kawa.info,  Node: Special named constants,  Next: Keywords,  Prev: Multiple values,  Up: Extensions

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.


File: kawa.info,  Node: Keywords,  Next: Procedures,  Prev: Special named constants,  Up: Extensions

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 `#\:'.)

