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

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

More grinding out the manual.

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