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>.
• <religious-statement>
      Lisp is the world's greatest programming language
  </religious-statement>,
  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.
• 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.
• 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 LispObjects to Java primitives with methods such as intValue() which returns (surprise!) an int.

Other important ABCL classes

• 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 LispObjects 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 ints (in this example) as Fixnums.
• 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).
• 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

1. class (Main)
2. classes of the parameters (int)
3. 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

• Armed Bear Common Lisp website
• Practical Common Lisp by Peter Seibel
• Open Season soundtrack by Paul Westerberg

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.