Armed Bear Common Lisp (ABCL) - User Documentation "It's the right to arm bears" —Paul Westerberg

Overview

Supports interoperability both ways between Java and Lisp.

ABCL is distributed under the GNU General Public License with Classpath exception. Basically this means you can use ABCL from your application without the need to make your own application open source.



Benefits of using ABCL

Java has great GUI libraries,

<religious-statement>

but it's not the world's greatest programming language

</religious-statement> .

but it's not the world's greatest programming language . <religious-statement>

Lisp is the world's greatest programming language

</religious-statement> ,

but has no standard GUI libraries.

Lisp is the world's greatest programming language , but has no standard GUI libraries. Therefore: Write great applications using Java for your front-end GUI backed with Lisp code and get the best of both worlds.

Installing ABCL

Go to the ABCL page and find the download link.

Download the Zip of the Latest Build.

Upzip the files.

Build according to instructions here.

In the end, you will end up with a file called

<abcl-dir>\dist\abcl.jar

You will need to add abcl.jar to your class path for ABCL projects.

to your class path for ABCL projects. That's it!

Hello, world!

Type the following at the command line (adjust the path as necessary): C:\abcl-src-0.15.0>cd dist C:\abcl-src-0.15.0\dist>java -jar abcl.jar This will run the Lisp REPL.

This will run the Lisp REPL. At the REPL prompt, type: CL-USER(1): (format t "Hello, world!") Hello, world! NIL

To exit the REPL, type: CL-USER(2): (exit)

ABCL Cons and LispObject classes

Cons Corresponds to a Lisp cons or list Has car() and cdr() methods if you want to write Java code in a Lisp style. Can also unbox Cons objects into arrays, if you wish by using the copyToArray() method which returns LispObject[] .

LispObject A Lisp S-expression Can unbox LispObject s to Java primitives with methods such as intValue() which returns (surprise!) an int .



Other important ABCL classes

org.armedbear.lisp

Interpreter createInstance() : Creates a Lisp interpreter. eval(String expression) : Evaluates a Lisp expression. Often used with load to load a Lisp file.

Packages findPackage(String packageName) : Finds a Lisp package.

Package findAccessibleSymbol(String symbolName) : Finds a symbol such as that for a function.

Symbol getSymbolFunction() : Returns the function for a corresponding symbol.

Function execute() : Executes a function taking a variable number of LispObject s as arguments.

JavaObject : A subclass of LispObject for objects coming from Java.

Getting a Lisp package from Java

To load a file of Lisp functions from Java, you do the following: Interpreter interpreter = Interpreter.createInstance(); interpreter.eval("(load \"my-lisp-code.lisp\")");

You can then load the package containing a function you want to call. In this case, our function is in the default Lisp package: Package defaultPackage = Packages.findPackage("CL-USER");

Getting a Lisp function from Java

Suppose we have a function called my-function defined in my-lisp-code.lisp (which was loaded above). We obtain it in two steps like this: Symbol myFunctionSym = defaultPackage.findAccessibleSymbol( "MY-FUNCTION"); Function myFunction = myFunctionSym.getSymbolFunction();

Calling a Lisp function from Java

Call a Lisp function like this: Cons list = (Cons) myFunction.execute( Fixnum.getInstance(64), Fixnum.getInstance(64));

Our original Lisp function returned a list. ABCL's Cons Java class corresponds to a Lisp list. Note also that we wrap the int s (in this example) as Fixnum s.

Java class corresponds to a Lisp list. Note also that we wrap the s (in this example) as s. On the Lisp side, we can access these integers as if they came from directly from another Lisp method: (defun my-function (n1 n2) ...)

Converting Java objects to Lisp values and vice-versa

Since the user can't be expected to know how to map every Java type to Lisp and vice-versa, there are a couple

of nice methods you can use in all cases:

public static LispObject JavaObject.getInstance(Object, boolean) : Converts (or wraps) a Java object to a Lisp object, if the boolean is true (else it just wraps it in a JavaObject ).

: Converts (or wraps) a Java object to a Lisp object, if the boolean is true (else it just wraps it in a ). public Object LispObject.javaInstance() : Converts (or unwraps) a Lisp object to Java. You can invoke this on any Lisp object; if it can't be converted, it will be returned as-is.

Calling Java from Lisp

This code sample is by Ville Voutilainen.

Java code

public class Main { public int addTwoNumbers(int a, int b) { return a + b; } }

Lisp code

We need to get the

class ( Main ) classes of the parameters ( int ) method reference (getting that requires the class of our object and the classes of the parameters)

After that we can invoke the function with jcall , giving the method reference, the object and the parameters. The result is a Lisp object (no need to do jobject-lisp-value , unless we invoke the method with jcall-raw ).

(defun void-function (param) (let* ((class (jclass "Main")) (intclass (jclass "int")) (method (jmethod class "addTwoNumbers" intclass intclass)) (result (jcall method param 2 4))) (format t "in void-function, result of calling addTwoNumbers(2, 4): ~a~%" result)))

Sample Code

Code examples can be found here.

Conway's Game of Life: This example shows how to call Lisp code from Java. life.lisp : Lisp code for simulating Conway's Game of Life cellular automaton. LifeGUI.java : A subclass of JApplet for showing a Life universe. Calls life.lisp for all Life functionality.



References

This documentation was written by Paul Reiners (except where otherwise noted). Helpful suggestions and corrections were given by Alessio Stalla and others on the ABCL mailing list. Please email me with any suggestions or corrections.

Armed Bear Common Lisp Tutorial