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

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

Document running ABCL in the manual.

File size: 12.7 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'' exectuable needs to be in your
35path.
36
37To make it easier to faciliate 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
40simplly 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 occurance 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 what is documented here is subject to change. 
143
144\begin{itemize}
145\item All Lisp values are descendants of LispObject.java
146\item Lisp symbols are accessible via either directly referencing the
147  Symbol.java instance or by dynamically introspecting the
148  corresponding Package.java instance.
149\item The Lisp dynamic environment may be saved via
150  \code{LispThread.bindSpecial(Binding)} and restored via
151  \code{LispThread.resetSpecialBindings(Mark)}.
152\item Functions may be executed by invocation of the
153  Function.execute(args [...])
154\end{itemize}
155
156\subsection{Lisp FFI}
157
158FFI stands for "Foreign Function Interface" which is the phase which
159the contemporary Lisp world refers to methods of "calling out" from
160Lisp into "foreign" languages and environments.  This document
161describes the various ways that one interacts with Lisp world of ABCL
162from Java, considering the hosted Lisp as the "Foreign Function" that
163needs to be "Interfaced".
164
165\subsection{Calling Lisp from Java}
166
167Note: As the entire ABCL Lisp system resides in the org.armedbear.lisp
168package the following code snippets do not show the relevant import
169statements in the interest of brevity.  An example of the import
170statement would be
171
172\begin{listing-java}
173  import org.armedbear.lisp.*;
174\end{listing-java}
175
176to potentially import all the JVM symbol from the `org.armedbear.lisp'
177namespace.
178
179Per JVM, there can only ever be a single Lisp interpreter.  This is
180started by calling the static method `Interpreter.createInstance()`.
181
182\begin{listing-java}
183  Interpreter interpreter = Interpreter.createInstance();
184\end{listing-java}
185
186If this method has already been invoked in the lifetime of the current
187Java process it will return null, so if you are writing Java whose
188life-cycle is a bit out of your control (like in a Java servlet), a
189safer invocation pattern might be:
190
191\begin{code}[java]
192  Interpreter interpreter = Interpreter.getInstance();
193  if (interpreter == null) {
194    interpreter = Interpreter.createInstance();
195  }
196\end{code}
197
198The Lisp \code{eval} primitive may be simply passed strings for evaluation,
199as follows
200
201\begin{listing-java}
202  String line = "(load \"file.lisp\")";
203  LispObject result = interpreter.eval(line);
204\end{listing-java}
205
206Notice that all possible return values from an arbitrary Lisp
207computation are collapsed into a single return value.  Doing useful
208further computation on the ``LispObject'' depends on knowing what the
209result of the computation might be, usually involves some amount
210of \code{instanceof} introspection, and forms a whole topic to itself
211(c.f. [Introspecting a LispObject])
212
213Using \code{eval} involves the Lisp interpreter.  Lisp functions may
214be directly invoked by Java method calls as follows.  One simply
215locates the package containing the symbol, then obtains a reference to
216the symbol, and then invokes the \code{execute()} method with the
217desired parameters.
218
219\begin{listing-java}
220    interpreter.eval("(defun foo (msg) (format nil \"You told me '~A'~%\" msg))");
221    Package pkg = Packages.findPackage("CL-USER");
222    Symbol foo = pkg.findAccessibleSymbol("FOO");
223    Function fooFunction = (Function)foo.getSymbolFunction();
224    JavaObject parameter = new JavaObject("Lisp is fun!");
225    LispObject result = fooFunction.execute(parameter);
226    // How to get the "naked string value"?
227    System.out.println("The result was " + result.writeToString());
228\end{listing-java}
229
230If one is calling an primitive function in the CL package the syntax
231becomes considerably simpler if we can locate the instance of
232definition in the ABCL source, we can invoke the symbol directly.  To
233tell if a `LispObject` contains a reference to a symbol.
234
235\begin{listing-java}
236    boolean nullp(LispObject object) {
237      LispObject result = Primitives.NULL.execute(object);
238      if (result == NIL) {
239        return false;
240      }
241      return true;
242   }
243\end{listing-java}
244
245\subsubsection{Introspecting a LispObject}
246\label{topic:Introspecting a LispObject}
247
248We present various patterns for introspecting an an arbitrary
249`LispObject` which can represent the result of every Lisp evaluation
250into semantics that Java can meaniningfully deal with.
251
252\subsubsection{LispObject as \code{boolean}}
253
254If the LispObject a generalized boolean values, one can use
255\code{getBooleanValue()} to convert to Java:
256
257\begin{listing-java}
258     LispObject object = Symbol.NIL;
259     boolean javaValue = object.getBooleanValue();
260\end{listing-java}
261
262Although since in Lisp, any value other than NIL means "true", the
263use of Java equality it quite a bit easier and more optimal:
264
265\begin{listing-java}
266    boolean javaValue = (object != Symbol.NIL);
267\end{listing-java}
268
269\paragraph{LispObject is a list}
270
271If LispObject is a list, it will have the type `Cons`.  One can then use
272the \code{copyToArray} to make things a bit more suitable for Java
273iteration.
274
275\begin{listing-java}
276    LispObject result = interpreter.eval("'(1 2 4 5)");
277    if (result instanceof Cons) {
278      LispObject array[] = ((Cons)result.copyToArray());
279      ...
280    }
281\end{listing-java}
282   
283A more Lispy way to iterated down a list is to use the `cdr()` access
284function just as like one would traverse a list in Lisp:;
285
286\begin{listing-java}
287    LispObject result = interpreter.eval("'(1 2 4 5)");
288    while (result != Symbol.NIL) {
289      doSomething(result.car());
290      result = result.cdr();
291    }
292\end{listing-java}
293
294
295\section{Java}
296
297% include autogen docs for the JAVA package.
298\include{java}
299
300\section{Multithreading}
301
302% TODO document the THREADS package.
303\include{threads}
304
305\section{Extensions}
306
307The symbols in the EXTENSIONS package consititutes extensions to the
308ANSI standard that are potentially useful to the user.  They include
309functions for manipulating network sockets, running external programs,
310registering object finalizers, constructing reference weakly held by
311the garbage collector and others.
312
313\include{extensions}
314
315\chapter{Beyond ANSI}
316
317Naturally, in striving to be a useful contemporary Common Lisp
318implementation, ABCL endeavors to include extensions beyond the ANSI
319specification which are either widely adopted or are especially useful
320in working with the hosting JVM.
321
322\section{Extensions to CLOS}
323
324There is an additional syntax for specializing the parameter of a
325generic function on a java class, viz. \code{(java:jclass CLASS-STRING)}
326where \code{CLASS-STRING} is a string naming a Java class in dotted package
327form.
328
329For instance the following specialization would perhaps allow one to
330print more information about the contents of a java.util.Collection
331object
332
333\begin{listing-lisp}
334(defmethod print-object ((coll (java:jclass "java.util.Collection"))
335                         stream)
336  ;;; ...
337)
338\end{listing-lisp}
339
340If the class had been loaded via a classloader other than the original
341the class you wish to specialize on, one needs to specify the
342classloader as an optional third argument.
343
344\begin{listing-lisp}
345
346(defparameter *other-classloader*
347  (jcall "getBaseLoader" cl-user::*classpath-manager*))
348 
349(defmethod print-object ((device-id (java:jclass "dto.nbi.service.hdm.alcatel.com.NBIDeviceID" *other-classloader*))
350                         stream)
351  ;;; ...
352)
353\end{listing-lisp}
354
355\section{Extensions to the Reader}
356
357We implement a special hexadecimal escape sequence for specifying
358characters to the Lisp reader, namely we allow a sequences of the form
359\# \textbackslash Uxxxx to be processed by the reader as character whose code is
360specified by the hexadecimal digits ``xxxx''.  The hexadecimal sequence
361must be exactly four digits long, padded by leading zeros for values
362less than 0x1000.
363
364Note that this sequence is never output by the implementation.  Instead,
365the corresponding Unicode character is output for characters whose
366code is greater than 0x00ff.
367
368\chapter{History}
369
370ABCL was originally the extension language for the J editor, which was
371started in 1998 by Peter Graves.  Sometime in 2003, it seems that a
372lot of code that had previously not been released publically was
373suddenly committed that enabled ABCL to be plausibly termed an ANSI
374Common Lisp implementation. 
375
376In 2006, the implementation was transferred to the current
377maintainers, who have strived to improve its usability as a
378contemporary Common Lisp implementation.
379
380
381\end{document}
382
383% TODO
384%   1.  Create mechanism for swigging DocString and Lisp docs into
385%       sections.
386
Note: See TracBrowser for help on using the repository browser.