This is kawa.info, produced by makeinfo version 4.5 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.7, updated 3 June 2003.

   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@milowski.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.  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
`http://www.gnu.org/software/kawa/internals.html'.

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

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

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

* 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::
* Overall Index::	 Index of functions, macros, concepts, and more.


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

   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.

   Kawa implements the following semi-standard SRFIs (Scheme Request
for Implementation (http://srfi.schemers.org/)):
   * SRFI 0: Feature-based conditional expansion construct, using
     `cond-expand' - *note Syntax and conditional compilation::.

   * SRFI 1: List Library
     (http://srfi.schemers.org/srfi-1/srfi-1.html), if `(require
     'list-lib)'.

   * SRFI 4: Homogeneous numeric vector datatypes - *note Uniform
     vectors::..

   * SRFI 6: Basic String Ports - *note Ports::.

   * SRFI 8: `receive': Binding to multiple values - *note Multiple
     values::.

   * SRFI 9: Defining Record Types, using `define-record-type' - *note
     Record types::.

   * SRFI 11: Syntax for receiving multiple values, using `let-values'
     and `let*-value' - *note Multiple values::.

   * SRFI 17: Generalized `set!' - *note Locations::.

   * SRFI 23: Error reporting mechanism, using `error' - *note
     Exceptions::.

   * SRFI 25: Multi-dimensional Array Primitives - *note Arrays::.

   * SRFI 26: Notation for Specializing Parameters without Currying -
     *note Procedures::.

   * SRFI 28: Basic Format Strings - *note Format::.

   * SRFI 30: Nested Multi-line Comments.


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.7.tar.gz'.  The same sources are
available as a zip file
`ftp://ftp.gnu.org/pub/gnu/kawa/kawa-1.7-src.zip'.

   A ready-to-run `.jar' archive of the pre-compiled classes is in
`ftp://ftp.gnu.org/pub/gnu/kawa/kawa-1.7.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 from 1.1 through 1.4.x, 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.4
(http://java.sun.com/j2se/1.4/) 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 depends on certain "Java 2" features, such as
collections.  If you have an older Java implementation (including JDK
1.1.x) you will need to get the source distribution.

   The binary release comes as a `.jar' archive `kawa-1.7.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 Windows you need to set `classpath' in a DOS console.  For
example:
     set classpath=\kawa\kawa-1.7.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.7.tar.gz'.  The same sources are available as a zip file
`kawa-1.7-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 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.7.tar.gz
     cd kawa-1.7

   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.

   If you use a very old or bare-bones Java implementation that not have
certain "Java 2" features (such as `java.util.List', `java.lang.ref',
or `ThreadLocal') then you need to convert the Kawa source-code so it
doesn't depend on those features.  You do this with the following
command:
     make select-java1
   Most people should not need to do this.  (You don't need to if you're
using GCJ, even though it doesn't implement all of Java 2.)  (If you
need to convert the code back to the default, do: `make select-java2'.)

   Then 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:
     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://ant.apache.org/bindownload.cgi'.  The buildfile should work
with Ant 1.3, and has been tested with 1.4.1. and 1.5.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 (you may need 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.7.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.  Version 3.3 or later of GCC is
recommended, and only Intel x86-based Linux/GNU system have been tested
with Kawa.

   First, get and install GCC 3.3.  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.


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-OR-URL'
     Kawa reads and evaluates expressions from the file named by
     FILENAME-OR-URL.  If the latter is `-', standard input is read
     (with no prompting).  Otherwise, it is equivalent to evaluating
     `(load "FILENAME-OR-URL")'.  The FILENAME-OR-URL is interpreted as
     a URL if it is absolute - it starts with a "URI scheme" like
     `http:'.

`-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/qexo/) for more
     information.

`--xslt'
     Set the default language to XSLT (XML Stylesheet Language
     Transformations).  (The implementation is _very_ incomplete.)  See
     the Kawa-XSLT page (http://www.gnu.org/software/qexo/xslt.html)
     for more information.

`--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 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' `--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
===================================

 - Function: compile-file source-file compiled-archive
     Compile the SOURCE-FILE, producing a `.zip' archive COMPILED-FILE.

     For example, to byte-compile a file `foo.scm' do:
          (compile-file "foo.scm" "foo")

     This will create `foo.zip', which contains byte-compiled "j-code".
     You can move this file around, without worrying about class paths.
     To load the compiled file, you can later `load' the named file, as
     in either `(load "foo")' or `(load "foo.zip")'.  This should have
     the same effect as loading `foo.scm', except you will get the
     faster 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 | --applet | --servlet] -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:

* Syntax and conditional compilation::
* Multiple values::
* Special named constants::
* Keywords::
* Procedures::
* Quantities::
* Logical Number Operations::
* Lists::
* Strings::
* Arrays::  Multi-dimensional Arrays
* Uniform vectors::
* Exceptions:: Signalling and recovering from exceptions
* Locations::
* Eval and Environments::
* Debugging::
* Threads::
* Processes::
* Miscellaneous::


File: kawa.info,  Node: Syntax and conditional compilation,  Next: Multiple values,  Prev: Extensions,  Up: Extensions

Syntax and conditional compilation
==================================

 - Syntax: define-syntax ..
     Pattern ...

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

 - Function: gentemp
     Returns a new (interned) symbol each time it is called.  The
     symbol names are implementation-dependent.  (This is not directly
     macro-related, but is often used in conjunction with `defmacro' to
     get a fresh unique identifier.)

 - Syntax: cond-expand cond-expand-clause* [(else
          command-or-definition*)]
          COND-EXPAND-CLAUSE ::= `(FEATURE-REQUIREMENT COMMAND-OR-DEFINITION*)'
          FEATURE-REQUIREMENT ::= FEATURE-IDENTIFIER
            | `(and FEATURE-REQUIREMENT*)'
            | `(or FEATURE-REQUIREMENT*)'
            | `(not FEATURE-REQUIREMENT)'
          FEATURE-IDENTIFIER ::= a symbol which is the name or alias of a SRFI

     The `cond-expand' form tests for the existence of features at
     macro-expansion time. It either expands into the body of one of its
     clauses or signals an error during syntactic processing.
     `cond-expand' expands into the body of the first clause whose
     feature requirement is currently satisfied; the `else' clause, if
     present, is selected if none of the previous clauses is selected.

     A feature requirement has an obvious interpretation as a logical
     formula, where the FEATURE-IDENTIFIER variables have meaning true
     if the feature corresponding to the feature identifier, as
     specified in the SRFI registry, is in effect at the location of
     the `cond-expand' form, and false otherwise. A feature requirement
     is satisfied if its formula is true under this interpretation.

     Examples:
          (cond-expand
              ((and srfi-1 srfi-10)
               (write 1))
              ((or srfi-1 srfi-10)
               (write 2))
              (else))

          (cond-expand
            (command-line
             (define (program-name) (car (argv)))))

     The second example assumes that `command-line' is an alias for some
     feature which gives access to command line arguments. Note that an
     error will be signaled at macro-expansion time if this feature is
     not present.

