The class inherits from the classes and interfaces listed in supers. This is a list of names of classes that are in scope (perhaps imported using require), or names for existing classes or interfaces optionally surrounded by <>, such as <gnu.lists.Sequence>. If define-simple-class is used, at most one of these may be the name of a normal Java class or classes defined using define-simple-class; the rest must be interfaces or classes defined using define-class. If define-class is used, all of the classes listed in supers should be interfaces or classes defined using define-class.

As a matter of style the following order is suggested, though this not enforced:

Each field-decl declares a instance "slot" (field) with the given field-name. By default it is publicly visible, but you can specify a different visiblity with the access: specifier. The following field-option keywords are implemented:

The field-name can be left out. That indicates a "dummy slot", which is useful for initialization not tied to a specific field. In Java terms this is an instance or static initializer, i.e., a block of code executed when a new instance is created or the class is loaded.

In this example, x is the only actual field. It is first initialized to 10, but if (some-condition) is true then its value is doubled.

(define-simple-class <my-class> ()
  (allocation: 'class
   init: (perform-actions-when-the-class-is-initizalized))
  (x init: 10)
  (init: (if (some-condition) (set! x (* x 2)))))

Each method-decl declares a method, which is by default public and non-static, and whose name is method-name. (If method-name is not a valid Java method name, it is mapped to something reasonable. For example foo-bar? is mapped to isFooBar.) The types of the method arguments can be specified in the formal-arguments. The return type can be specified by a opt-return-type, deprecated-return-specifier, or is otherwise the type of the body. Currently, the formal-arguments cannot contain optional, rest, or keyword parameters. (The plan is to allow optional parameters, implemented using multiple overloaded methods.)

A method-decl in a define-simple-class can have the following option-keywords:

The scope of the body of a method includes the field-decls and field-decls of the body, including those inherited from superclasses and implemented interfaces.

If the method-body is the special form #!abstract, then the method is abstract. This means the method must be overridden in a subclass, and you're not allowed to create an instance of the enclosing class.

