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

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

Clarify PATHNAME class hierarchy.

File size: 16.5 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 the proceeding command to work, the ``java'' executable needs
36to be in your path.
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 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\chapter{Implementation Dependent Extensions}
307
308As outlined by the CLHS ANSI conformance guidelines, we document the
309extensions to the Armed Bear Lisp implementation made accessible to
310the user by virtue of being an exported symbol in the JAVA, THREADS,
311or EXTENSIONS packages.
312
313\section{JAVA}
314
315\subsection{Modifying the JVM CLASSPATH}
316
317The JAVA:ADD-TO-CLASSPATH generic functions allows one to add the
318specified pathname or list of pathnames to the current JVM classpath
319allowing the dynamic loading of JVM objects:
320
321\begin{listing-lisp}
322CL-USER> (add-to-classpath "/path/to/some.jar")
323\end{listing-lisp}p
324
325\subsection{API}
326
327% include autogen docs for the JAVA package.
328\include{java}
329
330\section{THREADS}
331
332Multithreading
333
334\subsection{API}
335
336% TODO document the THREADS package.
337\include{threads}
338
339\section{EXTENSIONS}
340
341The symbols in the EXTENSIONS package (nicknamed ``EXT'') constitutes
342extensions to the ANSI standard that are potentially useful to the
343user.  They include functions for manipulating network sockets,
344running external programs, registering object finalizers, constructing
345reference weakly held by the garbage collector and others.
346
347See \ref{Extensible Sequences} for a generic function interface to
348the native JVM contract for \code{java.util.List}.
349
350\subsection{API}
351
352\include{extensions}
353
354\chapter{Beyond ANSI}
355
356Naturally, in striving to be a useful contemporary Common Lisp
357implementation, ABCL endeavors to include extensions beyond the ANSI
358specification which are either widely adopted or are especially useful
359in working with the hosting JVM.
360
361\section{Implementation Dependent}
362\begin{enumerate}
363  \item Compiler to JVM 5 bytecode
364  \item Pathname extensionsn
365\end{enumerate}
366
367\section{Pathname}
368
369We implment an extension to the Pathname that allows for the
370description and retrieval of resources named in a URI scheme that the
371JVM ``understands''.  Support is built-in to the ``http'' and
372``https'' implementations but additional protocol handlers may be
373installed at runtime by having JVM symbols present in the
374sun.net.protocol.dynmamic pacakge. See [JAVA2006] for more details.
375
376ABCL has created specializations of the ANSI Pathname object to
377enable to use of URIs to address dynamically loaded resources for the
378JVM.  A URL-PATHNAME has a corresponding URL whose cannoical
379representation is defined to be the NAMESTRING of the Pathname.
380
381PATHNAME : URL-PATHNAME : JAR-PATHNAME
382
383Both URL-PATHNAME and JAR-PATHNAME may be used anu where will a
384PATHNAME is accepted witht the following caveats
385
386A stream obtained via OPEN on a URL-PATHNAME cannot be the target of
387write operations.
388
389No canonicalization is performed on the underlying URI (i.e. the
390implementation does not attempt to compute the current name of the
391representing resource unless it is requested to be resolved.)  Upon
392resolution, any cannoicalization procedures followed in resolving the
393resource (e.g. following redirects) are discarded. 
394
395The implementation of URL-PATHNAME allows the ABCL user to laod dynamically
396code from the network.  For example, for Quicklisp.
397
398\begin{listing-lisp}
399  CL-USER> (load "http://beta.quicklisp.org/quicklisp.lisp")
400\end{listing-lisp}
401
402will load and execute the Quicklisp setup code.
403
404\ref{XACH2011}
405         
406\section{Extensible Sequences}
407
408\ref{RHODES2007}
409
410The SEQUENCE pacakge fully implements Christopher Rhodes' proposal for
411extensible sequences.  These user extensible sequences are used
412directly in \code{java-collections.lisp} provide these CLOS
413abstractions on the standard Java collection classes as defined by the
414\code{java.util.List} contract.
415
416
417\section{Extensions to CLOS}
418
419There is an additional syntax for specializing the parameter of a
420generic function on a java class, viz. \code{(java:jclass CLASS-STRING)}
421where \code{CLASS-STRING} is a string naming a Java class in dotted package
422form.
423
424For instance the following specialization would perhaps allow one to
425print more information about the contents of a java.util.Collection
426object
427
428\begin{listing-lisp}
429(defmethod print-object ((coll (java:jclass "java.util.Collection"))
430                         stream)
431  ;;; ...
432)
433\end{listing-lisp}
434
435If the class had been loaded via a classloader other than the original
436the class you wish to specialize on, one needs to specify the
437classloader as an optional third argument.
438
439\begin{listing-lisp}
440
441(defparameter *other-classloader*
442  (jcall "getBaseLoader" cl-user::*classpath-manager*))
443 
444(defmethod print-object ((device-id (java:jclass "dto.nbi.service.hdm.alcatel.com.NBIDeviceID" *other-classloader*))
445                         stream)
446  ;;; ...
447)
448\end{listing-lisp}
449
450\section{Extensions to the Reader}
451
452We implement a special hexadecimal escape sequence for specifying
453characters to the Lisp reader, namely we allow a sequences of the form
454\# \textbackslash Uxxxx to be processed by the reader as character whose code is
455specified by the hexadecimal digits ``xxxx''.  The hexadecimal sequence
456must be exactly four digits long, padded by leading zeros for values
457less than 0x1000.
458
459Note that this sequence is never output by the implementation.  Instead,
460the corresponding Unicode character is output for characters whose
461code is greater than 0x00ff.
462
463\chapter{History}
464
465ABCL was originally the extension language for the J editor, which was
466started in 1998 by Peter Graves.  Sometime in 2003, it seems that a
467lot of code that had previously not been released publically was
468suddenly committed that enabled ABCL to be plausibly termed an ANSI
469Common Lisp implementation. 
470
471In 2006, the implementation was transferred to the current
472maintainers, who have strived to improve its usability as a
473contemporary Common Lisp implementation.
474
475In 201x, with the publication of this Manual explicitly stating the
476conformance of Armed Bear Common Lisp to ANSI, we release abcl-1.0.
477
478\section{References}
479
480[Java2000]:  A New Era for Java Protocol Handlers.
481\url{http://java.sun.com/developer/onlineTraining/protocolhandlers/}
482
483[Xach2011]:  Quicklisp:  A system for quickly constructing Common Lisp
484libraries.  \url{http://www.quicklisp.org/}
485
486
487\end{document}
488
489% TODO
490%   1.  Create mechanism for swigging DocString and Lisp docs into
491%       sections.
492
Note: See TracBrowser for help on using the repository browser.