source: public_html/doc/abcl-user.html

Last change on this file was 15275, checked in by Mark Evenson, 5 years ago

site: clean up HTML

Start moving all presentation logic into CSS.

Declare documents as polyglot HTML5/XHTML
<​https://dev.w3.org/html5/html-polyglot/html-polyglot.htm>.

Strip use SVN $Id$ expansion as this doesn't convey any useful
information to the actual reader of the page.
File size: 10.5 KB
Line 
1<!DOCTYPE html>
2<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
3<!-- saved from url=(0076)http://www.automatous-monk.com/jvmlanguages/abcl/Armed_Bear_Common_Lisp.html -->
4  <head>
5    <title>Armed Bear Common Lisp User Documentation</title>
6    <meta name="Description" content="Introductory user documentation on Armed Bear Common Lisp."/>
7    <meta charset="utf-8"/>
8    <link rel="stylesheet" type="text/css" href="abcl-css.css"/>
9  </head>
10<body>
11 <div class="header">
12   <h1>Armed Bear Common Lisp (ABCL) - User Documentation</h1>
13<H2> "It's the right to arm bears" Paul Westerberg </H2>
14 </div>
15<h1>Overview</h1>
16<UL>
17  <LI> Supports interoperability both ways between Java and Lisp. </LI>
18  <LI> ABCL is distributed under the GNU General Public License with Classpath exception.
19    <UL>
20      <LI>Basically this means you can use ABCL from your application without the need to make your own application open source.
21      </LI>
22    </UL>
23  </LI>
24</UL>
25<H1> Benefits of using ABCL </H1>
26<UL>
27  <LI> Java has great GUI libraries, <BR>
28    <CODE>&lt;religious-statement&gt;</CODE><BR>
29    &nbsp;&nbsp; &nbsp; but it's not the world's greatest programming language<BR>
30    <CODE>&lt;/religious-statement&gt;</CODE>. </LI>
31  <LI> <CODE>&lt;religious-statement&gt;</CODE><BR>
32    &nbsp;&nbsp; &nbsp;Lisp is the world's greatest programming language<BR>
33    <CODE>&lt;/religious-statement&gt;</CODE>,<BR>
34    but has no standard GUI libraries. </LI>
35  <LI> Therefore: Write great applications using Java for your front-end GUI backed with Lisp code and get the best of both worlds. </LI>
36</UL>
37<H1> Installing ABCL </H1>
38<UL>
39  <LI> Go to the <A href="https://abcl.org">ABCL page</A> and find the download link. </LI>
40  <LI> Download the Zip of the Latest Build. </LI>
41  <LI> Upzip the files. </LI>
42  <LI> Build according to instructions <A href="http://common-lisp.net/project/armedbear/doc/abcl-install-with-java.html">here</A>. </LI>
43  <LI> In the end, you will end up with a file called<BR>
44    <CODE>&nbsp;&nbsp;&nbsp;&nbsp; &lt;abcl-dir&gt;\dist\abcl.jar</CODE> </LI>
45  <LI> You will need to add <CODE>abcl.jar</CODE> to your class path for ABCL projects. </LI>
46  <LI> That's it! </LI>
47</UL>
48<H1> Hello, world! </H1>
49<UL>
50  <LI> Type the following at the command line (adjust the path as necessary):
51    <PRE>     C:\abcl-src-0.15.0&gt;cd dist
52     C:\abcl-src-0.15.0\dist&gt;java -jar abcl.jar
53</PRE>
54    This will run the Lisp REPL. </LI>
55  <LI> At the REPL prompt, type:
56    <PRE>     CL-USER(1): (format t "Hello, world!")
57     Hello, world!
58     NIL
59</PRE>
60  </LI>
61  <LI> To exit the REPL, type:
62    <PRE>     CL-USER(2): (exit)
63</PRE>
64  </LI>
65</UL>
66<H1> ABCL <CODE>Cons</CODE> and <CODE>LispObject</CODE> classes </H1>
67<UL>
68  <LI><CODE>Cons</CODE>
69    <UL>
70      <LI>Corresponds to a Lisp cons or list </LI>
71      <LI> Has <CODE>car()</CODE> and <CODE>cdr()</CODE> methods if you want to write Java code in a Lisp style. </LI>
72      <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>
73    </UL>
74  </LI>
75  <LI><CODE>LispObject</CODE> 
76    <UL>
77  <LI>A Lisp S-expression</LI>
78      <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>
79    </UL>
80  </LI>
81</UL>
82<H1>Other important ABCL classes </H1>
83All the classes below are in the <CODE>org.armedbear.lisp</CODE> package:
84<UL>
85  <LI> <CODE>Interpreter</CODE>
86    <UL>
87      <LI><CODE>createInstance()</CODE>: Creates a Lisp interpreter. </LI>
88      <LI><CODE>eval(String expression)</CODE>: Evaluates a Lisp expression. Often used with <CODE>load</CODE> to load a Lisp file.</LI>
89    </UL>
90  </LI>
91  <LI><CODE>Packages</CODE>
92    <UL>
93      <LI><CODE>findPackage(String packageName)</CODE>: Finds a Lisp package. </LI>
94    </UL>
95  </LI>
96  <LI> <CODE>Package</CODE>
97    <UL>
98      <LI><CODE> findAccessibleSymbol(String symbolName)</CODE>: Finds a symbol such as that for a function. </LI>
99    </UL>
100  </LI>
101  <LI> <CODE>Symbol</CODE>
102    <UL>
103      <LI> <CODE> getSymbolFunction()</CODE>: Returns the function for a corresponding symbol. </LI>
104    </UL>
105  </LI>
106  <LI> <CODE> Function </CODE>
107    <UL>
108      <LI> <CODE>execute()</CODE>: Executes a function taking a variable number of <CODE>LispObject</CODE>s as arguments. </LI>
109    </UL>
110  </LI>
111  <LI> <CODE>JavaObject</CODE>: A subclass of <CODE>LispObject</CODE> for objects coming from Java. </LI>
112</UL>
113<H1> Getting a Lisp package from Java </H1>
114<UL>
115  <LI> To load a file of Lisp functions from Java, you do the following:
116    <PRE>     Interpreter interpreter = Interpreter.createInstance();
117     interpreter.eval("(load \"my-lisp-code.lisp\")");
118</PRE>
119  </LI>
120  <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:
121    <PRE>     Package defaultPackage =
122          Packages.findPackage("CL-USER");
123</PRE>
124  </LI>
125</UL>
126<H1> Getting a Lisp function from Java </H1>
127<UL>
128  <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:
129  <PRE>     Symbol myFunctionSym =
130          defaultPackage.findAccessibleSymbol(
131               "MY-FUNCTION");
132     Function myFunction =
133          myFunctionSym.getSymbolFunction();</PRE></LI>
134</UL>
135<H1> Calling a Lisp function from Java </H1>
136<UL>
137  <LI> Call a Lisp function like this:
138    <PRE>&nbsp;&nbsp;&nbsp;&nbsp; Cons list =
139&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; (Cons)&nbsp;myFunction.execute(
140&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),
141&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));
142</PRE>
143  </LI>
144  <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>
145  <LI> On the Lisp side, we can access these integers  as if they came from directly from another Lisp method:
146    <PRE>&nbsp;&nbsp;&nbsp;&nbsp; (defun my-function (n1 n2)
147&nbsp;&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; ...)
148</PRE>
149  </LI>
150</UL>
151<H1> Converting Java objects to Lisp values and vice-versa</H1>
152<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>
153  of nice methods you can use in all cases:</P>
154<UL>
155  <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>
156  <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>
157</UL>
158<H1>
159Calling Java from Lisp
160</H1>
161<P>This code sample is by Ville Voutilainen.</P>
162<H2>Java code</H2>
163  <PRE>public class Main {
164    public int addTwoNumbers(int a, int b) {
165        return a + b;
166    }
167}
168</PRE>
169  See the entire code sample <A href="http://trac.common-lisp.net/armedbear/browser/trunk/abcl/examples/lisp-to-java/Main.java">here</A>.
170<H2>Lisp code</H2>
171<P>
172We need to get the
173</P>
174<OL>
175  <LI>
176class (<CODE>Main</CODE>)
177  </LI>
178  <LI>
179classes of the parameters (<CODE>int</CODE>)
180  </LI>
181  <LI>
182method reference (getting that requires the class of our object and the classes of the parameters)
183  </LI>
184  </OL>
185<P>
186After that we can invoke the function with <CODE>jcall</CODE>,
187giving the method reference, the object and the parameters.
188The result is a Lisp object (no need to do <CODE>jobject-lisp-value</CODE>,
189unless we invoke the method
190with <CODE>jcall-raw</CODE>).
191</P>
192<PRE>(defun void-function (param)
193  (let* ((class (jclass "Main"))
194         (intclass (jclass "int"))
195         (method (jmethod class "addTwoNumbers" intclass intclass))
196         (result (jcall method param 2 4)))
197    (format t "in void-function, result of calling addTwoNumbers(2, 4): ~a~%" result)))
198</PRE>
199  See the entire code sample <A href="http://trac.common-lisp.net/armedbear/browser/trunk/abcl/examples/lisp-to-java/lispfunctions.lisp">here</A>.
200<H1>Sample Code</H1>
201<UL>
202  <LI>
203  Code examples can be found <A href="http://trac.common-lisp.net/armedbear/browser/trunk/abcl/examples/">here</A>.
204  </LI>
205  <LI>Conway's Game of Life: This example shows how to call Lisp code from Java.
206<UL>
207  <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>
208  <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>
209</UL>
210  </LI>
211</UL>
212<H1> References </H1>
213<UL>
214  <LI> <A href="http://common-lisp.net/project/armedbear/">Armed Bear Common Lisp website</A> </LI>
215  <LI><A href="http://gigamonkeys.com/book/">Practical Common Lisp by Peter Seibel</A></LI>
216  <LI> <A href="https://musicbrainz.org/recording/985c53f8-c969-4bf0-a672-fbd2a8781a98"><I>Open Season</I> soundtrack by Paul Westerberg</A></LI>
217</UL>
218
219<hr/>
220
221  <p>
222    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.
223  </p>
224
225  <hr/>
226
227    <a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/3.0/us/">Creative Commons License</a>
228      <br/>
229      <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>
230      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.
231
232    <div class="footer">
233      <hr />
234      Hosted as part of <a href="https://common-lisp.net/">common-lisp.net</a></p>
235    </div>
236     
237</body>
238</html>
Note: See TracBrowser for help on using the repository browser.