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

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

ispell buffer.

File size: 13.2 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
23\chapter{Running}
24
25ABCL is packaged as a single jar file (usually named either
26``abcl.jar'' or something like``abcl-0.27.1.jar'' if you are using a
27versioned package) that can be executed under the
28control of a suitable JVM as follows
29
30\begin{listing-shell}
31  cmd\$ java -jar abcl.jar
32\end{listing-shell}
33
34For this command to work, the ``java'' executable needs to be in your
35path.
36
37To make it easier to facilitate the use of ABCL in tool chains (such as
38SLIME) the invocation is wrapped in a Bourne shell script under UNIX
39or a DOS command script under Windows so that ABCL may be executed
40simply as:
41
42\begin{listing-shell}
43  cmd\$ abcl
44\end{listing-shell}
45
46\section{Options}
47
48ABCL supports the following options:
49
50\begin{verbatim}
51--help
52    Displays this message.
53--noinform
54    Suppresses the printing of startup information and banner.
55--noinit
56    Suppresses the loading of the '~/.abclrc' startup file.
57--nosystem
58    Suppresses loading the 'system.lisp' customization file.
59--eval <FORM>
60    Evaluates the <FORM> before initializing REPL.
61--load <FILE>
62    Loads the file <FILE> before initializing REPL.
63--load-system-file <FILE>
64    Loads the system file <FILE> before initializing REPL.
65--batch
66    The process evaluates forms specified by arguments and possibly by those
67    by those in the intialization file '~/.abcl', and then exits.
68
69The occurance of '--' copies the remaining arguments, unprocessed, into
70the variable EXTENSIONS:*COMMAND-LINE-ARGUMENT-LIST*.
71\end{verbatim}
72
73All of the command line arguments which follow the occurrence of ``--''
74are passed into a list bound to the EXT:*COMMAND-LINE-ARGUMENT-LIST*
75variable.
76
77\section{Initialization}
78
79If the ABCL process is started without the ``--noinit'' flag, it
80attempts to load a file named ``.abclrc'' located in the user's home
81directory and then interpret its contents. 
82
83The user's home directory is determined by the value of the JVM system
84property ``user.home''.
85
86\chapter{Conformance}
87
88\section{ANSI Common Lisp}
89ABCL is currently a non-conforming ANSI Common Lisp implementation due
90to the following (known) issues:
91
92\begin{itemize}
93  \item Lack of long form of DEFINE-METHOD-COMBINATION
94  \item Missing statement of conformance in accompanying documentation
95\end{itemize}
96
97ABCL aims to be be a fully conforming ANSI Common Lisp
98implementation.  Any other behavior should be reported as a bug.
99
100\section{Contemporary Common Lisp}
101In addition to ANSI conformance, ABCL strives to implement features
102expected of a contemporary Common Lisp.
103\begin{itemize}
104  \item Incomplete MOP
105    % N.B.
106    % TODO go through AMOP with symbols, starting by looking for
107    % matching function signature.
108    % XXX is this really blocking ANSI conformance?  Answer: we have
109    % to start with such a ``census'' to determine what we have.
110  \item Incomplete Gray Streams
111\end{itemize}
112
113\chapter{Interaction with host JVM}
114
115% describe calling Java from Lisp, and calling Lisp from Java,
116% probably in two separate sections.  Presumably, we can partition our
117% audience into those who are more comfortable with Java, and those
118% that are more comforable with Lisp
119
120\section{Lisp to Java}
121
122ABCL offers a number of mechanisms to manipulate Java libraries from
123Lisp.
124
125\begin{itemize}
126\item Java values are accessible as objects of type JAVA:JAVA-OBJECT.
127\item The Java FFI presents a Lisp package (JAVA) with many useful
128  symbols for manipulating the artifacts of expectation on the JVM,
129  including creation of new objects \ref{JAVA:JNEW}, \ref{JAVA:JMETHOD}), the
130  introspection of values \ref{JAVA:JFIELD}, the execution of methods
131  (\ref{JAVA:JCALL}, \ref{JAVA:JCALL-RAW}, \ref{JAVA:JSTATIC})
132\item The JSS package (\ref{JSS}) in contrib introduces a convenient macro
133  syntax \ref{JSS:SHARPSIGN_DOUBLEQUOTE_MACRO} for accessing Java
134  methods, and additional convenience functions.
135\item Java classes and libraries may be dynamically added to the
136  classpath at runtime (JAVA:ADD-TO-CLASSPATH).
137\end{itemize}
138
139\section{Lisp from Java}
140
141Manipulation of the Lisp API is currently lacking a stable interface,
142so the following documented interfaces are subject to change with
143notice:
144
145\begin{itemize}
146\item All Lisp values are descendants of LispObject.java
147\item Lisp symbols are accessible via either directly referencing the
148  Symbol.java instance or by dynamically introspecting the
149  corresponding Package.java instance.
150\item The Lisp dynamic environment may be saved via
151  \code{LispThread.bindSpecial(Binding)} and restored via
152  \code{LispThread.resetSpecialBindings(Mark)}.
153\item Functions may be executed by invocation of the
154  Function.execute(args [...])
155\end{itemize}
156
157\subsection{Lisp FFI}
158
159FFI stands for "Foreign Function Interface" which is the phase which
160the contemporary Lisp world refers to methods of "calling out" from
161Lisp into "foreign" languages and environments.  This document
162describes the various ways that one interacts with Lisp world of ABCL
163from Java, considering the hosted Lisp as the "Foreign Function" that
164needs to be "Interfaced".
165
166\subsection{Calling Lisp from Java}
167
168Note: As the entire ABCL Lisp system resides in the org.armedbear.lisp
169package the following code snippets do not show the relevant import
170statements in the interest of brevity.  An example of the import
171statement would be
172
173\begin{listing-java}
174  import org.armedbear.lisp.*;
175\end{listing-java}
176
177to potentially import all the JVM symbol from the `org.armedbear.lisp'
178namespace.
179
180Per JVM, there can only ever be a single Lisp interpreter.  This is
181started by calling the static method `Interpreter.createInstance()`.
182
183\begin{listing-java}
184  Interpreter interpreter = Interpreter.createInstance();
185\end{listing-java}
186
187If this method has already been invoked in the lifetime of the current
188Java process it will return null, so if you are writing Java whose
189life-cycle is a bit out of your control (like in a Java servlet), a
190safer invocation pattern might be:
191
192\begin{code}[java]
193  Interpreter interpreter = Interpreter.getInstance();
194  if (interpreter == null) {
195    interpreter = Interpreter.createInstance();
196  }
197\end{code}
198
199The Lisp \code{eval} primitive may be simply passed strings for evaluation,
200as follows
201
202\begin{listing-java}
203  String line = "(load \"file.lisp\")";
204  LispObject result = interpreter.eval(line);
205\end{listing-java}
206
207Notice that all possible return values from an arbitrary Lisp
208computation are collapsed into a single return value.  Doing useful
209further computation on the ``LispObject'' depends on knowing what the
210result of the computation might be, usually involves some amount
211of \code{instanceof} introspection, and forms a whole topic to itself
212(c.f. [Introspecting a LispObject])
213
214Using \code{eval} involves the Lisp interpreter.  Lisp functions may
215be directly invoked by Java method calls as follows.  One simply
216locates the package containing the symbol, then obtains a reference to
217the symbol, and then invokes the \code{execute()} method with the
218desired parameters.
219
220\begin{listing-java}
221    interpreter.eval("(defun foo (msg) (format nil \"You told me '~A'~%\" msg))");
222    Package pkg = Packages.findPackage("CL-USER");
223    Symbol foo = pkg.findAccessibleSymbol("FOO");
224    Function fooFunction = (Function)foo.getSymbolFunction();
225    JavaObject parameter = new JavaObject("Lisp is fun!");
226    LispObject result = fooFunction.execute(parameter);
227    // How to get the "naked string value"?
228    System.out.println("The result was " + result.writeToString());
229\end{listing-java}
230
231If one is calling an primitive function in the CL package the syntax
232becomes considerably simpler if we can locate the instance of
233definition in the ABCL source, we can invoke the symbol directly.  To
234tell if a `LispObject` contains a reference to a symbol.
235
236\begin{listing-java}
237    boolean nullp(LispObject object) {
238      LispObject result = Primitives.NULL.execute(object);
239      if (result == NIL) {
240        return false;
241      }
242      return true;
243   }
244\end{listing-java}
245
246\subsubsection{Introspecting a LispObject}
247\label{topic:Introspecting a LispObject}
248
249We present various patterns for introspecting an an arbitrary
250`LispObject` which can represent the result of every Lisp evaluation
251into semantics that Java can meaningfully deal with.
252
253\subsubsection{LispObject as \code{boolean}}
254
255If the LispObject a generalized boolean values, one can use
256\code{getBooleanValue()} to convert to Java:
257
258\begin{listing-java}
259     LispObject object = Symbol.NIL;
260     boolean javaValue = object.getBooleanValue();
261\end{listing-java}
262
263Although since in Lisp, any value other than NIL means "true", the
264use of Java equality it quite a bit easier and more optimal:
265
266\begin{listing-java}
267    boolean javaValue = (object != Symbol.NIL);
268\end{listing-java}
269
270\paragraph{LispObject is a list}
271
272If LispObject is a list, it will have the type `Cons`.  One can then use
273the \code{copyToArray} to make things a bit more suitable for Java
274iteration.
275
276\begin{listing-java}
277    LispObject result = interpreter.eval("'(1 2 4 5)");
278    if (result instanceof Cons) {
279      LispObject array[] = ((Cons)result.copyToArray());
280      ...
281    }
282\end{listing-java}
283   
284A more Lispy way to iterated down a list is to use the `cdr()` access
285function just as like one would traverse a list in Lisp:;
286
287\begin{listing-java}
288    LispObject result = interpreter.eval("'(1 2 4 5)");
289    while (result != Symbol.NIL) {
290      doSomething(result.car());
291      result = result.cdr();
292    }
293\end{listing-java}
294
295
296\section{Java}
297
298% include autogen docs for the JAVA package.
299\include{java}
300
301\section{Multithreading}
302
303% TODO document the THREADS package.
304\include{threads}
305
306\section{Extensions}
307
308The symbols in the EXTENSIONS package constitutes extensions to the
309ANSI standard that are potentially useful to the user.  They include
310functions for manipulating network sockets, running external programs,
311registering object finalizers, constructing reference weakly held by
312the garbage collector and others.
313
314See \ref{Extensible Sequences} for a generic function interface to
315the native JVM contract for \code{java.util.List}.
316
317\include{extensions}
318
319\chapter{Beyond ANSI}
320
321Naturally, in striving to be a useful contemporary Common Lisp
322implementation, ABCL endeavors to include extensions beyond the ANSI
323specification which are either widely adopted or are especially useful
324in working with the hosting JVM.
325
326\section{Extensible Sequences}
327
328
329\ref{RHODES2007}
330
331The SEQUENCE pacakge fully implements Christopher Rhodes' proposal for
332extensible sequences.  These user extensible sequences are used
333directly in \code{java-collections.lisp} provide these CLOS
334abstractions on the standard Java collection classes as defined by the
335\code{java.util.List} contract.
336
337
338\section{Extensions to CLOS}
339
340There is an additional syntax for specializing the parameter of a
341generic function on a java class, viz. \code{(java:jclass CLASS-STRING)}
342where \code{CLASS-STRING} is a string naming a Java class in dotted package
343form.
344
345For instance the following specialization would perhaps allow one to
346print more information about the contents of a java.util.Collection
347object
348
349\begin{listing-lisp}
350(defmethod print-object ((coll (java:jclass "java.util.Collection"))
351                         stream)
352  ;;; ...
353)
354\end{listing-lisp}
355
356If the class had been loaded via a classloader other than the original
357the class you wish to specialize on, one needs to specify the
358classloader as an optional third argument.
359
360\begin{listing-lisp}
361
362(defparameter *other-classloader*
363  (jcall "getBaseLoader" cl-user::*classpath-manager*))
364 
365(defmethod print-object ((device-id (java:jclass "dto.nbi.service.hdm.alcatel.com.NBIDeviceID" *other-classloader*))
366                         stream)
367  ;;; ...
368)
369\end{listing-lisp}
370
371\section{Extensions to the Reader}
372
373We implement a special hexadecimal escape sequence for specifying
374characters to the Lisp reader, namely we allow a sequences of the form
375\# \textbackslash Uxxxx to be processed by the reader as character whose code is
376specified by the hexadecimal digits ``xxxx''.  The hexadecimal sequence
377must be exactly four digits long, padded by leading zeros for values
378less than 0x1000.
379
380Note that this sequence is never output by the implementation.  Instead,
381the corresponding Unicode character is output for characters whose
382code is greater than 0x00ff.
383
384\chapter{History}
385
386ABCL was originally the extension language for the J editor, which was
387started in 1998 by Peter Graves.  Sometime in 2003, it seems that a
388lot of code that had previously not been released publically was
389suddenly committed that enabled ABCL to be plausibly termed an ANSI
390Common Lisp implementation. 
391
392In 2006, the implementation was transferred to the current
393maintainers, who have strived to improve its usability as a
394contemporary Common Lisp implementation.
395
396
397\end{document}
398
399% TODO
400%   1.  Create mechanism for swigging DocString and Lisp docs into
401%       sections.
402
Note: See TracBrowser for help on using the repository browser.