(define-simple-class Searchable () interface: #t
  ((search value) :: boolean #!abstract))

If the method-body is the special form #!native, then the method is native, implemented using JNI.

The special method-name ‘*init*’ can be used to name a non-default constructor (only if make-interface discussed above is #f). It can be used to initialize a freshly-allocated instance using passed-in parameters. You can call a superclass or a sibling constructor using the invoke-special special function. (This is general but admittedly a bit verbose; a more compact form may be added in the future.) See the example below.

In the following example we define a simple class 2d-vector and a class 3d-vector that extends it. (This is for illustration only - defining 3-dimensional points as an extension of 2-dimensional points does not really make sense.)

(define-simple-class 2d-vector ()
  (x ::double init-keyword: x:)
  ;; Alternative type-specification syntax.
  (y type: double init-keyword: y:)
  (zero-2d :: 2d-vector allocation: 'static
   init-value: (2d-vector 0))
  ;; An object initializer (constructor) method.
  ((*init* (x0 ::double) (y0 ::double))
   (set! x x0)
   (set! y y0))
  ((*init* (xy0 ::double))
   ;; Call above 2-argument constructor.
   (invoke-special 2d-vector (this) '*init* xy0 xy0))
  ;; Need a default constructor as well.
  ((*init*) #!void)
  ((add (other ::2d-vector)) ::2d-vector
   ;; Kawa compiles this using primitive Java types!
   (2d-vector
     x: (+ x other:x)
     y: (+ y other:y)))
  ((scale (factor ::double)) ::2d-vector
   (2d-vector x: (* factor x) y: (* factor y))))

(define-simple-class 3d-vector (2d-vector)
  (z type: double init-value: 0.0 init-keyword: z:)
  ;; A constructor which calls the superclass constructor.
  ((*init* (x0 ::double) (y0 ::double) (z0 ::double))
   (invoke-special 2d-vector (this) '*init* x0 y0)
   (set! z z0))
  ;; Need a default constructor.
  ((*init*) #!void)
  ((scale (factor ::double)) ::2d-vector
   ;; Note we cannot override the return type to 3d-vector
   ;; because Kawa doesn't yet support covariant return types.
   (3d-vector
     x: (* factor x)
     y: (* factor (this):y) ;; Alternative syntax.
     z: (* factor z))))

Note we define both explicit non-default constructor methods, and we associate fields with keywords, so they can be named when allocating an object. Using keywords requires a default constructor, and since having non-default constructors suppresses the implicit default constructor we have to explicitly define it. Using both styles of constructors is rather redundant, though.

Kawa doesn't directly support marking a method as synchronized, but you can get the same effect using a synchronized expression:

(define-simple-class <Bar> ()
  ;; non-static method
  ((foo) :: void
   (synchronized (this)
		 (synchronized-block)))
  ;; static method
  ((baz) allocation: 'static :: void
   (synchronized <Bar>
		 (synchronized-block))))

An anonymous class is commonly used in the Java platform where a function language would use a lambda expression. Examples are call-back handlers, events handlers, and run methods. In these cases Kawa lets you use a lambda expression as a short-hand for an anonymous class. For example:

(button:addActionListener
  (lambda (e) (do-something)))

is equivalent to:

(button:addActionListener
  (object (java.awt.event.ActionListener)
    ((actionPerformed (e ::java.awt.event.ActionEvent))::void
     (do-something))))

This is possible when the required type is an interface or abstract class with a Single (exactly one) Abstract Methods. Such a class is sometypes called a SAM-type, and the conversion from a lambda expression to an anonymous class is sometimes called SAM-conversion.

Note that Kawa can also infer the parameter and return types of a method that overrides a method in a super-class.

The definitions that a module exports are accessible to other modules. These are the "public" definitions, to use Java terminology. By default, all the identifiers declared at the top-level of a module are exported, except those defined using define-private. (If compiling with the --main flag, then by default no identifiers are exported.) However, a major purpose of using modules is to control the set of names exported. One reason is to reduce the chance of accidental name conflicts between separately developed modules. An even more important reason is to enforce an interface: Client modules should only use the names that are part of a documented interface, and should not use internal implementation procedures (since those may change).

If there is a module-export (or export) declaration in the module, then only those names listed are exported. There can be more than one module-export, and they can be anywhere in the Scheme file. The recommended style has a single module-export near the beginning of the file.

In this module, fact is public and worker is private:

(module-export fact)
(define (worker x) ...)
(define (fact x) ...)

Alternatively, you can write:

(define-private (worker x) ...)
(define (fact x) ...)

If you want to just use a Scheme module as a module (i.e. load or require it), you don't care how it gets translated into a module class. However, Kawa gives you some control over how this is done, and you can use a Scheme module to define a class which you can use with other Java classes. This style of class definition is an alternative to define-class, which lets you define classes and instances fairly conveniently.

The default name of the module class is the main part of the filename of the Scheme source file (with directories and extensions sripped off). That can be overridden by the -T Kawa command-line flag. The package-prefix specified by the -P flag is prepended to give the fully-qualified class name.

By default, the base class of the generated module class is unspecified; you cannot count on it being more specific than Object. However, you can override it with module-extends.

Note that the compiler does not currently check that all the abstract methods requires by the base class or implemented interfaces are actually provided, and have the correct signatures. This will hopefully be fixed, but for now, if you are forgot a method, you will probably get a verifier error

For each top-level exported definition the compiler creates a corresponding public field with a similar (mangled) name. By default, there is some indirection: The value of the Scheme variable is not that of the field itself. Instead, the field is a gnu.mapping.Symbol object, and the value Scheme variable is defined to be the value stored in the Symbol. Howewer, if you specify an explicit type, then the field will have the specified type, instead of being a Symbol. The indirection using Symbol is also avoided if you use define-constant.

If the Scheme definition defines a procedure (which is not re-assigned in the module), then the compiler assumes the variable as bound as a constant procedure. The compiler generates one or more methods corresponding to the body of the Scheme procedure. It also generates a public field with the same name; the value of the field is an instance of a subclass of <gnu.mapping.Procedure> which when applied will execute the correct method (depending on the actual arguments). The field is used when the procedure used as a value (such as being passed as an argument to map), but when the compiler is able to do so, it will generate code to call the correct method directly.

You can control the signature of the generated method by declaring the parameter types and the return type of the method. See the applet (see the section called “Compiling to an applet”) example for how this can be done. If the procedures has optional parameters, then the compiler will generate multiple methods, one for each argument list length. (In rare cases the default expression may be such that this is not possible, in which case an "variable argument list" method is generated instead. This only happens when there is a nested scope inside the default expression, which is very contrived.) If there are #!keyword or #!rest arguments, the compiler generate a "variable argument list" method. This is a method whose last parameter is either an array or a <list>, and whose name has $V appended to indicate the last parameter is a list.

Top-leval macros (defined using either define-syntax or defmacro) create a field whose type is currently a sub-class of kawa.lang.Syntax; this allows importing modules to detect that the field is a macro and apply the macro at compile time.

Unfortunately, the Java class verifier does not allow fields to have arbitrary names. Therefore, the name of a field that represents a Scheme variable is "mangled" (see the section called “Mapping Scheme names to Java names”) into an acceptable Java name. The implementation can recover the original name of a field X as ((gnu.mapping.Named) X).getName() because all the standard compiler-generate field types implemented the Named interface.

There are two kinds of module class: A static module is a class (or gets compiled to a class) all of whose public fields a static, and that does not have a public constructor. A JVM can only have a single global instance of a static module. An instance module has a public default constructor, and usually has at least one non-static public field. There can be multiple instances of an instance module; each instance is called a module instance. However, only a single instance of a module can be registered in an environment, so in most cases there is only a single instance of instance modules. Registering an instance in an environment means creating a binding mapping a magic name (derived from the class name) to the instance.

In fact, any Java class class that has the properties of either an instance module or a static module, is a module, and can be loaded or imported as such; the class need not have written using Scheme.

You can control whether a module is compiled to a static or a non-static class using either a command-line flag to the compiler, or using the module-static special form.

The top-level actions of a module will get compiled to a run method. If there is an explicit method-extends, then the module class will also automatically implement java.lang.Runnable. (Otherwise, the class does not implement Runnable, since in that case the run method return an Object rather than void. This will likely change.)

Certain compilation options can be be specified either on the command-line when compiling, or in the module itself.

You can import a module into the current namespace with require.

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.

The easiest way to invoke a static method is to use colon notation, specifically:

The class-expression can be a class in the current lexical scope, such as a class defined using define-simple-class:

(define-simple-class MyClass ()
  ((add2 x y) allocation: 'static (+ x y)))
(MyClass:add2 3 4) ⇒ 7

Often class-expression is a fully-qualified class name:

(java.lang.Math:sqrt 9.0) ⇒ 3.0

This is only allowed when the name is of a class that exists and is accessible both at compile-time and run-time, and the name is not otherwise lexically bound.

You can also use a defined alias:

(define-alias jlMath java.lang.Math)
(jlMath:sqrt 16.0) ⇒ 4.0

You can even evaluate class-expression at run-time (in which case Kawa may have to use slower reflection):

(let ((math java.lang.Math)) math:sqrt 9.0) ⇒ 3.0

Here java.lang.Math evaluates to a java.lang.Class instance for the named class (like Java's java.lang.Class.class, again assuming the class exists and is accessible both at compile-time and run-time, and the name is not otherwise lexically bound.

The syntax is:

This invokes the method named method-name with the evaluated instance as the target object and the evaluated arguments as the method arguments.

For example:

((list 9 8 7):toString) ⇒ "(9 8 7)"
([5 6 7]:get 2) ⇒ 7

This older syntax is also available:

For example:

(*:toString (list 9 8 7))

You can also name the class explicitly:

For example:

(java.util.List:get [5 6 7] 2) ⇒ 7

Using an explicit class is like coercing the instance:

Note that for some special values, including java.lang.Class instances, you can't use the compact form of colon notation where the instance is before the comma:

(java.lang.Integer:getDeclaredField "MAX_VALUE") ⇒ error

This is because in this case we look for a static member of java.lang.Integer (at least as currently defined and implemented), while we want an instance member of java.lang.Class. In those cases you can use one of these alternative forms, which all return the same java.lang.reflect.Field result:

(*:getDeclaredField java.lang.Integer "MAX_VALUE")
(java.lang.Class:getDeclaredField java.lang.Integer "MAX_VALUE")
(invoke java.lang.Integer 'getDeclaredField "MAX_VALUE")

The method to invoke is selected using the specified method name and argments. If specified name is not a Java name, it is "mangled" (see the section called “Mapping Scheme names to Java names”) into a valid Java name. All accessible methods whose names match are considered. Methods that match after appending $V or $X or $V$X are also considered. A $V suffix matches a variable number of arguments: any excess arguments are collect into an gnu.lists.LList or a Java array (depending on the final parameter type). A $X specifies that the method expects an extra implicit CallContext parameter. In that case the method's result is written to the CallContext, so the method result type must be void.

(Kawa may compile a procedure with a #!rest or keyword args whose name is fn to a method named fn$V. It adds an implicit parameter for the extra arguments. By default this extra extra parameter is a Scheme list. You can specify a Java array type instead, in which case the method is named fn without the $V, and instead it is marked as a Java-5 varargs method. The array element type must be compatible with all the extra arguments.)

If you prefer, you can instead use the following functions. (There is also an older deprecated lower-level interface (see ???.)

Some examples using these functions are ‘vectors.scm’ and ‘characters.scm’ the directory ‘kawa/lib’ in the Kawa sources.

This way of invoking a method is deprecated.

You can use define-namespace to define an alias for a Java class:

(define-namespace Int32 "class:java.lang.Integer")

In this example the name Int32 is a namespace alias for the namespace whose full name is "class:java.lang.Integer". The full name should be the 6 characters "class:" followed by the fully-qualified name of a Java class.

Instead of a vamespace-uri you can use a variable that names a class, usually of the form <classname>. The following is equivalent to the above:

(define-namespace Int32 <java.lang.Integer>)

However, there is one important difference: The <classname> is first searched in the lexical scope. It may resolve to a class defined in the current compilation unit (perhaps defined using define-simple-class), or imported from another module, or an alias (such as from define-alias). Only if <classname> is not found in the current scope is it tried as the class name classname.

You can name a method using a qualified name containing a colon. The part of the name before the colon is a namespace alias (in this case Int32), and the part of the name after the colon is the method name. For example:

(Int32:toHexString 255) ⇒ "ff"

This invokes the static method toHexString in the Java class java.lang.Integer, passing it the argument 255, and returning the String "ff".

The general syntax is

(prefix:method-name arg ...)

This invokes the method named method-name in the class corresponding to prefix, and the args are the method arguments.

You can use the method name new to construct new objects:

(Int32:new '|255|)

This is equivalent to the Java expression new Integer("255"). You can also write:

(Int32:new "255")

You can also call instance methods using a namespace prefix:

(Int32:doubleValue (Int32:new "00255"))

This returns the double value 255.0.

As a shorthand, you can use the name of a Java class instead of a namespace alias:

(java.lang.Integer:toHexString 255)
(java.lang.Object:toString some-value)

If Kawa sees a qualified name with a prefix that is not defined and that matches the name of a known class, then Kawa will automatically treat the prefix as a nickname for namespace uri like class:java.lang.Integer. Both conditions should be true at both compile-time and run-time. However, using an explicit define-namespace is recommended.

As a final shorthand you can use an identifier in handle brackets, such as an existing type alias like <list>. The following are all equivalent:

(<list>:list3 'a 'b 'c)

This is equivalent to:

(define-namespace prefix <list>
(prefix:list3 'a 'b 'c)

for some otherwise-unused prefix.

The recommmended way to access fields uses the colon notation. For static fields and properties the following is recommended:

For example:

java.lang.Integer:MAX_VALUE

A property with a get method is equivalent to a field. The following are all equivalent:

java.util.Currency:available-currencies
java.util.Currency:availableCurrencies
(java.util.Currency:getAvailableCurrencies)

Just like for a method call, the class-expression can be a class in the current lexical scope, a fully-qualified class name, or more generally an expression that evaluates to a class.

The syntax is:

The field-name can of course be the name of an actual object field, but it can also be the name of a property with a zero-argument get method. For example, if cal is a java.util-Calendar instance, then the following are all equivalent:

cal:time-zone
cal:timeZone
(cal:getTimeZone)
(cal:get-time-zone)

You can use colon notation to assign to a field:

(set! cal:time-zone TimeZone:default)

which is equivalent to:

(cal:setTimeZone (TimeZone:getDefault))

A Java array only has the length field, plus the class property:

(int[] 4 5 6):length ⇒ 3
(int[] 4 5 6):class:name ⇒ "int[]"

The following methods are useful in cases where colon notation is ambiguous, for example where there are both fields and methods with the same name. You might also prefer as a matter of style, to emphasise that a field is being accessed.

Examples:

(static-field java.lang.System 'err)
;; Copy the car field of b into a.
(set! (field a 'car) (field b 'car))

There is older syntax where following the colon there is field name a following the colon and a period.

To access an static field named field-name use this syntax

(prefix:.field-name instance)

The prefix can be as discussed in See the section called “Calling Java methods from Scheme”. Here are 5 equivalent ways:

(java.lang.Integer:.MAX_VALUE)
(<java.lang.Integer>:.MAX_VALUE)
(define-namespace Int32 <java.lang.Integer>)
(Int32:.MAX_VALUE)
(define-namespace Integer "class:java.lang.Integer")
(Integer:.MAX_VALUE)
(define-alias j.l.Integer java.lang.Integer)
(j.l.Integer:.MAX_VALUE)

You can set a static field using this syntax:

(set! (prefix:.field-name) new-value)

The special field name class can be used to extract the java.lang.Class object for a class-type. For example:

(java.util.Vector:.class) ⇒ class java.util.Vector

To access a instance field named field-name use the following syntax. Note the period before the field-name.

(*:.field-name instance)

This syntax works with set! - to set the field use this syntax:

(set! (*:.field-name instance) new-value)

Here is an example:

(define p (list 3 4 5))
(*:.cdr p) ⇒ (4 5)
(set! (*:.cdr p) (list 6 7))
p ⇒ (3 6 7)

You can specify an explicit class:

(prefix:.field-name instance)

If prefix is bound to <class>, then the above is equivalent to:

(*:.field-name (as <class> instance))

To allocate a Java array you can use the array type specifier as a constructor function. For example, to allocate an array with room for 10 elements each of each is a primitive int:

(int[] length: 10)

You can specify the initial elements instead of the length:

(object[] 31 32 33 34)

This creates a 4-length array, initialized to the given values.

Note this is a variation of the generation object-allocation (see the section called “Allocating objects”) pattern. You can explicitly use the make function, if you prefer:

(make object[] 31 32 33 34)

If you specify a length, you can also specify initial values for selected elements. If you specify an index, in the form of a literal integer-valued keyword, then following elements are placed starting at that position.

(int[] length: 100 10 12 80: 15 16 50: 13 14)

This creates an array with 100 elements. Most of them are initialized to the default value of zero, but elements with indexes 0, 1, 50, 51, 80, 81 are initialized to the values 10, 12, 13, 14, 15, 16, respectively.

You can access the elements of a Java array by treating it as a one-argument function, where the argument is the index:

(define primes (integer[] 2 3 5 7 11 13))
(primes 0) ⇒ 2
(primes 5) ⇒ 13

You can set an element by treating the array as a function with a setter:

(set! (primes 0) -2)
(set! (primes 3) -7)
primes ⇒ [-2 3 5 -7 11 13]

To get the number of elements of an array, you can treat it as having a length field:

primes:length ⇒ 6

Here is a longer example. This is the actual definition of the standard gcd function. Note the args variable receives all the arguments on the form of an integer array. (This uses the Java5 varargs feature.)

(define (gcd #!rest (args ::integer[])) ::integer
  (let ((n ::int args:length))
    (if (= n 0)
	0
	(let ((result ::integer (args 0)))
	  (do ((i ::int 1 (+ i 1)))
	      ((>= i n) result)
	    (set! result (gnu.math.IntNum:gcd result (args i))))))))

The above example generates good code, thanks to judicious use of casts and type specifications. In general, if Kawa knows that a “function” is an array then it will generate efficient bytecode instructions for array operations.

The deprecated ??? are also supported.

Kawa also supports the standard javax.script API. The main advantage of this API is if you want your users to be able to chose between multiple scripting languages. That way you can support Kawa without Kawa-specific programming.

For example the standard JDK tool jrunscript provides a read-eval-print-loop for any language that implements the javax.script API. It knows nothing about Kawa but can still use it:

$ jrunscript -cp kawa.jar -l scheme
scheme> (cadr '(3 4 5))
4

(Of course the jrunscript REPL isn't as nice as the one that Kawa provides. For example the latter can handle multi-line inputs.)