You can import a module into the current namespace with import or 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.
Syntax: import import-set*
An import declaration provides a way to import identifiers
exported by a library (module). Each import-set names a set of
bindings from a library and possibly specifies local names
for the imported bindings.
A library-reference is 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
only, except, prefix, and rename forms as
described below.
-
An only form 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-pair is used, then the identifier1import-set,
and is renamed to 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)))
The names A, B1, C, and D1 must
exist in the library (kawa example). The bindings are
accessible using the names A, B2, C, and D2.
An except form 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 import-set.
A prefix form adds the identifier prefix to each name from
another import-set.
-
A rename form:
(rename (identifier1 identifier2) …)
removes the bindings for identifier1 …import-set, then adds the bindings back for the
corresponding identifier2 …import-set. Each identifier1import-set, each identifier2 must not be in the
intermediate import-set, and the identifier2s must be
distinct.
A class form is a convenient way to define abbreviations
for class names; it may be more convenient than define-alias.
The class-prefix is concatenated with each identifier
(with a period in between) to produce a classname.
Each identifier becomes an alias for the class.
For example:
(import (class java.util Map (HashMap HMap)))
This defines Map as an alias for java.util.Map,
and HMap as an alias for java.util.HashMap.
(You can think of the class form as similar to a only form,
where the class-prefix names a special kind of
library represented of a Java package, and whose exported
bindings are the classes in the package.)
You can combine the class form with
only, except, rename, and prefix,
though only prefix is 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)
Syntax: require ’featureName
Syntax: require classname [explicit-source-name
Syntax: require explicit-source-name
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 classname.
The form require has similar functionality as import,
but with a different syntax, and without options like rename.
If a "sourcepath"
If a 'featurename is specified then the
featurename is looked up (at compile time) in the "feature table"
which yields the implementing classname.
Syntax: provide ’featurename
Declare that 'featurename is available.
A following cond-expand in this scope will match featurename.
Using require and provide with featurenames is
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
static binding.
For some examples, you may want to look in the gnu/kawa/slib
directory.
When Kawa sees a import or require it searches for
either a matching source file or a previously-compiled class with a
matching name.
For import we generate a classname by converting it in the same
way 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 srfi,
and certain builtin classes will have kawa.lib. prepended.)
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
any explicit-source-name. The source file is parsed as
a program-unit. It is an error if the program-unit
does not declare a library (explicit or implicit) with the
matching name.
If Kawa finds both a matching source file and a class, it will pick one
based on which is newer.
Searching for source files
The Java property kawa.import.path controls how import
and 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 (require foo.bar)
the implicit source name is "foo/bar". If the path element is
"/opt/kawa/*.sc" then the resulting filename is "/opt/kawa/foo/bar.sc".
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
is ".scm" for Scheme.)
A path element that starts with a selector of the
form "<library-name-parts>" is only applicable if a prefix
of the requested module name matches the library-name-parts. If there
is "*" 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 "/opt/fo-libs/foo/fum.scm".
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
a class x.y might be a file named /a/b/x/y.scm.
Then the current root would be /a/b/
- 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 (x y)
(with the class name x.y) has 2 components.
The current root is what you get when you take the current file name
(say "/a/b/c/d.scm"), and remove everything after
the N’th slash ("/") from the end (say "c/d.scm";
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 "/" appended.)
The default search path is "." - i.e. just search relative
to the current root.
The following libraries are bundled with Kawa:
-
(scheme base)
-
(scheme case-lambda)
-
(scheme char)
-
(scheme complex)
-
(scheme cxr)
-
(scheme cxr)
-
(scheme eval)
-
(scheme inexact)
-
(scheme lazy)
-
(scheme load)
-
(scheme process-context)
-
(scheme read)
-
(scheme repl)
-
(scheme time)
-
(scheme write)
-
(scheme r5rs)
The above are standard libraries as defined by R7RS.
-
(rnrs arithmetic bitwise)
-
(rnrs hashtables)
-
(rnrs lists)
-
(rnrs programs)
-
(rnrs sorting)
-
(rnrs unicode)
The above are standard libraries as defined by R6RS.
-
(kawa reflect)
Defines procedures and syntax for acessing Java objects and members:
as
field
instance?
invoke
invoke-static
invoke-special
make
primitive-throw
set-field!
set-static-field!
static-field
-
(kawa expressions)
-
(kawa hashtable)
-
(kawa quaternions)
-
(kawa rotations)
-
(kawa regex)
-
(kawa string-cursors)
Various Kawa libraries add details.
-
(kawa base)
All the bindings by default available to the kawa top-level.
Importing a supported SRFI numbered N is conventionally
doing using a (import (srfi N))
or the older R6RS syntax (import (srfi :N)) (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 (require 'srfi-N):
(require 'srfi-95)
Importing from a plain class
Note you can import from many classes, even if they weren’t
compiled from a library-definition. The set of public fields
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 gnu.expr.ModuleBody
or implements java.lang.Runnable then the corresponding run
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).
