(c) 1998 Franz Inc - this may not be copied without permission of Franz Inc
Java Common Lisp (jcl) is a language for writing programs to run on the Java Virtual Machine. It uses a syntax familiar to Lisp programmers. jcl programs can be generated by Lisp program. This allows a Lisp program to migrate functionality over to a jvm.
Java is a case sensitive language and thus jcl is as well. All jcl source is read into the java-source package, and when jcl source is read, the readtable is set to be case sensitive. Thus it is possible for a jcl program to be read by a Lisp in Upper Case mode.
When a jcl program is read, the normal lisp reader does the work, thus everything must be valid Lisp syntax. This also means that normal Lisp reader macros are in effect (e.g. #x3ff4 or #.(+ 234 4) will work). Also the comment characters are semicolon and #| followed by |#.
At present jcl is strictly an Ascii system -- it does not permit Unicode characters outside the 8-bit Ascii range to be expressed.
Identifiers in Java are more restricted than they are in Lisp. A Java identifier begins with a letter and contains letters or numbers. The underscore and dollar sign characters are considered letters. The jcl programmer would be advised to follow that restriction on naming identifiers.although the only restriction jcl places on identifiers is that they cannot contain a period.
In order to make it easier for a Lisp program in Upper Case mode to generate jcl programs, we permit strings to be used in places where you would expect an identifier (i..e a Lisp symbol).
In jcl all values have a type. Types are denoted by the following expressions
| Primitive Types | |
| byte | |
| char | |
| short | |
| int | |
| long | |
| float | |
| double | |
| boolean | |
| void | |
| Reference types | Classname |
| Array types | (array type) [same as (array type *)] |
| (array type *) | |
| (array type * ...) |
A file containing jcl code should contain zero or more import forms, an optional package form, a def-java-class form followed by a sequence of zero or more def-java-method forms. def-java-macro forms can be placed anywhere in the file.
The name of the file should be foo.jcl where 'foo' is the name of the class defined in the file.
In jcl, as in java, everything is class-centric. You define a class and then methods that are associated with that class. This is also how you define interfaces, which for the purposes of this function are so similar to classes, that we'll just use the term class to refer to classes and interfaces.
The form of a def-java-class is
(def-java-class class-name (superclass superinterface ...)
flag ...
(field-desc ...)
[:methods (name (arg1 ..) expr) ...]
[:classes (name (superclass ...) [flag ...] (field-desc ...)) ... ]
)
The class-name is an identifier (which is either a Lisp symbol or string). You can use a fully qualified name such as "com.franz.jkf.myclass", but you're more likely to want to set the package to "com.franz.jkf" and just use the class-name "myclass" in the def-java-class form. Every class you define will have one superclass and zero or more superinterfaces. If no superclass is given, then the superclass used is java.lang.Object.
flags are use to specify attributes of the class. Flags are also used to specify attributes of fields in a class and of methods. The table below describes all of the flags and which ones can be used to describe classes, fields and methods:
| Flag | |||
| :abstract | class | method | |
| :final | class | field | method |
| :interface | class | ||
| :native | method | ||
| :private | field | method | |
| :protected | field | method | |
| :public | class | field | method |
| :static | Inner class only | field | method |
| :synchronized | method | ||
| :transient | field | ||
| :volatile | field |
Following the zero or more flags is a list of field descriptions. The format of a field-desc is a list beginning with the field name followed optionally by a sequence of keyword value pairs.
(field-name :type type :initform expression :flags (flag1 ....))
The initform expression, if given, will be evaluated inside the default constructor for this class.
The table above shows the flag values valid inside this field description.
It's possible to list some of the methods of the class in the def-java-class form by putting them after a :methods specifier. This is normally not done for top level classes but it is necessary to use this syntax when defining methods for inner classes.
It's possible to define inner classes by specifying class descriptions after the :classes keyword.
Here are some sample class definitions
(def-java-class htest ()
; simple one slot public class
:public
((x :type int))
)
(def-java-class zip (nil intx inty)
; interface with one slot (which must be static in an interface).
; by specifying nil for the superclass, we get the default (java.lang.Object)
:public :interface
((teeth :type int :initform 20 :flags (:static)))
:methods
(brush () :void) ; normal method
(teeth-count () :int )
)
This form is used to create a method that is associated with the class being defined in the same file.
(def-java-method method-name ((arg1 type)... (argn type)) return-type
flag ...
[(throws exception-class ...)]
expr ....
)
The set of allowable flags is given in the table above.
The body of a method is a sequence of expressions. The allowable expressions are described below. While java is a statement based language, jcl is, like Lisp, an expression based language. In jcl every expression returns zero or one value. The value of the last expression in the body of a method is the value returned by the method.
A few symbols have special meaning inside a jcl method..
(progn expr ...)
Evaluate each expression in sequence and return the value of the last one
(block tagname expr ....)
Like progn except that this sets up a tag for use by return-from
(ref expr slotname1 [ ... slotnameN ])
(ref classname static-slotname [ slotname1 ... slotnameN ])
(ref package1 ... packageN classname static-slotname [ slotname1 ... slotnameN ] )
The ref form is used to
A shorthand for this form can be used in many cases. In jcl the expression foo.bar.baz is converted into (ref foo bar baz) by jcl compiler. This dot convention only works when all components are found within a symbol (or string, in those places where a string can be used in place of a symbol). You can not use the dot convention to turn (myfun x).slot into (ref (myfun x) slot)
(if expr true-expr [ false-expr ] )
This is just like the Common Lisp if special form. In java conditionals only test boolean values. This is not the case in jcl which is more like Lisp in this regard. In jcl the following values are considered true:
The following things are considered false:
(and expr ....)
This is like the Common Lisp and form except that the result is always the boolean true or false value, it never returns the last value of the form.
(or expr ...)
This is like the Common Lisp or form except that the result is always the boolean true or false value, it never returns the value of any subexpression in the form
.
(handler-case hexpr (exception-class (var) expr ...) ...)
This is how the java try...except is expressed in jcl. While hexpr is evaluated, if an exception is raised that is a subclass of one of the exception-classes given in this form, then that exception object is bound to the var and the control continues in the body of the exception handler.
(unwind-protect protected-expr expr1 .... exprN)
This is how the java try...finally is expressed in jcl. While protected-expr is evaluated a condition handler is setup so that any attempt to throw control out of the protected-expr will result in control going instead to expr1 and the following forms. If all the forms up and and including exprN evaluate, then the throw that caused control to reach expr is continued.
(throw expr)
The expr should evaluate to an object that is a subclass of java.lang.Exception. The program resumes execution at the innermost handler for the exception being thrown.
(let ((var [ initform [ type ]]) ....) expr ...)
A set of local variables are bound during the evaluation of a sequence of expressions. If the initform is not given then it is assumed to be 0 (zero). If the type is not given, then it is assumed to be the type of the initform. In this case the type of a number is the most restrictive type that describes it.
(setq place expr ... ...)
Like the Common Lisp setf this stores values not only in local variables but in slots of objects (described by ref expressions). The value of the setq expression is the value of the last expression stored.
(< expr1 expr2 ...) (<= expr1 expr2 ...) (= expr1 expr2 ...) (>= expr1 expr2 ...) (> expr1 expr2 ...)
These are a mixture of the Common Lisp functions by the same names and the and special form. They compute a relation between numbers yet short circuit evaluation as soon as they determine that the answer is false. The return value is the boolean value true or false.
(+ [ expr ... ]) (* [ expr ... ]) (/ [ expr ... ]) (- [ expr ... ])
These take zero or more arguments and compute the appropriate function over the argument values. The exprs are only evaluated as needed before the function is applied to them This means that an arithmetic exception may be signaled before all of the arguments have been evaluated.
(<< value shiftamount)
shift the value left by the given shift amount. The value should be a type that can be widened to an int or a long. The result of the shift will either be an int or a long depending on the type of the value. The low bits of the shiftamount are used to determine the number of places left the value is shifted. If an int will be shifted then the shiftamount is anded with #x1f and that value is the shift amount. If value is a long then the shiftamount is anded with #x3f. The resulting shift amount is thus always a non-negative number.
(>> value shiftamount)
shift the value right by the given shiftamount, copying the sign bit into vacated bits. This is an arithmetic shift. See the description for << to see how the shiftamount value is modified before it is used
(>>> value shiftamount)
shift the value right by the given shiftamount, copying zero into vacated bits. This is a logical shift. See the description for << to see how the shiftamount value is modified before it is used.
(logand expr ...) (logior expr ...) (logxor expr ...)
perform the bitwise operation on the expressions (which must be of type int or long)
(instanceof expr type)
returns true if the object that is the value of the expr is an
instance of the named type. The expression expr
must return a reference to an object, not a primitive type such as int. The type
is not quoted.
e.g. (instanceof x String) tests if x points to a String object.
(not expr)
Compute the boolean value that is the inverse of the given value, where the description of what is considered true and false is described with the if special form.
(new type expr ...)
Allocate a new object of the given type and call its constructor passing the value of the exprs as arguments.
The type is normally a symbol. It can also be an anonymous type description.
The form of an anonymous type description is
(:class superclass (superinterface ...) [flag ...] (field-desc ...) [:methods method-desc] [:classes class-desc])
Essentially it looks just like a def-java-class form except that instead of naming the class you name the class and/or interfaces that the class inherits from. If the anonymous class is to inherit from only an interface an no class then that interface should be put in the superclass spot, i.e. (:class superint () .....)
Users can add macros to the jcl compiler with def-java-macro. The following macros are already defined:
(cond (pred-expr value-expr1 ... value-exprN) ... [(t value-expr1 .. value-exprN) ])
This is very close to the Common Lisp cond form except that one type of clause is not permitted: that is the clause where the value of the predicate is the value returned (if it is true).
(if* pred then expr1 ... exprN [ elseif pred then expr1 .... exprN ] ... [ else expr1 .... exprN ] )
The if* macro from Common Lisp. This is designed to do the work of the Common Lisp if, when and unless forms and maximize program readability.
(s+ expr1 expr2 ... exprN)
In Java the + operator is overloaded to do string concatenation. We chose not to do this in JiL. Instead we offer the s+ macro that generates code just like the Java compiler when it determines that + must do string concatenation. Each expression can return any type of value and as long as there is an appropriate append method in the class java.lang.StringBuffer that accepts that type of value.
A jcl source file can contain a package form
(package packagename)
This form should appear before the class and any methods are defined. It specifies the package prefix for the class. Failure to include a package form in a file sets the package prefix to the empty string.
The import form specifies a class or set of classes which should be referenceable without the full package qualification. There can be zero or more import forms in a jcl source file
(import classname) (import packagename.*)
The first form imports just the single class, the second imports all classes in the given package (but not subpackages of the given package).
Just as in Java, there is an implicit import done of java.lang.* before a jcl file is compiled.
This defines a macro for use in compiling jcl expressions only. The form is identical to Lisp's defmacro:
(def-java-macro name (arg ...) expr ...)
First you must install a Java Development Tookit on your machine and verify that all of your environment variables are set so that you can compile and run a simple java program.
Next you place the files comprising the jcl compiler on your machine, and we suggest that they be in the java subdirectory of the main directory in which you intend to work. Start lisp and
:ld java/load
and the jcl compiler will be compiled and loaded into Lisp.
The function (jcomp-file filename) will now compile a jcl sourcefile into a classfile. A source file can contain multiple class definitions. The def-java-method's that follow a def-java-class are associated with that class. The output of jcomp-file are one or more class files. The name of the class files are the names of the classes defined, followed by a ".class". Inner and anoymous classes (when they are supported) are given names generated by the jcl compiler and are written out one per file as well.
The toplevel forms permitted in a file processed by jcl are: