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

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

Edit for more consistent voice.

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