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: Procedures,  Next: Quantities,  Prev: Keywords,  Up: Extensions

Procedures
==========

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

Procedure properties
--------------------

   You can associate arbitrary "properties" with any procedure.  Each
property is a (KEY, VALUE)-pair.  Usually the KEY is a symbol, but it
can be any object.

   The system uses certain internal properties: `'name' refers to the
name used when a procedure is printed; `'emacs-interactive' is used to
implement Emacs `interactive' specification; `'setter' will be (not yet
implemented) used to associate a `setter' prcedure.

 - Function: procedure-property proc key [default]
     Get the property value corresponding to the given KEY.  If PROC
     has no property with the given KEY, return DEFAULT (which defaults
     to `#f') instead.

 - Function: set-procedure-property! proc key value
     Associate the given VALUE with the KEY property of PROC.

   To change the print name of the standard `+' procedure (probably not
a good idea!), you could do:
     (set-procedure-property! + 'name 'PLUS)
   Note this _only_ changes the name property used for printing:
     + => #<procedure PLUS>
     (+ 2 3) => 5
     (PLUS 3 4) => ERROR

Generic (dynamically overloaded) procedures
-------------------------------------------

   A "generic procedure" is a collection of "method procedures".  (A
"method procedure" is not the same as a Java method, but the terms are
related.)  You can call a generic procedure, which selects the "closest
match" among the component method procedures:  I.e. the most specific
method procedure that is applicable give the actual arguments.

 - Function: make-procedure [keyword: value]... method...
     Create a generic procedure given the specific methods.  You can
     also specify property values for the result.

     The KEYWORDs specify how the arguments are used.  A `method:'
     keyword is optional and specifies that the following argument is a
     method.  A `name:' keyword specifies the name of the resulting
     procedure, when used for printing.  Unrecognized keywords are used
     to set the procedure properties of the result.
          (define plus10 (make-procedure foo: 33 name: 'Plus10
                                      method: (lambda (x y) (+ x y 10))
                                      method: (lambda () 10)))

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 [:: TYPE [INITIALIZER] | INITIALIZER [[::] TYPE]] )
     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))'.


File: kawa.info,  Node: Quantities,  Next: Logical Number Operations,  Prev: Procedures,  Up: Extensions

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 `4cm^2' (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-base-unit unit-name dimension
     Define UNIT-NAME as a base (primitive) unit, which is used to
     measure along the specified DIMENSION.
          (define-base-unit dollar "Money")

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


File: kawa.info,  Node: Logical Number Operations,  Next: Strings,  Prev: Quantities,  Up: Extensions

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


File: kawa.info,  Node: Strings,  Next: Uniform vectors,  Prev: Logical Number Operations,  Up: Extensions

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.


File: kawa.info,  Node: Uniform vectors,  Next: Exceptions,  Prev: Strings,  Up: Extensions

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: kawa.info,  Node: Exceptions,  Next: Locations,  Prev: Uniform vectors,  Up: Extensions

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 context of the given HANDLER specifications.
     Each HANDLER has the form:
          VAR TYPE EXP ...
     If an exception is thrown in BODY, the first HANDLER 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.


File: kawa.info,  Node: Locations,  Next: Eval and Environments,  Prev: Exceptions,  Up: Extensions

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


File: kawa.info,  Node: Eval and Environments,  Next: Debugging,  Prev: Locations,  Up: Extensions

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.


File: kawa.info,  Node: Debugging,  Next: Threads,  Prev: Eval and Environments,  Up: Extensions

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.


File: kawa.info,  Node: Threads,  Next: Processes,  Prev: Debugging,  Up: Extensions

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


File: kawa.info,  Node: Processes,  Next: Miscellaneous,  Prev: Threads,  Up: Extensions

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


File: kawa.info,  Node: Miscellaneous,  Prev: Processes,  Up: Extensions

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.

 - 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: reverse! list
     The result is a list consisting of the elements of LIST in reverse
     order.  No new pairs are allocated, instead the pairs of LIST are
     re-used, with `cdr' cells of LIST reversed in place.  Note that if
     LIST was pair, it becomes the last pair of the reversed result.


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


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

Input, output, and file handling
********************************

   Kawa has a number of useful tools for controlling input and output:

   A programmable reader.

   A powerful pretty-printer.

* Menu:

* Named output formats::
* Files:: File System Interface
* Ports::
* Format:: Formatted Output (Common-Lisp-style)


File: kawa.info,  Node: Named output formats,  Next: Files,  Up: Input-Output

   The `--output-format' (or `--format') command-line switch can be
used to override the default format for how values are printed on the
standard output.  This format is used for values printed by the
read-eval-print interactive interface.  It is also used to control how
values are printed when Kawa evaluates a file named on the command line
(using the `-f' flag or a just a script name).  (It also effects
applications compiled with the `--main' flag.)  It currently effects
how values are printed by a `load', though that may change.

   The default format depends on the current programming language.  For
Scheme, the default is `--scheme' for read-eval-print interaction, and
`--ignore' for files that are loaded.

   The formats currently supported include the following:
`scheme'
     Values are printed in a format matching the Scheme programming
     language, as if using `display'.  "Groups" or "elements" are
     written as lists.

`readable-scheme'
     Like `scheme', as if using `write': Values are generally printed
     in a way that they can be read back by a Scheme reader.  For
     example, strings have quotation marks, and character values are
     written like `#\A'.

`elisp'
     Values are printed in a format matching the Emacs Lisp programming
     language.  Mostly the same as `scheme'.

`readable-elisp'
     Like `elisp', but values are generally printed in a way that they
     can be read back by an Emacs Lisp reader.  For example, strings
     have quotation marks, and character values are written like `?A'.

`clisp'
`commonlisp'
     Values are printed in a format matching the Common Lisp
     programming language, as if written by `princ'.  Mostly the same
     as `scheme'.

`readable-clisp'
`readable-commonlisp'
     Like `clisp', but as if written by `prin1': values are generally
     printed in a way that they can be read back by a Common Lisp
     reader.  For example, strings have quotation marks, and character
     values are written like `#\A'.

`xml'
     Values are printed in XML format.  "Groups" or "elements" are
     written as using xml element syntax.  Plain characters (such as
     `<') are escaped (such as `&lt;').

`xhtml'
     Same as `xml', but follows the xhtml compatibility guidelines.

`html'
     Values are printed in HTML format.  Mostly same as `xml' format,
     but certain element without body, are written without a closing
     tag.   For example `<img>' is written without `</img>', which
     would be illegal for html, but required for xml.  Plain characters
     (such as `<') are not escaped inside `<script>' or `<style>'
     elements.

`cgi'
     The output should be a follow the CGI standards.  I.e. assume that
     this script is invoked by a web server as a CGI script/program,
     and that the output should start with some response header,
     followed by the actual response data.  To generate the response
     headers, use the `response-header' function.  If the
     `Content-type' response header has not been specified, and it is
     required by the CGI standard, Kawa will attempt to infer an
     appropriate `Content-ty[e' depending on the following value.

`ignore'
     Top-level values are ignored, instead of printed.


File: kawa.info,  Node: Files,  Next: Ports,  Prev: Named output formats,  Up: Input-Output

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


File: kawa.info,  Node: Ports,  Next: Format,  Prev: Files,  Up: Input-Output

Ports
=====

 - Function: current-error-port
     Return the port to which errors and warnings should be sent (the
     "standard error" in Unix and C terminology).

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

