source: trunk/abcl/doc/manual/abcl.tex @ 13438

Last change on this file since 13438 was 13438, checked in by Mark Evenson, 10 years ago

Manual renders to pdf via pdflatex.

File size: 10.8 KB
Line 
1% -*- mode: latex; -*-
2% http://en.wikibooks.org/wiki/LaTeX/
3\documentclass[10pt]{book}
4\usepackage{abcl}
5
6\begin{document}
7\title{A Manual for Armed Bear Common Lisp}
8\date{August 4, 2011}
9\author{Mark~Evenson, Erik~Huelsmann, Alessio~Stallo, Ville~Voutilainen}
10
11\maketitle
12
13\chapter{Introduction}
14
15Armed Bear is a mostly conforming implementation of the ANSI Common
16Lisp standard.  This manual documents the Armed Bear Common Lisp
17implementation for users of the system.
18
19\subsection{Version}
20This manual corresponds to abcl-0.27.0, as yet unreleased.
21
22\chapter{Conformance}
23
24
25\section{ANSI Common Lisp}
26ABCL is currently a non-conforming ANSI Common Lisp implementation due
27to the following (known) issues:
28
29\begin{itemize}
30  \item Lack of long form of DEFINE-METHOD-COMBINATION
31  \item Missing statement of conformance in accompanying documentation
32\end{itemize}
33
34ABCL aims to be be a fully conforming ANSI Common Lisp
35implementation.  Any other behavior should be reported as a bug.
36
37\section{Contemporary Common Lisp}
38In addition to ANSI conformance, ABCL strives to implement features
39expected of a contemporary Common Lisp.
40\begin{itemize}
41  \item Incomplete MOP
42    % N.B.
43    % TODO go through AMOP with symbols, starting by looking for
44    % matching function signature.
45    % XXX is this really blocking ANSI conformance?  Answer: we have
46    % to start with such a ``census'' to determine what we have.
47  \item Incomplete Gray Streams
48\end{itemize}
49
50\chapter{Interaction with host JVM}
51
52% describe calling Java from Lisp, and calling Lisp from Java,
53% probably in two separate sections.  Presumably, we can partition our
54% audience into those who are more comfortable with Java, and those
55% that are more comforable with Lisp
56
57\section{Lisp to Java}
58
59ABCL offers a number of mechanisms to manipulate Java libraries from
60Lisp.
61
62\begin{itemize}
63\item Java values are accessible as objects of type JAVA:JAVA-OBJECT.
64\item The Java FFI presents a Lisp package (JAVA) with many useful
65  symbols for manipulating the artifacts of expectation on the JVM,
66  including creation of new objects \ref{JAVA:JNEW}, \ref{JAVA:JMETHOD}), the
67  introspection of values \ref{JAVA:JFIELD}, the execution of methods
68  (\ref{JAVA:JCALL}, \ref{JAVA:JCALL-RAW}, \ref{JAVA:JSTATIC})
69\item The JSS package (\ref{JSS}) in contrib introduces a convenient macro
70  syntax \ref{JSS:SHARPSIGN_DOUBLEQUOTE_MACRO} for accessing Java
71  methods, and additional convenience functions.
72\item Java classes and libraries may be dynamically added to the
73  classpath at runtime (JAVA:ADD-TO-CLASSPATH).
74\end{itemize}
75
76\section{Lisp from Java}
77
78Manipulation of the Lisp API is currently lacking a stable interface,
79so what is documented here is subject to change. 
80
81\begin{itemize}
82\item All Lisp values are descendants of LispObject.java
83\item Lisp symbols are accessible via either directly referencing the
84  Symbol.java instance or by dynamically introspecting the
85  corresponding Package.java instance.
86\item The Lisp dynamic environment may be saved via
87  \code{LispThread.bindSpecial(Binding)} and restored via
88  \code{LispThread.resetSpecialBindings(Mark)}.
89\item Functions may be executed by invocation of the
90  Function.execute(args [...])
91\end{itemize}
92
93\subsection{Lisp FFI}
94
95FFI stands for "Foreign Function Interface" which is the phase which
96the contemporary Lisp world refers to methods of "calling out" from
97Lisp into "foreign" languages and environments.  This document
98describes the various ways that one interacts with Lisp world of ABCL
99from Java, considering the hosted Lisp as the "Foreign Function" that
100needs to be "Interfaced".
101
102\subsection{Calling Lisp from Java}
103
104Note: As the entire ABCL Lisp system resides in the org.armedbear.lisp
105package the following code snippets do not show the relevant import
106statements in the interest of brevity.  An example of the import
107statement would be
108
109\begin{listing-java}
110  import org.armedbear.lisp.*;
111\end{listing-java}
112
113to potentially import all the JVM symbol from the `org.armedbear.lisp'
114namespace.
115
116Per JVM, there can only ever be a single Lisp interpreter.  This is
117started by calling the static method `Interpreter.createInstance()`.
118
119\begin{listing-java}
120  Interpreter interpreter = Interpreter.createInstance();
121\end{listing-java}
122
123If this method has already been invoked in the lifetime of the current
124Java process it will return null, so if you are writing Java whose
125life-cycle is a bit out of your control (like in a Java servlet), a
126safer invocation pattern might be:
127
128\begin{code}[java]
129  Interpreter interpreter = Interpreter.getInstance();
130  if (interpreter == null) {
131    interpreter = Interpreter.createInstance();
132  }
133\end{code}
134
135The Lisp \code{eval} primitive may be simply passed strings for evaluation,
136as follows
137
138\begin{listing-java}
139  String line = "(load \"file.lisp\")";
140  LispObject result = interpreter.eval(line);
141\end{listing-java}
142
143Notice that all possible return values from an arbitrary Lisp
144computation are collapsed into a single return value.  Doing useful
145further computation on the ``LispObject'' depends on knowing what the
146result of the computation might be, usually involves some amount
147of \code{instanceof} introspection, and forms a whole topic to itself
148(c.f. [Introspecting a LispObject])
149
150Using \code{eval} involves the Lisp interpreter.  Lisp functions may
151be directly invoked by Java method calls as follows.  One simply
152locates the package containing the symbol, then obtains a reference to
153the symbol, and then invokes the \code{execute()} method with the
154desired parameters.
155
156\begin{listing-java}
157    interpreter.eval("(defun foo (msg) (format nil \"You told me '~A'~%\" msg))");
158    Package pkg = Packages.findPackage("CL-USER");
159    Symbol foo = pkg.findAccessibleSymbol("FOO");
160    Function fooFunction = (Function)foo.getSymbolFunction();
161    JavaObject parameter = new JavaObject("Lisp is fun!");
162    LispObject result = fooFunction.execute(parameter);
163    // How to get the "naked string value"?
164    System.out.println("The result was " + result.writeToString());
165\end{listing-java}
166
167If one is calling an primitive function in the CL package the syntax
168becomes considerably simpler if we can locate the instance of
169definition in the ABCL source, we can invoke the symbol directly.  To
170tell if a `LispObject` contains a reference to a symbol.
171
172\begin{listing-java}
173    boolean nullp(LispObject object) {
174      LispObject result = Primitives.NULL.execute(object);
175      if (result == NIL) {
176        return false;
177      }
178      return true;
179   }
180\end{listing-java}
181
182\subsubsection{Introspecting a LispObject}
183\label{topic:Introspecting a LispObject}
184
185We present various patterns for introspecting an an arbitrary
186`LispObject` which can represent the result of every Lisp evaluation
187into semantics that Java can meaniningfully deal with.
188
189\subsubsection{LispObject as \code{boolean}}
190
191If the LispObject a generalized boolean values, one can use
192\code{getBooleanValue()} to convert to Java:
193
194\begin{listing-java}
195     LispObject object = Symbol.NIL;
196     boolean javaValue = object.getBooleanValue();
197\end{listing-java}
198
199Although since in Lisp, any value other than NIL means "true", the
200use of Java equality it quite a bit easier and more optimal:
201
202\begin{listing-java}
203    boolean javaValue = (object != Symbol.NIL);
204\end{listing-java}
205
206\paragraph{LispObject is a list}
207
208If LispObject is a list, it will have the type `Cons`.  One can then use
209the \code{copyToArray} to make things a bit more suitable for Java
210iteration.
211
212\begin{listing-java}
213    LispObject result = interpreter.eval("'(1 2 4 5)");
214    if (result instanceof Cons) {
215      LispObject array[] = ((Cons)result.copyToArray());
216      ...
217    }
218\end{listing-java}
219   
220A more Lispy way to iterated down a list is to use the `cdr()` access
221function just as like one would traverse a list in Lisp:;
222
223\begin{listing-java}
224    LispObject result = interpreter.eval("'(1 2 4 5)");
225    while (result != Symbol.NIL) {
226      doSomething(result.car());
227      result = result.cdr();
228    }
229\end{listing-java}
230
231
232\section{Java}
233
234% include autogen docs for the JAVA package.
235\include{java}
236
237\section{Multithreading}
238
239% TODO document the THREADS package.
240\include{threads}
241
242\section{Extensions}
243
244The symbols in the EXTENSIONS package consititutes extensions to the
245ANSI standard that are potentially useful to the user.  They include
246functions for manipulating network sockets, running external programs,
247registering object finalizers, constructing reference weakly held by
248the garbage collector and others.
249
250\include{extensions}
251
252\chapter{Beyond ANSI}
253
254Naturally, in striving to be a useful contemporary Common Lisp
255implementation, ABCL endeavors to include extensions beyond the ANSI
256specification which are either widely adopted or are especially useful
257in working with the hosting JVM.
258
259\section{Extensions to CLOS}
260
261There is an additional syntax for specializing the parameter of a
262generic function on a java class, viz. \code{(java:jclass CLASS-STRING)}
263where \code{CLASS-STRING} is a string naming a Java class in dotted package
264form.
265
266For instance the following specialization would perhaps allow one to
267print more information about the contents of a java.util.Collection
268object
269
270\begin{listing-lisp}
271(defmethod print-object ((coll (java:jclass "java.util.Collection"))
272                         stream)
273  ;;; ...
274)
275\end{listing-lisp}
276
277If the class had been loaded via a classloader other than the original
278the class you wish to specialize on, one needs to specify the
279classloader as an optional third argument.
280
281\begin{listing-lisp}
282
283(defparameter *other-classloader*
284  (jcall "getBaseLoader" cl-user::*classpath-manager*))
285 
286(defmethod print-object ((device-id (java:jclass "dto.nbi.service.hdm.alcatel.com.NBIDeviceID" *other-classloader*))
287                         stream)
288  ;;; ...
289)
290\end{listing-lisp}
291
292\section{Extensions to the Reader}
293
294We implement a special hexadecimal escape sequence for specifying
295characters to the Lisp reader, namely we allow a sequences of the form
296\# \textbackslash Uxxxx to be processed by the reader as character whose code is
297specified by the hexadecimal digits ``xxxx''.  The hexadecimal sequence
298must be exactly four digits long, padded by leading zeros for values
299less than 0x1000.
300
301Note that this sequence is never output by the implementation.  Instead,
302the corresponding Unicode character is output for characters whose
303code is greater than 0x00ff.
304
305\chapter{History}
306
307ABCL was originally the extension language for the J editor, which was
308started in 1998 by Peter Graves.  Sometime in 2003, it seems that a
309lot of code that had previously not been released publically was
310suddenly committed that enabled ABCL to be plausibly termed an ANSI
311Common Lisp implementation. 
312
313In 2006, the implementation was transferred to the current
314maintainers, who have strived to improve its usability as a
315contemporary Common Lisp implementation.
316
317
318\end{document}
319
320% TODO
321%   1.  Create mechanism for swigging DocString and Lisp docs into
322%       sections.
323
Note: See TracBrowser for help on using the repository browser.