source: public/content/doc/abcl-user.html

Last change on this file was 13128, checked in by vvoutilainen, 14 years ago

Fix example links.
File size: 10.5 KB
Line 
1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2<!-- saved from url=(0076)http://www.automatous-monk.com/jvmlanguages/abcl/Armed_Bear_Common_Lisp.html -->
3<HTML xmlns="http://www.w3.org/1999/xhtml"><HEAD><META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<TITLE>Armed Bear Common Lisp User Documentation</TITLE>
5<META name="Description" content="Introductory user documentation on Armed Bear Common Lisp.">
6  <LINK rel="stylesheet" type="text/css" href="./abcl-user_files/style.css">
7</HEAD><BODY>
8 <DIV class="header">
9   <H1>Armed Bear Common Lisp (ABCL) - User Documentation</H1>
10<H2> "It's the right to arm bears" —Paul Westerberg </H2>
11 </DIV>
12<H1>Overview</H1>
13<UL>
14  <LI> Supports interoperability both ways between Java and Lisp. </LI>
15  <LI> ABCL is distributed under the GNU General Public License with Classpath exception.
16    <UL>
17      <LI>Basically this means you can use ABCL from your application without the need to make your own application open source.
18      </LI>
19    </UL>
20  </LI>
21</UL>
22<H1> Benefits of using ABCL </H1>
23<UL>
24  <LI> Java has great GUI libraries, <BR>
25    <CODE>&lt;religious-statement&gt;</CODE><BR>
26    &nbsp;&nbsp; &nbsp; but it's not the world's greatest programming language<BR>
27    <CODE>&lt;/religious-statement&gt;</CODE>. </LI>
28  <LI> <CODE>&lt;religious-statement&gt;</CODE><BR>
29    &nbsp;&nbsp; &nbsp;Lisp is the world's greatest programming language<BR>
30    <CODE>&lt;/religious-statement&gt;</CODE>,<BR>
31    but has no standard GUI libraries. </LI>
32  <LI> Therefore: Write great applications using Java for your front-end GUI backed with Lisp code and get the best of both worlds. </LI>
33</UL>
34<H1> Installing ABCL </H1>
35<UL>
36  <LI> Go to the <A href="http://common-lisp.net/project/armedbear/">ABCL page</A> and find the download link. </LI>
37  <LI> Download the Zip of the Latest Build. </LI>
38  <LI> Upzip the files. </LI>
39  <LI> Build according to instructions <A href="http://common-lisp.net/project/armedbear/doc/abcl-install-with-java.html">here</A>. </LI>
40  <LI> In the end, you will end up with a file called<BR>
41    <CODE>&nbsp;&nbsp;&nbsp;&nbsp; &lt;abcl-dir&gt;\dist\abcl.jar</CODE> </LI>
42  <LI> You will need to add <CODE>abcl.jar</CODE> to your class path for ABCL projects. </LI>
43  <LI> That's it! </LI>
44</UL>
45<H1> Hello, world! </H1>
46<UL>
47  <LI> Type the following at the command line (adjust the path as necessary):
48    <PRE>     C:\abcl-src-0.15.0&gt;cd dist
49     C:\abcl-src-0.15.0\dist&gt;java -jar abcl.jar
50</PRE>
51    This will run the Lisp REPL. </LI>
52  <LI> At the REPL prompt, type:
53    <PRE>     CL-USER(1): (format t "Hello, world!")
54     Hello, world!
55     NIL
56</PRE>
57  </LI>
58  <LI> To exit the REPL, type:
59    <PRE>     CL-USER(2): (exit)
60</PRE>
61  </LI>
62</UL>
63<H1> ABCL <CODE>Cons</CODE> and <CODE>LispObject</CODE> classes </H1>
64<UL>
65  <LI><CODE>Cons</CODE>
66    <UL>
67      <LI>Corresponds to a Lisp cons or list </LI>
68      <LI> Has <CODE>car()</CODE> and <CODE>cdr()</CODE> methods if you want to write Java code in a Lisp style. </LI>
69      <LI> Can also unbox <CODE>Cons</CODE> objects into arrays, if you wish by using the <CODE>copyToArray()</CODE> method which returns <CODE>LispObject[]</CODE>. </LI>
70    </UL>
71  </LI>
72  <LI><CODE>LispObject</CODE> 
73    <UL>
74  <LI>A Lisp S-expression</LI>
75      <LI> Can unbox <CODE>LispObject</CODE>s to Java primitives with methods such as <CODE>intValue()</CODE> which returns (surprise!) an <CODE>int</CODE>. </LI>
76    </UL>
77  </LI>
78</UL>
79<H1>Other important ABCL classes </H1>
80All the classes below are in the <CODE>org.armedbear.lisp</CODE> package:
81<UL>
82  <LI> <CODE>Interpreter</CODE>
83    <UL>
84      <LI><CODE>createInstance()</CODE>: Creates a Lisp interpreter. </LI>
85      <LI><CODE>eval(String expression)</CODE>: Evaluates a Lisp expression. Often used with <CODE>load</CODE> to load a Lisp file.</LI>
86    </UL>
87  </LI>
88  <LI><CODE>Packages</CODE>
89    <UL>
90      <LI><CODE>findPackage(String packageName)</CODE>: Finds a Lisp package. </LI>
91    </UL>
92  </LI>
93  <LI> <CODE>Package</CODE>
94    <UL>
95      <LI><CODE> findAccessibleSymbol(String symbolName)</CODE>: Finds a symbol such as that for a function. </LI>
96    </UL>
97  </LI>
98  <LI> <CODE>Symbol</CODE>
99    <UL>
100      <LI> <CODE> getSymbolFunction()</CODE>: Returns the function for a corresponding symbol. </LI>
101    </UL>
102  </LI>
103  <LI> <CODE> Function </CODE>
104    <UL>
105      <LI> <CODE>execute()</CODE>: Executes a function taking a variable number of <CODE>LispObject</CODE>s as arguments. </LI>
106    </UL>
107  </LI>
108  <LI> <CODE>JavaObject</CODE>: A subclass of <CODE>LispObject</CODE> for objects coming from Java. </LI>
109</UL>
110<H1> Getting a Lisp package from Java </H1>
111<UL>
112  <LI> To load a file of Lisp functions from Java, you do the following:
113    <PRE>     Interpreter interpreter = Interpreter.createInstance();
114     interpreter.eval("(load \"my-lisp-code.lisp\")");
115</PRE>
116  </LI>
117  <LI> You can then load the package containing a function you want to call.&nbsp; In this case, our function is in the default Lisp package:
118    <PRE>     Package defaultPackage =
119          Packages.findPackage("CL-USER");
120</PRE>
121  </LI>
122</UL>
123<H1> Getting a Lisp function from Java </H1>
124<UL>
125  <LI> Suppose we have a function called <CODE>my-function</CODE> defined in <CODE>my-lisp-code.lisp </CODE>(which was loaded above). We obtain it in two steps like this:
126  <PRE>     Symbol myFunctionSym =
127          defaultPackage.findAccessibleSymbol(
128               "MY-FUNCTION");
129     Function myFunction =
130          myFunctionSym.getSymbolFunction();</PRE></LI>
131</UL>
132<H1> Calling a Lisp function from Java </H1>
133<UL>
134  <LI> Call a Lisp function like this:
135    <PRE>&nbsp;&nbsp;&nbsp;&nbsp; Cons list =
136&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; (Cons)&nbsp;myFunction.execute(
137&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Fixnum.getInstance(64),
138&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Fixnum.getInstance(64));
139</PRE>
140  </LI>
141  <LI> Our original Lisp function returned a list.&nbsp; ABCL's <CODE>Cons</CODE> Java class corresponds to a Lisp list.&nbsp; Note also that we wrap the <CODE>int</CODE>s (in this example) as <CODE>Fixnum</CODE>s. </LI>
142  <LI> On the Lisp side, we can access these integers  as if they came from directly from another Lisp method:
143    <PRE>&nbsp;&nbsp;&nbsp;&nbsp; (defun my-function (n1 n2)
144&nbsp;&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; ...)
145</PRE>
146  </LI>
147</UL>
148<H1> Converting Java objects to Lisp values and vice-versa</H1>
149<P>Since the user can't be expected to know how to map every Java type to Lisp and vice-versa, there are a couple<BR>
150  of nice methods you can use in all cases:</P>
151<UL>
152  <LI><CODE>public static LispObject JavaObject.getInstance(Object, boolean)</CODE>: Converts (or wraps) a Java object to a Lisp object, if the boolean is true (else it just wraps it in a <CODE>JavaObject</CODE>).</LI>
153  <LI><CODE>public Object LispObject.javaInstance()</CODE>: 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.</LI>
154</UL>
155<H1>
156Calling Java from Lisp
157</H1>
158<P>This code sample is by Ville Voutilainen.</P>
159<H2>Java code</H2>
160  <PRE>public class Main {
161    public int addTwoNumbers(int a, int b) {
162        return a + b;
163    }
164}
165</PRE>
166  See the entire code sample <A href="http://trac.common-lisp.net/armedbear/browser/trunk/abcl/examples/lisp-to-java/Main.java">here</A>.
167<H2>Lisp code</H2>
168<P>
169We need to get the
170</P>
171<OL>
172  <LI>
173class (<CODE>Main</CODE>)
174  </LI>
175  <LI>
176classes of the parameters (<CODE>int</CODE>)
177  </LI>
178  <LI>
179method reference (getting that requires the class of our object and the classes of the parameters)
180  </LI>
181  </OL>
182<P>
183After that we can invoke the function with <CODE>jcall</CODE>,
184giving the method reference, the object and the parameters.
185The result is a Lisp object (no need to do <CODE>jobject-lisp-value</CODE>,
186unless we invoke the method
187with <CODE>jcall-raw</CODE>).
188</P>
189<PRE>(defun void-function (param)
190  (let* ((class (jclass "Main"))
191         (intclass (jclass "int"))
192         (method (jmethod class "addTwoNumbers" intclass intclass))
193         (result (jcall method param 2 4)))
194    (format t "in void-function, result of calling addTwoNumbers(2, 4): ~a~%" result)))
195</PRE>
196  See the entire code sample <A href="http://trac.common-lisp.net/armedbear/browser/trunk/abcl/examples/lisp-to-java/lispfunctions.lisp">here</A>.
197<H1>Sample Code</H1>
198<UL>
199  <LI>
200  Code examples can be found <A href="http://trac.common-lisp.net/armedbear/browser/trunk/abcl/examples/">here</A>.
201  </LI>
202  <LI>Conway's Game of Life: This example shows how to call Lisp code from Java.
203<UL>
204  <LI> <A href="http://www.automatous-monk.com/jvmlanguages/abcl/life.lisp"><CODE>life.lisp</CODE></A>: Lisp code for simulating Conway's Game of Life cellular automaton. </LI>
205  <LI> <A href="http://www.automatous-monk.com/jvmlanguages/abcl/LifeGUI.java"><CODE>LifeGUI.java</CODE></A>: A subclass of JApplet for showing a Life universe. &nbsp;Calls <CODE>life.lisp</CODE> for all Life functionality. </LI>
206</UL>
207  </LI>
208</UL>
209<H1> References </H1>
210<UL>
211  <LI> <A href="http://common-lisp.net/project/armedbear/">Armed Bear Common Lisp website</A> </LI>
212  <LI><A href="http://gigamonkeys.com/book/">Practical Common Lisp by Peter Seibel</A></LI>
213  <LI> <A href="http://itunes.apple.com/WebObjects/MZStore.woa/wa/viewAlbum?id=192190026&s=143441"><I>Open Season</I> soundtrack by Paul Westerberg</A></LI>
214</UL>
215<HR>
216<P>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<A href="mailto:paul.reiners@gmail.com"> email me</A> with any suggestions or corrections.</P>
217<HR>
218<A rel="license" href="http://creativecommons.org/licenses/by-nc-sa/3.0/us/"><IMG alt="Creative Commons License" style="border-width:0" src="./abcl-user_files/88x31.png"></A><BR><SPAN xmlns:dc="http://purl.org/dc/elements/1.1/" href="http://purl.org/dc/dcmitype/Text" property="dc:title" rel="dc:type">Armed Bear Common Lisp Tutorial</SPAN> by <A xmlns:cc="http://creativecommons.org/ns#" href="./abcl-user_files/abcl-user.html" property="cc:attributionName" rel="cc:attributionURL">Paul Reiners</A> is licensed under a <A rel="license" href="http://creativecommons.org/licenses/by-nc-sa/3.0/us/">Creative Commons Attribution-Noncommercial-Share Alike 3.0 United States License</A>.  Code samples are released under the GNU General Public License.
219
220
221</BODY></HTML>
Note: See TracBrowser for help on using the repository browser.