Go to the first, previous, next, last section, table of contents.
The multiple-value feature will be 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.
- Constant: #!optional
-
Special self-evaluating literal used in lambda parameter lists
before optional parameters.
- Constant: #!rest
-
Special self-evaluating literal used in lambda parameter lists
before the rest parameter.
- Constant: #!key
-
Special self-evaluating literal used in lambda parameter lists
before keyword parameters.
- Constant: #!eof
-
The end-of-file object.
Note that if the Scheme reader sees this literal at top-level,
it is returned literally. This is indistinguishable from
coming to the end of the input file. If you do not want to end reading,
but want the actual value of #!eof
, you should quote it.
- Constant: #!void
-
The void value. Same as
(values)
.
If this is the value of an expression in a read-eval-print loop,
nothing is printed.
- Constant: #!null
-
The Java
null
value. This is not really a Scheme value,
but is useful when interfacing to low-level Java code.
Keywords 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:
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
#\:
.)
Kawa borrows the extended formal argument list of DSSSL:
lambda-expression = (lambda (formal-arguments) body)
You can of course also use the extended format in a define
:
(define (name formal-arguments) body)
formal-arguments =
req-opt-args . rest-arg or:
req-opt-args rest-key-args
req-opt-args = req-arg* (#!optional opt-arg*)?
rest-key-args = (#!rest rest-arg)? (#!key key-arg*)?
opt-arg = variable | (variable initializer)
req-arg = variable
key-arg = variable | (variable initializer)
rest-arg = variable
When the procedure is applied to a list of actual arguments, the formal and
actual arguments are processed from left to right as follows:
-
The req-args are bound to actual arguments starting with the
first actual argument. It shall be an error if there are fewer actual
arguments then there are req-args.
-
Next the opt-args are bound to remaining actual arguemnts.
If there are fewer remaining actual arguments than there are
opt-args, then the remaining variables are bound
to the corresponding initializer, if one was specified, and
otherwise to
#f
. The initializer is evaluated in an
environment in which all the previous formal parameters have been bound.
-
If there is a rest-arg, it is bound to a list of all the
remaining actual arguments. These remaining actual arguments are also
eligible to be bound to keyword arguments. If there is no
rest-arg and there are no key-args, then it shall
be an error if there are any remaining actual arguments.
-
If
#!key
was specified, then there shall be an even number of
remaining actual arguments. These are interpreted as a series of pairs,
where the first member of each pair is a keyword specifying the argument name,
and the second is the corresponding value. It shall be an error if the first
member of a pair is not a keyword. It shall be an error if the argument name
is not the same as a variable in a key-args, unless there
is a rest-arg. If the same argument name occurs more than once
in the list of actual arguments, then the first value is used.
If there is no actual argument for a particular key-arg,
then the variable is bound
to the corresponding initializer, if one was specified, and
otherwise to #f
. The initializer is evaluated in an
environment in which all the previous formal parameters have been bound.
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))
.
The Record package provides a facility for user to define their own
record data types. A record type is implemented as Java Class
object, and records are extensions of the class Record
.
These procedures use the Java 1.1 reflection facility.
- Function: make-record-type type-name field-names
-
Returns a record-type descriptor, a value representing a new data
type disjoint from all others. The type-name argument must be a
string, but is only used for debugging purposes (such as the printed
representation of a record of the new type). The field-names
argument is a list of symbols naming the fields of a record of the
new type. It is an error if the list contains any duplicates.
In Kawa, returns a newly-created Class
object that extends
the Record
class. Each record field is implemented as
a public Java instance field.
- Function: record-constructor rtd [field-names]
-
Returns a procedure for constructing new members of the type represented
by rtd. The returned procedure accepts exactly as many arguments
as there are symbols in the given list, field-names; these are
used, in order, as the initial values of those fields in a new record,
which is returned by the constructor procedure. The values of any
fields not named in that list are unspecified. The field-names
argument defaults to the list of field names in the call to
make-record-type
that created the type represented by rtd;
if the field-names argument is provided, it is an error if it
contains any duplicates or any symbols not in the default list.
In Kawa, rtd may be any Class
that has a public default
constructor, as long as the field-names are public instance
fields. (The fields should have type Object
-- unless you
know what you are doing!)
- Function: record-predicate rtd
-
Returns a procedure for testing membership in the type represented by
rtd. The returned procedure accepts exactly one argument and
returns a true value if the argument is a member of the indicated record
type; it returns a false value otherwise.
In Kawa, the returned procedure checks if the argument is an instance
of rtd or one of its sub-classes.
- Function: record-accessor rtd field-name
-
Returns a procedure for reading the value of a particular field of a
member of the type represented by rtd. The returned procedure
accepts exactly one argument which must be a record of the appropriate
type; it returns the current value of the field named by the symbol
field-name in that record. The symbol field-name must be a
member of the list of field-names in the call to
make-record-type
that created the type represented by rtd. (In Kawa,
the field-name can be any public non-final Object field
of the Class
rtd.)
- Function: record-modifier rtd field-name
-
Returns a procedure for writing the value of a particular field of a
member of the type represented by rtd. The returned procedure
accepts exactly two arguments: first, a record of the appropriate type,
and second, an arbitrary Scheme value; it modifies the field named by
the symbol field-name in that record to contain the given value.
The returned value of the modifier procedure is unspecified. The symbol
field-name must be a member of the list of field-names in the call
to
make-record-type
that created the type represented by
rtd. (In Kawa,
the field-name can be any public non-final Object field
of the Class
rtd.)
- Function: record? obj
-
Returns a true value if obj is a record of any type and a false
value otherwise.
In Kawa, this is true if obj is an instance of kawa.lang.Record
.
- Function: record-type-descriptor record
-
Returns a record-type descriptor representing the type of the given
record. That is, for example, if the returned descriptor were passed to
record-predicate
, the resulting predicate would return a true
value when passed the given record. In Kawa, record may be any object,
and the value returned is the class of the object.
- Function: record-type-name rtd
-
Returns the type-name associated with the type represented by rtd. The
returned value is
eqv?
to the type-name argument given in
the call to make-record-type
that created the type represented by
rtd.
- Function: record-type-field-names rtd
-
Returns a list of the symbols naming the fields in members of the type
represented by rtd. The returned value is
equal?
to the
field-names argument given in the call to make-record-type
that
created the type represented by rtd.
- 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: 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: 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.
- Function: set-input-port-line-number! port num
-
Set line number of the current line of port to num.
- 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.
- 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)))
- Function: catch key thunk handler
-
Invoke thunk in the dynamic context of handler for
exceptions matching key. If thunk throws to the symbol key,
then handler is invoked this way:
(handler key args ...)
key may be a symbol. The thunk takes no
arguments. If thunk returns normally, that is the return value of
catch
.
Handler is invoked outside the scope of its own catch
. If
handler again throws to the same key, a new handler from further
up the call chain is invoked.
If the key is #t
, then a throw to any symbol will match
this call to catch
.
- Function: throw key &rest args ...
-
Invoke the catch form matching key, passing args to the
handler.
If the key is a symbol it will match catches of the same
symbol or of #t.
If there is no handler at all, an error is signaled.
- procedure: error message args ...
-
Raise an error with key
misc-error
and a message constructed by
displaying msg and writing args.
This normally prints a stack trace, and brings you back to
the top level, or exits kawa if you are not running interactively.
- Function: primitive-throw exception
-
Throws the exception, which must be an instance of a sub-class
of
<java.lang.Throwable>
.
- Syntax: try-finally body handler
-
Evaluate body, and return its result.
However, before it returns, evaluate handler.
Even if body returns abnormally (by throwing an exception),
handler is evaluated.
(This is implemented just like Java's try
-finally
.)
- Syntax: try-catch body handler ...
-
Evaluate body, in the conect of the given handler-specs.
Each handler has the form:
var type exp ...
If an exception is thrown in body, the first handle-spec
is selected such that the thrown exception is an instance of
the handler's type. If no handler is selected,
the exception is propagated through the dynamic execution context
until a matching handler is found. (If no matching handler
is found, then an error message is printed, and the computation terminated.)
Once a handler is selected,
the var is bound to the thrown exception, and the exp in
the handler are executed. The result of the try-catch
is the result of body if no exception is thrown, or the
value of the last exp in the selected handler if an
exception is thrown.
(This is implemented just like Java's try
-catch
.)
- Function: dynamic-wind in-guard thunk out-guard
-
All three arguments must be 0-argument procedures.
First calls in-guard, then thunk, then out-guard.
The result of the expression is that of thunk.
If thunk is exited abnormally (by throwing an exception or
invoking a continuation), out-guard is called.
If the continuation of the dynamic-wind is re-entered (which
is not yet possible in Kawa), the in-guard is called again.
This function will be in R5RS.
- 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.
As a super-class of numbers, Kawa also provides quantities.
A quantity is a product of a unit and a pure number.
The number part can be an arbitrary complex number.
The unit is a product of integer powers of base units,
such as meter or second.
Kawa quantities are a generalization of the quantities in DSSSL,
which only has length-derived quantities.
The precise syntax of quantity literals may change,
but some examples are 10pt
(10 points), 5s
(5 seconds),
and 4cm2
(4 square centimeters).
- Function: quantity? object
-
True iff object is a quantity. Note that all numbers are
quantities, but not the other way round.
- Function: quantity->number q
-
Returns the pure number part of the quantity q, relative to
primitive (base) units.
If q is a number, returns q.
If q is a unit, yields the magitude of q relative to base units.
- Function: quantity->unit q
-
Returns the unit of the quantity q.
If q is a number, returns the empty unit.
- Function: make-quantity x unit
-
Returns the product of x (a pure number) and unit.
You can specify a string instead of unit, such as
"cm"
or "s"
(seconds).
- Syntax: define-unit unit-name expression
-
Define unit-name as a unit (that can be used in literals)
equal to the quantity expression.
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
).
Kawa has first-class types, that you can use in various ways.
Currently, these are mainly useful for interfacing with primitive Java methods
(such as primitive-virtual-function
, but they will be useful
for other purposes (such as declarating variables) later.
These types are bound to identifiers having the form <TYPENAME>
.
(This syntax and most of the names are as in RScheme.)
To find which Java classes these types map into, look in
kawa/lang/PrimProcedure.java
.
Note that the value of these variables are instances
of gnu.bytecode.Type
,
not (as you might at first expect) java.lang.Class
.
- Variable: <object>
-
An arbitrary Scheme value - and hence an arbitrary Java object.
- Variable: <number>
-
The type of Scheme numbers.
- Variable: <integer>
-
The type of Scheme integers.
- Variable: <symbol>
-
The type of Scheme symbols.
- Variable: <keyword>
-
The type of keyword values. See section Keywords.
- Variable: <list>
-
The type of Scheme lists (pure and impure, including the empty list).
- Variable: <pair>
-
The type of Scheme pairs. This is a sub-type of
<list>
.
- Variable: <string>
-
The type of (mutable) Scheme strings.
This is not the same as (non-mutable) Java strings
(which happen to be the same as
<symbol>
).
- Variable: <vector>
-
The type of Scheme vectors.
- Variable: <function>
-
The type of Scheme procedures.
- Variable: <input-port>
-
The type of Scheme input ports.
- Variable: <output-port>
-
The type of Scheme output ports.
More will be added later.
In addition, any Java type can be named using this syntax.
For example <java.lang.StringBuffer[]>
represents
an array of references to java.lang.StringBuffer
objects.
- 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.)
- Function: scheme-implementation-version
-
Returns the Kawa version number as a string.
- Function: gentemp
-
Returns a new (interned) symbol each time it is called.
The symbol names are implementation-dependent.
- Syntax: defmacro name lambda-list form ...
-
Defines an old-style macro a la Common Lisp,
and installs
(lambda lambda-list form ...)
as the expansion function for name.
When the translator sees an application of name,
the expansion function is called with the rest of the application
as the actual arguments. The resulting object must be a Scheme
source form that is futher processed (it may be repeatedly macro-expanded).
If you define a macro with defmacro
, you (currently) cannot use
the macro in the same compilation as the definition.
This restriction does not apply to macros defined by define-syntax
.
- Variable: command-line-arguments
-
Any command-line arguments (following flags processed by Kawa itself)
are assigned to the global variable `command-line-arguments',
which is a vector of strings.
- Variable: home-directory
-
A string containing the home directory of the user.
- Function: exit [code]
-
Exits the Kawa interpreter, and ends the Java session.
The integer value code is returned to the operating
system. If code is not specified, zero is returned,
indicating normal (non-error) termination.
- Function: scheme-window [shared]
-
Create a read-eval-print-loop in a new top-level window.
If shared is true, it uses the same environment as the
current
(interaction-environment)
; if not (the default),
a new top-level environment is created.
You can create multiple top-level window that can co-exist.
They run in separate threads.
- Function: apply proc [arg1 ...] args
-
Args must be a sequence (list, vector, or string) or a
primitive Java array.
(This is an extension over standard Scheme, which requires that
args be a list.)
Calls the proc (which must be a procedure), using as arguments
the arg1... values plus all the elements of args.
- Syntax: constant-fold proc arg1 ...
-
Same as
(proc arg1 ...)
, unless proc and
all the following arguments are compile-time constants.
(That is: They are either constant, or symbols that have a global
binding and no lexical binding.) In that case, proc
is applied to the arguments at compile-time, and the result replaces
the constant-fold
form. If the application raises an exception,
a compile-time error is reported.
For example:
(constant-fold vector 'a 'b 'c)
is equivalent to (quote #(a b c))
, assuming vector
has not been re-bound.
- Syntax: when condition form...
-
If condition is true, evaluate each form in order,
returning the value of the last one.
- Syntax: unless condition form...
-
If condition is false, evaluate each form in order,
returning the value of the last one.
- Function: vector-append arg...
-
Creates a new vector, containing the elements from all the args
appended together. Each arg may be a vector or a list.
- Function: instance? value type
-
Returns
#t
iff value is an instance of type type.
(Undefined if type is a primitive type, such as <int>
.)
- Function: as type value
-
Converts or coerces value to a value of type type.
Throws an exception if that cannot be done.
Not supported for type to be a primitive type such as
<int>
.
Go to the first, previous, next, last section, table of contents.