You can import a module into the current namespace with
require. This adds the exported bindings (or a subset of them) to the
current lexical scope. It follows that these bindings (which are said
to be imported) are determined at compile-time.
importdeclaration provides a way to import identifiers exported by a library (module). Each
import-setnames a set of bindings from a library and possibly specifies local names for the imported bindings.
library-referenceis mapped to a class name by concatenating all the identifiers, separated by dots. For example:(import (gnu kawa slib srfi37))
is equivalent to:(import gnu.kawa.slib.srfi37)
as well as to:(require gnu.kawa.slib.srfi37)
By default, all of an imported library’s exported bindings are made visible within an importing library using the names given to the bindings by the imported library. The precise set of bindings to be imported and the names of those bindings can be adjusted with the
renameforms as described below.
onlyform produces a subset of the bindings from another
import-set, including only the listed
identifiers. The included
identifiers must be in the original
import-set. If a
rename-pairis used, then the
must be in the original
import-set, and is renamed to
. For example:
identifier2(import (only (kawa example) A (B1 B2) C (D1 D2)))
is equivalent to:(import (rename (only (kawa example) A B1 C D1) (B1 B2) (D1 D2)))
D1must exist in the library
(kawa example). The bindings are accessible using the names
exceptform produces a subset of the bindings from another
import-set, including all but the listed
identifiers. All of the excluded
identifiers must be in the original
prefixform adds the
identifierprefix to each name from another
removes the bindings for
to form an intermediate
import-set, then adds the bindings back for the corresponding
to form the final
must be in the original
identifier2 must not be in the intermediate
import-set, and the
identifier2s must be distinct.
classform is a convenient way to define abbreviations for class names; it may be more convenient than
class-prefixis concatenated with each
identifier(with a period in between) to produce a classname. Each
identifierbecomes an alias for the class. For example:(import (class java.util Map (HashMap HMap)))
Mapas an alias for
HMapas an alias for
java.util.HashMap. (You can think of the
classform as similar to a
onlyform, where the
class-prefixnames a special kind of library represented of a Java package, and whose exported bindings are the classes in the package.)
You can combine the
prefix, though only
prefixis likely to be useful. For example:(import (prefix (class java.lang Long Short) jl-))
is equivalent to(import (class java.lang (Long jl-Long) (Short jl-Short)))
which is equivalent to:(define-private-alias jl-Short java.lang.Short) (define-private-alias jl-Long java.lang.Long)
Search for a matching module (class), and add the names exported by that module to the current set of visible names. Normally, the module is specified using
requirehas similar functionality as
import, but with a different syntax, and without options like
is specified then that is used to locate the source file for the module, and if necessary, compile it.
'is specified then the
featurenameis looked up (at compile time) in the "feature table" which yields the implementing
'is available. A following
cond-expandin this scope will match
similar to the same-named macros in SLib, Emacs, and Common Lisp.
However, in Kawa these are not functions, but instead they
are syntax forms that are processed at compile time. That is
why only quoted
featurenames are supported.
This is consistent with Kawa emphasis on compilation and
For some examples, you may want to look in the
When Kawa sees a
require it searches for
either a matching source file or a previously-compiled class with a
import we generate a classname by converting it in the same
module-name does: taking each identifier in the
library-name-parts, mangling if needed, and concatenating the parts
separated by periods.
If there is a matching module in any
program-unit that is
in the process of being compiled, we use that. This may be
a file requested to be compiled with the
-C command-line switch,
or an extra
library-definition in a file already parsed.
Kawa will attempt to finish compiling the module and load the class,
but if there are circular dependencies it will use the uncompiled definitions.
Next Kawa looks for a matching class in the context classpath.
(There is special handling if the library-name starts with
and certain builtin classes will have
Kawa also searches for a matching source file, described below.
It uses the implicit source name (formed by concatenating the
library-name parts, separated by
"/"), as well as
explicit-source-name. The source file is parsed as
program-unit. It is an error if the
does not declare a library (explicit or implicit) with the
If Kawa finds both a matching source file and a class, it will pick one based on which is newer.
The Java property
kawa.import.path controls how
require search for a suitable source file. Example usage:
$ kawa -Dkawa.import.path=".:<foo fo>/opt/fo-libs/*.scm:/usr/local/kawa"
The value of the
kawa.import.path property is a list of
path elements, separated by
Each path element is combined with either the explicit source name
or the implicit source name to produce a filename.
If a matching file exists, then we have found a source file.
If a path element contains a
"*" then the
is replaced by the implicit source name (without an extension).
(Any explicit source name is ignored in this case.)
For example, for
(import (foo bar)) or
the implicit source name is
"foo/bar". If the path element is
"/opt/kawa/*.sc" then the resulting filename is
If there is no
"*" in the path element, and there is an
explicit source, then it is appended to the path element
(or replaces the path element if the explicit source is absolute).
Otherwise we use the implicit source, followed by the default file extension.
(The default file extension is that of the current source if that is a
named file; otherwise the default for the current language, which
".scm" for Scheme.)
A path element that starts with a selector of the
"< is only applicable if a prefix
of the requested module name matches the
library-name-parts. If there
"*" in the path element, that is replaced by the corresponding rest
of the implicit source name. For example if importing
(fee fo foo fum)
and the path element is
"<fee fo>/opt/fo-libs/*.scm" then the
resulting filename is
If there is a selector but no
"*", then the rest of the path element
following the selector is combined with the explicit or implicit source
as if there were no selector (assuming of course that the selector matches).
If the resulting filename is relative, then it is resolved
relative to the current root. For example the source to
a library with the name
(x y) that compiles to
x.y might be a file named
Then the current root would be
- that is the directory that results from removing the library name
suffix from the file name.
More generally: assume the current module has N name components.
For example the name
(with the class name
x.y) has 2 components.
The current root is what you get when you take the current file name
"/a/b/c/d.scm"), and remove everything after
the N’th slash (
"/") from the end (say
what remains (e.g.
"/a/b/" is the current root.
(If the current input source is not a named file,
use the value of
(current-path) with a
The default search path is
"." - i.e. just search relative
to the current root.
The following libraries are bundled with Kawa:
The above are standard libraries as defined by R7RS.
(rnrs arithmetic bitwise)
The above are standard libraries as defined by R6RS.
Defines procedures and syntax for acessing Java objects and members:
Various Kawa libraries add details.
All the bindings by default available to the kawa top-level.
Importing a supported SRFI numbered
N is conventionally
doing using a
or the older R6RS syntax
(import (srfi : (with a colon, for historical reasons). You can also give it
a name, as specified by SRFI 95. For example, any of these work:
(import (srfi 95)) (import (srfi 95 sorting-and-merging)) (import (srfi :95)) (import (srfi :95 sorting-and-merging))
You can also use
Note you can import from many classes, even if they weren’t
compiled from a library-definition. The set of
in a class are considered as the set of exported definitions,
with the names demangled as needed.
The module can be static module (all public fields must be static), or an instance module (it has a public default constructor).
If an imported definition is a non-static field and if no module
instance for that class
has been registered in the current environment, then a new instance
is created and registered (using a "magic" identifier).
If the module class either inherits from
java.lang.Runnable then the corresponding
method is executed. (This is done after the instance is
registered so that cycles can be handled.) These actions (creating,
registering, and running the module instance) are done both at compile
time and at run time, if necessary.
All the imported fields of the module class are then incorporated in the current set of local visible names in the current module. (This is for both instance and static modules.) This is done at compile time - no new bindings are created at run-time (except for the magic binding used to register the module instance), and the imported bindings are private to the current module. References to the imported bindings will be compiled as field references, using the module instance (except for static fields).