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: Multiple values,  Next: Special named constants,  Prev: Syntax and conditional compilation,  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 `lambda' 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)

 - Syntax: receive formals expression body
     The FORMALS, EXPRESSION, and BODY are as described in R5RS.
     Specifically, FORMALS can have any of three forms:
    `(VARIABLE1 ... VARIABLEN)'
          The environment in which the receive-expression is evaluated
          is extended by binding VARIABLE1, ..., VARIABLEN to fresh
          locations. The EXPRESSION is evaluated, and its values are
          stored into those locations. (It is an error if EXPRESSION
          does not have exactly N values.)

    `VARIABLE'
          The environment in which the receive-expression is evaluated
          is extended by binding VARIABLE to a fresh location. The
          EXPRESSION is evaluated, its values are converted into a
          newly allocated list, and the list is stored in the location
          bound to VARIABLE.

    `(VARIABLE1 ... VARIABLEN . VARIABLEN+1)'
          The environment in which the receive-expression is evaluated
          is extended by binding VARIABLE1, ..., VARIABLEN+1 to fresh
          locations. The EXPRESSION is evaluated. Its first N values
          are stored into the locations bound to VARIABLE1 ...
          VARIABLEN. Any remaining values are converted into a newly
          allocated list, which is stored into the location bound to
          VARIABLEN+1 (It is an error if EXPRESSION does not have at
          least N values.)

     In any case, the expressions in BODY are evaluated sequentially in
     the extended environment. The results of the last expression in
     the body are the values of the receive-expression.

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


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

   As a matter of style, it is cleaner to use the `define-procedure'
form, as it is a more declarative interface.

 - Syntax: define-procedure name [propname: propvalue] ... method ...
     Defines NAME as a compound procedure consisting of the specified
     METHODs, with the associated properties.  Applying NAME select the
     "best" METHOD, and applies that.  See the following section on
     generic procedures.

     For example, the standard `vector-ref' procedure specifies one
     method, as well as the `setter' property:
          (define-procedure vector-ref
            setter: vector-set!
            (lambda ((vector :: <vector>) (k :: <int>))
              (invoke vector 'get k)))

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 given the actual arguments.

     *Note:* The current implementation of selecting the "best" method
     is not reliable if there is more than one method.  It can select
     depending on argument count, and it can select between primitive
     Java methods.  However, it cannot yet do what you probably hope
     for: select between different Scheme procedures based on parameter
     types.

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

 - Syntax: cut slot-or-expr slot-or-expr* [`<...>']
     where each SLOT-OR-EXPR is either an EXPRESSION or the literal
     symbol `<>'.

     It is frequently necessary to specialize some of the parameters of
     a multi-parameter procedure. For example, from the binary
     operation `cons' one might want to obtain the unary operation
     `(lambda (x) (cons 1 x))'.  This specialization of parameters is
     also known as "partial application", "operator section", or
     "projection".  The macro `cut' specializes some of the parameters
     of its first argument. The parameters that are to show up as
     formal variables of the result are indicated by the symbol `<>',
     pronouced as "slot".  In addition, the symbol `<...>', pronounced
     as "rest-slot", matches all residual arguments of a variable
     argument procedure.

     A `cut'-expression is transformed into a LAMBDA EXPRESSION with as
     many formal variables as there are slots in the list SLOT-OR-EXPR*.
     The body of the resulting LAMBDA EXPRESSION calls the first
     SLOT-OR-EXPR with arguments from the SLOT-OR-EXPR* list in the
     order they appear. In case there is a rest-slot symbol, the
     resulting procedure is also of variable arity, and the body calls
     the first SLOT-OR-EXPR with remaining arguments provided to the
     actual call of the specialized procedure.

     Here are some examples:
     `(cut cons (+ a 1) <>)' is the same as
     `(lambda (x2) (cons (+ a 1) x2))'
     `(cut list 1 <> 3 <> 5)' is the same as
     `(lambda (x2 x4) (list 1 x2 3 x4 5))'
     `(cut list)' is the same as `(lambda () (list))'
     `(cut list 1 <> 3 <...>)' is the same as
     `(lambda (x2 . xs) (apply list 1 x2 3 xs))'

     The first argument can also be a slot, as one should expect in
     Scheme:
     `(cut <> a b)' is the same as `(lambda (f) (f a b))'

 - Syntax: cute slot-or-expr slot-or-expr* [`<...>']
     The macro `cute' (a mnemonic for "cut with evaluated non-slots") is
     similar to `cut', but it evaluates the non-slot expressions at the
     time the procedure is specialized, not at the time the specialized
     procedure is called.

     For example:
     `(cute cons (+ a 1) <>)' is the same as
     `(let ((a1 (+ a 1))) (lambda (x2) (cons a1 x2)))'

     As you see from comparing this example with the first example
     above, the `cute'-variant will evaluate `(+ a 1)' once, while the
     `cut'-variant will evaluate it during every invocation of the
     resulting procedure.



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

Quantities and Numbers
======================

   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)

 - Function: quotient x y
     Generalized to arbitrary real numbers, using the definition:
     `(truncate (/ x y))'.

 - Function: remainder x y
     Generalized to arbitrary real numbers, using the definition: `(- x
     (* y (truncate (/ x y))))'.  If `y' is `0', the result is `x' -
     i.e. we take `(* 0 (quotient x 0))' to be `0'.  The result is
     inexact if either argument is inexact, even if `x' is exact and
     `y' is 0.

 - Function: modulo x y
     Generalized to arbitrary real numbers, using the definition: `(- x
     (* y (floor (/ x y))))'.  If `y' is `0', the result is `x'.  The
     result is inexact if either argument is inexact, even if `x' is
     exact and `y' is 0.


File: kawa.info,  Node: Logical Number Operations,  Next: Lists,  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: logtest 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: Lists,  Next: Strings,  Prev: Logical Number Operations,  Up: Extensions

Lists
=====

   The SRFI-1 List Library (http://srfi.schemers.org/srfi-1/srfi-1.html)
is available, though not enabled by default.  To use its functions you
must `(require 'list-lib)' or `(require 'srfi-1)'.
     (require 'list-lib)
     (iota 5 0 -0.5) ;; => (0.0 -0.5 -1.0 -1.5 -2.0)

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


File: kawa.info,  Node: Strings,  Next: Arrays,  Prev: Lists,  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: Arrays,  Next: Uniform vectors,  Prev: Strings,  Up: Extensions

Multi-dimensional Arrays
========================

   Arrays are heterogeneous data structures whose elements are indexed
by integer sequences of fixed length.  The length of a valid index
sequence is the rank or the number of dimensions of an array. The shape
of an array consists of bounds for each index.

   The lower bound B and the upper bound E of a dimension are exact
integers with `(<= B E)'. A valid index along the dimension is an exact
integer K that satisfies both `(<= B K)' and `(< K E)'.  The length of
the array along the dimension is the difference `(- E B)'.  The size of
an array is the product of the lengths of its dimensions.

   A shape is specified as an even number of exact integers. These are
alternately the lower and upper bounds for the dimensions of an array.

 - Function: array? obj
     Returns `#t' if OBJ is an array, otherwise returns `#f'.

 - Function: shape bound ...
     Returns a shape. The sequence BOUND ... must consist of an even
     number of exact integers that are pairwise not decreasing. Each
     pair gives the lower and upper bound of a dimension.  If the shape
     is used to specify the dimensions of an array and BOUND ... is the
     sequence B0 E0 ... BK EK ... of N pairs of bounds, then a valid
     index to the array is any sequence J0 ... JK ... of N exact
     integers where each JK satisfies `(<= BK JK)' and `(< JK EK)'.

     The shape of a D-dimensional array is a D × 2 array where the
     element at K 0 contains the lower bound for an index along
     dimension K and the element at K 1 contains the corresponding
     upper bound, where K satisfies `(<=  0 K)' and `(< K D)'.

 - Function: make-array shape
 - Function: make-array shape obj
     Returns a newly allocated array whose shape is given by SHAPE.  If
     OBJ is provided, then each element is initialized to it.
     Otherwise the initial contents of each element is unspecified.
     The array does not retain a reference to SHAPE.

 - Function: array shape obj ...
     Returns a new array whose shape is given by SHAPE and the initial
     contents of the elements are OBJ ... in row major order. The array
     does not retain a reference to SHAPE.

 - Function: array-rank array
     Returns the number of dimensions of ARRAY.
          (array-rank
            (make-array (shape 1 2 3 4)))
     Returns 2.

 - Function: array-start array k
     Returns the lower bound for the index along dimension K.

 - Function: array-end array k
     Returns the upper bound for the index along dimension K.

 - Function: array-ref array k ...
 - Function: array-ref array index
     Returns the contents of the element of ARRAY at index K ....  The
     sequence K ... must be a valid index to ARRAY.  In the second
     form, INDEX must be either a vector or a 0-based 1-dimensional
     array containing K ....
          (array-ref (array (shape 0 2 0 3)
                        'uno 'dos 'tres
                        'cuatro 'cinco 'seis)
             1 0)
     Returns `cuatro'.
          (let ((a (array (shape 4 7 1 2) 3 1 4)))
             (list (array-ref a 4 1)
                   (array-ref a (vector 5 1))
                   (array-ref a (array (shape 0 2)
                                   6 1))))
     Returns `(3 1 4)'.

 - Function: array-set! array k ... obj
 - Function: array-set! array index obj
     Stores OBJ in the element of ARRAY at index K ....  Returns the
     void value.  The sequence K ... must be a valid index to ARRAY.
     In the second form, INDEX must be either a vector or a 0-based
     1-dimensional array containing K ....

          (let ((a (make-array
                      (shape 4 5 4 5 4 5))))
             (array-set! a 4 4 4 "huuhkaja")
             (array-ref a 4 4 4))
     Returns `"huuhkaja"'.

 - Function: share-array array shape proc
     Returns a new array of SHAPE shape that shares elements of ARRAY
     through PROC. The procedure PROC must implement an affine function
     that returns indices of ARRAY when given indices of the array
     returned by `share-array'.  The array does not retain a reference
     to SHAPE.
          (define i_4
             (let* ((i (make-array
                          (shape 0 4 0 4)
                          0))
                    (d (share-array i
                          (shape 0 4)
                          (lambda (k)
                             (values k k)))))
                (do ((k 0 (+ k 1)))
                    ((= k 4))
                   (array-set! d k 1))
                i))

     Note: the affinity requirement for PROC means that each value must
     be a sum of multiples of the arguments passed to PROC, plus a
     constant.

     Implementation note: arrays have to maintain an internal index
     mapping from indices K1 ... KD to a single index into a backing
     vector; the composition of this mapping and PROC can be recognised
     as `(+ N0 (* N1 K1) ... (* ND KD))' by setting each index in turn
     to 1 and others to 0, and all to 0 for the constant term; the
     composition can then be compiled away, together with any
     complexity that the user introduced in their procedure.

   Multi-dimensional arrays are specified by SRFI-25
(http://srfi.schemers.org/srfi-25/srfi-25.html).  In Kawa, a
one-dimensional array whose lower bound is 0 is also a sequence.
Furthermore, if such an array is simple (not created `share-array') it
will be implemented using a `<vector>'.  Uniform vectors and strings
are also arrays in Kawa.  For example:
     (share-array
      (f64vector 1.0 2.0 3.0 4.0 5.0 6.0)
      (shape 0 2 0 3)
      (lambda (i j) (+ (* 2 i) j)))
   evaluates to a two-dimensionsal array of `<double>':
     #2a((1.0 2.0 3.0) (3.0 4.0 5.0))


File: kawa.info,  Node: Uniform vectors,  Next: Exceptions,  Prev: Arrays,  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.

Relationship with Java arrays
-----------------------------

   Each uniform array type is implemented as an "underlying Java array",
and a length field.  The underlying type is `byte[]' for `<u8vector>'
or `<s8vector>'; `short[]' for `<u16vector>' or `<u16vector>'; `int[]'
for `<u32vector>' or `<s32vector>'; `long[]' for `<u64vector>' or
`<s64vector>'; `<float[]' for `<f32vector>'; and `<double[]' for
`<f32vector>'.  The length field allows a uniform array to only use the
initial part of the underlying array.  (This can be used to support
Common Lisp's fill pointer feature.)  This also allows resizing a
uniform vector.  There is no Scheme function for this, but you can use
the `setSize' method:
     (invoke some-vector 'setSize 200)

   If you have a Java array, you can create a uniform vector sharing
with the Java array:
     (define arr :: <byte[]> ((primitive-array-new <byte>) 10))
     (define vec :: <u8vector> (make <u8vector> arr))
   At this point `vec' uses `arr' for its underlying storage, so
changes to one affect the other.  It `vec' is re-sized so it needs a
larger underlying array, then it will no longer use `arr'.


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.  This procedure is part of SRFI-23,
     and other Scheme implementations.

 - 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) arg
... value)' 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:
     ((setter car) x 10)
   which is equivalent to:
     (set-car! x 10)

 - Function: setter procedure
     Gets the "setter procedure" associated with a "getter procedure".
     Equivalent to `(procedure-property PROCEDURE 'setter)'.  By
     convention, a setter procedure takes the same parameters as the
     "getter" procedure, plus an extra parameter that is the new value
     to be stored in the location specified by the parameters.  The
     expectation is that following `((setter PROC) ARGS ... VALUE)' then
     the value of `(PROC ARGS ...)' will be VALUE.

     The `setter' of `setter' can be used to set the `setter' property.
     For example the Scheme prologue effectively does the following:
          (set! (setter vector-set) vector-set!)

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

 - Function: base-uri [node]
     If NODE is specified, returns the base-URI property of the NODE.
     If the NODE does not have the base-URI property, returns `#f'.
     (The XQuery version returns the empty sequence in that case.)

     In the zero-argument case, returns the "base URI" of the current
     context.  By default the base URI is the current working directory
     (as a URL).  While a source file is `load'ed, the base URI is
     temporarily set to the URL of the document.

 - Function: load path
     The PATH can be an (absolute) URL or a filename.

 - Function: load-relative path
     Same as `load', except that PATH is a URI that is relative to the
     context's current base URI.


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, only modest effort has been made into making Kawa
thread-safe.

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

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

