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

Last change on this file since 14885 was 14885, checked in by mevenson, 12 months ago

Remove ASDF-INSTALL from ABCL-CONTRIB

The Quicklisp library manager has superseded all plausible use of
ADSF-INSTALL at this historical moment.

File size: 59.2 KB
Line 
1% -*- mode: latex; -*-
2% http://en.wikibooks.org/wiki/LaTeX/
3\documentclass[10pt]{book}
4\usepackage{abcl}
5
6\usepackage{hyperref} % Put this one last, it redefines lots of internals
7
8
9\begin{document}
10\title{Armed Bear Common Lisp User Manual}
11\date{Version 1.4.0-dev\\
12\smallskip
13April 2015}
14\author{Mark Evenson \and Erik H\"{u}lsmann \and Rudolf Schlatte \and
15  Alessio Stalla \and Ville Voutilainen}
16
17\maketitle
18
19\tableofcontents
20%%Preface to the Fourth edition, abcl-1.3.
21\subsection{Preface to the Fourth Edition}
22
23\textsc{ABCL} 1.3 now implements an optimized implementation of the
24LispStack abstraction thanks to Dmitry Nadezhin which runs on ORCL
25JVMs from 1.[5-8] conformantly.
26
27%%Preface to the Third edition, abcl-1.2.
28\subsection{Preface to the Third Edition}
29The implementation now contains a performant and conformant
30implementation of (A)MOP to the point of inclusion in CLOSER-MOP's
31test suite.
32
33%%Preface to the second edition, abcl-1.1.
34
35\subsection{Preface to the Second Edition}
36
37\textsc{ABCL} 1.1 now contains \textsc{(A)MOP}.  We hope you enjoy!  --The Mgmt.
38
39\chapter{Introduction}
40
41Armed Bear Common Lisp (\textsc{ABCL}) is an implementation of Common
42Lisp that runs on the Java Virtual Machine.  It compiles Common Lisp
43to Java 5 bytecode \footnote{The class file version is ``49.0''.},
44providing the following integration methods for interfacing with Java
45code and libraries:
46\begin{itemize}
47\item Lisp code can create Java objects and call their methods (see
48  Section~\ref{sec:lisp-java}, page~\pageref{sec:lisp-java}).
49\item Java code can call Lisp functions and generic functions, either
50  directly (Section~\ref{sec:calling-lisp-from-java},
51  page~\pageref{sec:calling-lisp-from-java}) or via \texttt{JSR-223}
52  (Section~\ref{sec:java-scripting-api},
53  page~\pageref{sec:java-scripting-api}).
54\item \code{jinterface-implementation} creates Lisp-side implementations
55  of Java interfaces that can be used as listeners for Swing classes and
56  similar.
57\item \code{java:jnew-runtime-class} can inject fully synthetic Java
58  classes--and their objects-- into the current JVM process whose
59  behavior is specified via closures expressed in Common Lisp.. \footnote{Parts of
60    the current implementation are not fully finished, so the status
61    of some interfaces here should be treated with skepticism if you
62    run into problems.}
63
64\end{itemize}
65\textsc{ABCL} is supported by the Lisp library manager
66\textsc{QuickLisp}\footnote{\url{http://quicklisp.org/}} and can run many of the
67programs and libraries provided therein out-of-the-box.
68
69\section{Conformance}
70\label{section:conformance}
71
72\subsection{ANSI Common Lisp}
73\textsc{ABCL} is currently a (non)-conforming \textsc{ANSI} Common Lisp
74implementation due to the following known issues:
75
76\begin{itemize}
77\item The generic function signatures of the \code{CL:DOCUMENTATION} symbol
78  do not match the specification.
79\item The \code{CL:TIME} form does not return a proper \code{CL:VALUES}
80  environment to its caller.
81\item When merging pathnames and the defaults point to a \code{EXT:JAR-PATHNAME},
82  we set the \code{DEVICE} of the result to \code{:UNSPECIFIC} if the pathname to be
83  be merged does not contain a specified \code{DEVICE}, does not contain a
84  specified \code{HOST}, does contain a relative \code{DIRECTORY}, and we are
85  not running on a \textsc{MSFT} Windows platform.\footnote{The intent of this
86    rather arcane sounding deviation from conformance is so that the
87    result of a merge won't fill in a \code{DEVICE} with the wrong "default
88    device for the host" in the sense of the fourth paragraph in the
89    \textsc{CLHS} description of MERGE-PATHNAMES (see in \cite{CLHS} the paragraph beginning
90    "If the PATHNAME explicitly specifies a host and not a device
").
91    A future version of the implementation may return to conformance
92    by using the \code{HOST} value to reflect the type explicitly.
93  }
94
95\end{itemize}
96
97Somewhat confusingly, this statement of non-conformance in the
98accompanying user documentation fulfills the requirements that
99\textsc{ABCL} is a conforming ANSI Common Lisp implementation according
100to the Common Lisp HyperSpec~\cite{CLHS}.  Clarifications to this point
101are solicited.
102
103\textsc{ABCL} aims to be be a fully conforming \textsc{ANSI} Common Lisp implementation.
104Any other behavior should be reported as a bug.
105
106\subsection{Contemporary Common Lisp}
107In addition to \textsc{ANSI} conformance, \textsc{ABCL} strives to implement
108features expected of a contemporary Common Lisp, i.e. a Lisp of the
109post-2005 Renaissance.
110
111The following known problems detract from \textsc{ABCL} being a proper
112contemporary Common Lisp.
113\begin{itemize}
114\item An incomplete implementation of interactive debugging mechanisms,
115  namely a no-op version of \code{STEP} \footnote{Somewhat surprisingly
116    allowed by \textsc{ANSI}}, the inability to inspect local variables
117  in a given call frame, and the inability to resume a halted
118  computation at an arbitrarily selected call frame.
119\item Incomplete streams abstraction, in that \textsc{ABCL} needs
120  suitable abstraction between \textsc{ANSI} and Gray
121  streams.  \footnote{The streams could be optimized to the
122    \textsc{JVM} NIO \cite{nio} abstractions at great profit for
123    binary byte-level manipulations.}
124\item Incomplete documentation (missing docstrings from exported
125  symbols and the draft status of this user manual).
126\end{itemize}
127
128
129
130\section{License}
131
132\textsc{ABCL} is licensed under the terms of the \textsc{GPL} v2 of
133June 1991 with the ``classpath-exception'' (see the file
134\texttt{COPYING} in the source distribution \footnote{See
135  \url{http://abcl.org/svn/trunk/tags/1.3.0/COPYING}} for
136the license, term 13 in the same file for the classpath exception).
137This license broadly means that you must distribute the sources to
138ABCL, including any changes you make, together with a program that
139includes ABCL, but that you are not required to distribute the sources
140of the whole program.  Submitting your changes upstream to the ABCL
141development team is actively encouraged and very much appreciated, of
142course.
143
144\section{Contributors}
145
146\begin{itemize}
147\item Philipp Marek \texttt{Thanks for the markup}
148\item Douglas Miles \texttt{Thanks for the whacky IKVM stuff and keeping the flame alive
149  in the dark years.}
150\item Alan Ruttenberg \texttt{Thanks for JSS.}
151\item and of course
152\emph{Peter Graves}
153\end{itemize}
154
155
156\chapter{Running ABCL}
157
158
159\textsc{ABCL} is packaged as a single jar file usually named either
160\texttt{abcl.jar} or possibly something like \texttt{abcl-1.3.0.jar} if
161using a versioned package on the local filesystem from your system
162vendor.  This jar file can be executed from the command line to obtain a
163\textsc{REPL}\footnote{Read-Eval Print Loop, a Lisp command-line}, viz:
164
165\index{REPL}
166
167\begin{listing-shell}
168  cmd$ java -jar abcl.jar
169\end{listing-shell} %$ unconfuse Emacs syntax highlighting
170
171\emph{N.b.} for the proceeding command to work, the \texttt{java}
172executable needs to be in your path.
173
174To facilitate the use of ABCL in tool chains such as SLIME~\cite{slime}
175(the Superior Lisp Interaction Mode for Emacs), we provide both a Bourne
176shell script and a \textsc{DOS} batch file.  If you or your
177administrator adjusted the path properly, ABCL may be executed simply
178as:
179
180\begin{listing-shell}
181  cmd$ abcl
182\end{listing-shell}%$
183
184Probably the easiest way of setting up an editing environment using the
185\textsc{Emacs} editor is to use \textsc{Quicklisp} and follow the instructions at
186\url{http://www.quicklisp.org/beta/#slime}.
187
188\section{Options}
189
190ABCL supports the following command line options:
191
192\index{Command Line Options}
193
194\begin{description}
195\item[\texttt{  --help}] displays a help message.
196\item[\texttt{  --noinform}] Suppresses the printing of startup information and banner.
197\item[\texttt{  --noinit}] suppresses the loading of the \verb+~/.abclrc+ startup file.
198\item[\texttt{  --nosystem}] suppresses loading the \texttt{system.lisp} customization file.
199\item[\texttt{  --eval FORM}] evaluates FORM before initializing the REPL.
200\item[\texttt{  --load FILE}] loads the file FILE before initializing the REPL.
201\item[\texttt{  --load-system-file FILE}] loads the system file FILE before initializing the REPL.
202\item[\texttt{  --batch}] evaluates forms specified by arguments and in
203  the initialization file \verb+~/.abclrc+, and then exits without
204  starting a \textsc{REPL}.
205\end{description}
206
207All of the command line arguments following the occurrence of \verb+--+
208are passed unprocessed into a list of strings accessible via the
209variable \code{EXT:*COMMAND-LINE-ARGUMENT-LIST*} from within ABCL.
210
211\section{Initialization}
212
213If the \textsc{ABCL} process is started without the \code{--noinit}
214flag, it attempts to load a file named \code{.abclrc} in the user's home
215directory and then interpret its contents.
216
217The user's home directory is determined by the value of the JVM system
218property \texttt{user.home}.  This value may or may not correspond
219to the value of the \texttt{HOME} system environment variable, at the
220discretion of the JVM implementation that \textsc{ABCL} finds itself
221hosted upon.
222
223\chapter{Interaction with the Hosting JVM}
224
225%  Plan of Attack
226%
227% describe calling Java from Lisp, and calling Lisp from Java,
228% probably in two separate sections.  Presumably, we can partition our
229% audience into those who are more comfortable with Java, and those
230% that are more comforable with Lisp
231
232The Armed Bear Common Lisp implementation is hosted on a Java Virtual
233Machine.  This chapter describes the mechanisms by which the
234implementation interacts with that hosting mechanism.
235
236\section{Lisp to Java}
237\label{sec:lisp-java}
238
239\textsc{ABCL} offers a number of mechanisms to interact with Java from its
240Lisp environment. It allows calling both instance and static methods
241of Java objects, manipulation of instance and static fields on Java
242objects, and construction of new Java objects.
243
244When calling Java routines, some values will automatically be
245converted by the FFI\footnote{Foreign Function Interface, is the term
246  of art for the part of a Lisp implementation which implements
247  calling code written in other languages, typically normalized to the
248  local C compiler calling conventions.}  from Lisp values to Java
249values. These conversions typically apply to strings, integers and
250floats. Other values need to be converted to their Java equivalents by
251the programmer before calling the Java object method. Java values
252returned to Lisp are also generally converted back to their Lisp
253counterparts. Some operators make an exception to this rule and do not
254perform any conversion; those are the ``raw'' counterparts of certain
255FFI functions and are recognizable by their name ending with
256\code{-RAW}.
257
258\subsection{Low-level Java API}
259
260This subsection covers the low-level API available after evaluating
261\code{(require 'JAVA)}.  A higher level Java API, developed by Alan
262Ruttenberg, is available in the \code{contrib/} directory and described
263later in this document, see Section~\ref{section:jss} on page
264\pageref{section:jss}.
265
266\subsubsection{Calling Java Object Methods}
267
268There are two ways to call a Java object method in the low-level (basic) API:
269
270\begin{itemize}
271\item Call a specific method reference (which was previously acquired)
272\item Dynamic dispatch using the method name and the call-specific
273  arguments provided by finding the best match (see
274  Section~\ref{sec:param-matching-for-ffi}).
275\end{itemize}
276
277\code{JAVA:JMETHOD} is used to acquire a specific method reference.  The
278function takes two or more arguments. The first is a Java class
279designator (a \code{JAVA:JAVA-CLASS} object returned by
280\code{JAVA:JCLASS} or a string naming a Java class). The second is a
281string naming the method.
282
283Any arguments beyond the first two should be strings naming Java
284classes, with one exception as listed in the next paragraph. These
285classes specify the types of the arguments for the method.
286
287When \code{JAVA:JMETHOD} is called with three parameters and the last
288parameter is an integer, the first method by that name and matching
289number of parameters is returned.
290
291Once a method reference has been acquired, it can be invoked using
292\code{JAVA:JCALL}, which takes the method as the first argument. The
293second argument is the object instance to call the method on, or
294\code{NIL} in case of a static method.  Any remaining parameters are
295used as the remaining arguments for the call.
296
297\subsubsection{Calling Java object methods: dynamic dispatch}
298
299The second way of calling Java object methods is by using dynamic dispatch.
300In this case \code{JAVA:JCALL} is used directly without acquiring a method
301reference first. In this case, the first argument provided to \code{JAVA:JCALL}
302is a string naming the method to be called. The second argument is the instance
303on which the method should be called and any further arguments are used to
304select the best matching method and dispatch the call.
305
306\subsubsection{Dynamic dispatch: Caveats}
307
308Dynamic dispatch is performed by using the Java reflection
309API \footnote{The Java reflection API is found in the
310  \code{java.lang.reflect} package}. Generally the dispatch works
311fine, but there are corner cases where the API does not correctly
312reflect all the details involved in calling a Java method. An example
313is the following Java code:
314
315\begin{listing-java}
316ZipFile jar = new ZipFile("/path/to/some.jar");
317Object els = jar.entries();
318Method method = els.getClass().getMethod("hasMoreElements");
319method.invoke(els);
320\end{listing-java}
321
322Even though the method \code{hasMoreElements()} is public in
323\code{Enumeration}, the above code fails with
324
325\begin{listing-java}
326java.lang.IllegalAccessException: Class ... can
327not access a member of class java.util.zip.ZipFile\$2 with modifiers
328"public"
329       at sun.reflect.Reflection.ensureMemberAccess(Reflection.java:65)
330       at java.lang.reflect.Method.invoke(Method.java:583)
331       at ...
332\end{listing-java}
333
334This is because the method has been overridden by a non-public class and
335the reflection API, unlike \texttt{javac}, is not able to handle such a case.
336
337While code like that is uncommon in Java, it is typical of ABCL's FFI
338calls. The code above corresponds to the following Lisp code:
339
340\begin{listing-lisp}
341(let ((jar (jnew "java.util.zip.ZipFile" "/path/to/some.jar")))
342  (let ((els (jcall "entries" jar)))
343    (jcall "hasMoreElements" els)))
344\end{listing-lisp}
345
346except that the dynamic dispatch part is not shown.
347
348To avoid such pitfalls, all Java objects in \textsc{ABCL} carry an extra
349field representing the ``intended class'' of the object. That class is
350used first by \code{JAVA:JCALL} and similar to resolve methods; the
351actual class of the object is only tried if the method is not found in
352the intended class. Of course, the intended class is always a
353super-class of the actual class -- in the worst case, they coincide. The
354intended class is deduced by the return type of the method that
355originally returned the Java object; in the case above, the intended
356class of \code{ELS} is \code{java.util.Enumeration} because that is the
357return type of the \code{entries} method.
358
359While this strategy is generally effective, there are cases where the
360intended class becomes too broad to be useful. The typical example
361is the extraction of an element from a collection, since methods in
362the collection API erase all types to \code{Object}. The user can
363always force a more specific intended class by using the \code{JAVA:JCOERCE}
364operator.
365
366% \begin{itemize}
367% \item Java values are accessible as objects of type JAVA:JAVA-OBJECT.
368% \item The Java FFI presents a Lisp package (JAVA) with many useful
369%   symbols for manipulating the artifacts of expectation on the JVM,
370%   including creation of new objects \ref{JAVA:JNEW}, \ref{JAVA:JMETHOD}), the
371%   introspection of values \ref{JAVA:JFIELD}, the execution of methods
372%   (\ref{JAVA:JCALL}, \ref{JAVA:JCALL-RAW}, \ref{JAVA:JSTATIC})
373% \item The JSS package (\ref{JSS}) in contrib introduces a convenient macro
374%   syntax \ref{JSS:SHARPSIGN_DOUBLEQUOTE_MACRO} for accessing Java
375%   methods, and additional convenience functions.
376% \item Java classes and libraries may be dynamically added to the
377%   classpath at runtime (JAVA:ADD-TO-CLASSPATH).
378% \end{itemize}
379
380\subsubsection{Calling Java class static methods}
381
382Like non-static methods, references to static methods can be acquired by
383using the \code{JAVA:JMETHOD} primitive. Static methods are called with
384\code{JAVA:JSTATIC} instead of \code{JAVA:JCALL}.
385
386Like \code{JAVA:JCALL}, \code{JAVA:JSTATIC} supports dynamic dispatch by
387passing the name of the method as a string instead of passing a method reference.
388The parameter values should be values to pass in the function call instead of
389a specification of classes for each parameter.
390
391\subsubsection{Parameter matching for FFI dynamic dispatch}
392\label{sec:param-matching-for-ffi}
393
394The algorithm used to resolve the best matching method given the name
395and the arguments' types is the same as described in the Java Language
396Specification. Any deviation should be reported as a bug.
397
398% ###TODO reference to correct JLS section
399
400\subsubsection{Instantiating Java objects}
401
402Java objects can be instantiated (created) from Lisp by calling
403a constructor from the class of the object to be created. The
404\code{JAVA:JCONSTRUCTOR} primitive is used to acquire a constructor
405reference. It's arguments specify the types of arguments of the constructor
406method the same way as with \code{JAVA:JMETHOD}.
407
408The obtained constructor is passed as an argument to \code{JAVA:JNEW},
409together with any arguments.  \code{JAVA:JNEW} can also be invoked with
410a string naming the class as its first argument.
411
412\subsubsection{Accessing Java object and class fields}
413
414Fields in Java objects can be accessed using the getter and setter
415functions \code{JAVA:JFIELD} and \code{(SETF JAVA:JFIELD)}.  Static
416(class) fields are accessed the same way, but with a class object or
417string naming a class as first argument.
418
419Like \code{JAVA:JCALL} and friends, values returned from these accessors carry
420an intended class around, and values which can be converted to Lisp values will
421be converted.
422
423\section{Java to Lisp}
424
425This section describes the various ways that one interacts with Lisp
426from Java code.  In order to access the Lisp world from Java, one needs
427to be aware of a few things, the most important ones being listed below:
428
429\begin{itemize}
430\item All Lisp values are descendants of \code{LispObject}.
431\item Lisp symbols are accessible either via static members of the
432  \code{Symbol} class, or by dynamically introspecting a \code{Package}
433  object.
434\item The Lisp dynamic environment may be saved via
435  \code{LispThread.bindSpecial(Binding)} and restored via
436  \code{LispThread.resetSpecialBindings(Mark)}.
437\item Functions can be executed by invoking \code{LispObject.execute(args
438    [...])}
439\end{itemize}
440
441\subsection{Calling Lisp from Java}
442\label{sec:calling-lisp-from-java}
443
444Note: the entire ABCL Lisp system resides in the
445\texttt{org.armedbear.lisp} package, but the following code snippets do
446not show the relevant import statements in the interest of brevity.  An
447example of the import statement would be
448\begin{listing-java}
449  import org.armedbear.lisp.*;
450\end{listing-java}
451to potentially import all the JVM symbol from the `org.armedbear.lisp'
452namespace.
453
454There can only ever be a single Lisp interpreter per JVM instance.  A
455reference to this interpreter is obtained by calling the static method
456\code{Interpreter.createInstance()}.
457
458\begin{listing-java}
459  Interpreter interpreter = Interpreter.createInstance();
460\end{listing-java}
461
462If this method has already been invoked in the lifetime of the current
463Java process it will return \texttt{null}, so if you are writing Java
464whose life-cycle is a bit out of your control (like in a Java servlet),
465a safer invocation pattern might be:
466
467\begin{listing-java}
468  Interpreter interpreter = Interpreter.getInstance();
469  if (interpreter == null) {
470    interpreter = Interpreter.createInstance();
471  }
472\end{listing-java}
473
474
475The Lisp \code{eval} primitive may simply be passed strings for evaluation:
476
477\begin{listing-java}
478  String line = "(load \"file.lisp\")";
479  LispObject result = interpreter.eval(line);
480\end{listing-java}
481
482Notice that all possible return values from an arbitrary Lisp
483computation are collapsed into a single return value.  Doing useful
484further computation on the \code{LispObject} depends on knowing what the
485result of the computation might be.  This usually involves some amount
486of \code{instanceof} introspection, and forms a whole topic to itself
487(see Section~\ref{topic:Introspecting a LispObject},
488page~\pageref{topic:Introspecting a LispObject}).
489
490Using \code{eval} involves the Lisp interpreter.  Lisp functions may
491also be directly invoked by Java method calls as follows.  One simply
492locates the package containing the symbol, obtains a reference to the
493symbol, and then invokes the \code{execute()} method with the desired
494parameters.
495
496\begin{listing-java}
497  interpreter.eval("(defun foo (msg)" +
498    "(format nil \"You told me '~A'~%\" msg))");
499  Package pkg = Packages.findPackage("CL-USER");
500  Symbol foo = pkg.findAccessibleSymbol("FOO");
501  Function fooFunction = (Function)foo.getSymbolFunction();
502  JavaObject parameter = new JavaObject("Lisp is fun!");
503  LispObject result = fooFunction.execute(parameter);
504  // How to get the "naked string value"?
505  System.out.println("The result was " + result.writeToString());
506\end{listing-java}
507
508If one is calling a function in the CL package, the syntax can become
509considerably simpler.  If we can locate the instance of definition in
510the ABCL Java source, we can invoke the symbol directly.  For instance,
511to tell if a \code{LispObject} is (Lisp) \texttt{NIL}, we can invoke the
512CL function \code{NULL} in the following way:
513
514\begin{listing-java}
515  boolean nullp(LispObject object) {
516    LispObject result = Primitives.NULL.execute(object);
517    if (result == NIL) { // the symbol 'NIL' is explicitly named in the Java
518                         // namespace at ``Symbol.NIL''
519                         // but is always present in the
520                         // local namespace in its unadorned form for
521                         // the convenience of the User.
522      return false;
523    }
524    return true;
525 }
526\end{listing-java}
527
528\subsubsection{Multiple Values}
529
530After a call to a function that returns Lisp multiple values, the
531values are associated with the executing \code{LispThread} until the
532next call into Lisp.  One may access the values object as a list of
533\code{LispObject} instances via a call to \code{getValues()} on that
534thread reference
535as evidenced by the following code:
536
537\begin{listing-java}
538
539  org.armedbear.lisp.Package cl = Packages.findPackage("CL");
540  Symbol valuesSymbol = cl.findAccessibleSymbol("VALUES");
541  LispObject[] valuesArgs = {
542    LispInteger.getInstance(1), LispInteger.getInstance(2)
543  };
544  // equivalent to ``(values 1 2)''
545  LispObject result = valuesSymbol.execute(valuesArgs);
546  LispObject[] values = LispThread.currentThread().getValues();
547  for (LispObject value: values) {
548    System.out.println("value ==> " + value.printObject());
549  }
550\end{listing-java}
551
552\subsubsection{Introspecting a LispObject}
553\label{topic:Introspecting a LispObject}
554
555We present various patterns for introspecting an arbitrary
556\code{LispObject} which can hold the result of every Lisp evaluation
557into semantics that Java can meaningfully deal with.
558
559\paragraph{LispObject as \code{boolean}}
560
561If the \code{LispObject} is to be interpreted as a generalized boolean
562value, one can use \code{getBooleanValue()} to convert to Java:
563
564\begin{listing-java}
565   LispObject object = Symbol.NIL;
566   boolean javaValue = object.getBooleanValue();
567\end{listing-java}
568
569Since in Lisp any value other than \code{NIL} means "true", Java
570equality can also be used, which is a bit easier to type and better in
571terms of information it conveys to the compiler:
572
573\begin{listing-java}
574    boolean javaValue = (object != Symbol.NIL);
575\end{listing-java}
576
577\paragraph{LispObject as a list}
578
579If \code{LispObject} is a list, it will have the type \code{Cons}.  One
580can then use the \code{copyToArray} method to make things a bit more
581suitable for Java iteration.
582
583\begin{listing-java}
584  LispObject result = interpreter.eval("'(1 2 4 5)");
585  if (result instanceof Cons) {
586    LispObject array[] = ((Cons)result.copyToArray());
587    ...
588  }
589\end{listing-java}
590
591A more Lispy way to iterate down a list is to use the `cdr()` access
592function just as like one would traverse a list in Lisp:;
593
594\begin{listing-java}
595  LispObject result = interpreter.eval("'(1 2 4 5)");
596  while (result != Symbol.NIL) {
597    doSomething(result.car());
598    result = result.cdr();
599  }
600\end{listing-java}
601
602\section{Java Scripting API (JSR-223)}
603\label{sec:java-scripting-api}
604
605ABCL can be built with support for JSR-223~\cite{jsr-223}, which offers
606a language-agnostic API to invoke other languages from Java. The binary
607distribution download-able from ABCL's homepage is built with JSR-223
608support. If you're building ABCL from source on a pre-1.6 JVM, you need
609to have a JSR-223 implementation in your classpath (such as Apache
610Commons BSF 3.x or greater) in order to build ABCL with JSR-223 support;
611otherwise, this feature will not be built.
612
613This section describes the design decisions behind the ABCL JSR-223
614support. It is not a description of what JSR-223 is or a tutorial on
615how to use it. See
616\url{http://abcl.org/trac/browser/trunk/abcl/examples/jsr-223}
617for example usage.
618
619\subsection{Conversions}
620
621In general, ABCL's implementation of the JSR-223 API performs implicit
622conversion from Java objects to Lisp objects when invoking Lisp from
623Java, and the opposite when returning values from Java to Lisp. This
624potentially reduces coupling between user code and ABCL. To avoid such
625conversions, wrap the relevant objects in \code{JavaObject} instances.
626
627\subsection{Implemented JSR-223 interfaces}
628
629JSR-223 defines three main interfaces, of which two (\code{Invocable}
630and \code{Compilable}) are optional. ABCL implements all the three
631interfaces - \code{ScriptEngine} and the two optional ones - almost
632completely. While the JSR-223 API is not specific to a single scripting
633language, it was designed with languages with a more or less Java-like
634object model in mind: languages such as Javascript, Python, Ruby, which
635have a concept of "class" or "object" with "fields" and "methods". Lisp
636is a bit different, so certain adaptations were made, and in one case a
637method has been left unimplemented since it does not map at all to Lisp.
638
639\subsubsection{The ScriptEngine}
640
641The main interface defined by JSR-223, \code{javax.script.ScriptEngine},
642is implemented by the class
643\code{org.armedbear.lisp.scripting.AbclScriptEngine}. \code{AbclScriptEngine}
644is a singleton, reflecting the fact that ABCL is a singleton as
645well. You can obtain an instance of \code{AbclScriptEngine} using the
646\code{AbclScriptEngineFactory} or by using the service provider
647mechanism through \code{ScriptEngineManager} (refer to the
648\texttt{javax.script} documentation).
649
650\subsection{Start-up and configuration file}
651
652At start-up (i.e. when its constructor is invoked, as part of the
653static initialization phase of \code{AbclScriptEngineFactory}) the ABCL
654script engine attempts to load an "init file" from the classpath
655(\texttt{/abcl-script-config.lisp}). If present, this file can be used to
656customize the behavior of the engine, by setting a number of
657variables in the \code{ABCL-SCRIPT} package. Here is a list of the available
658variables:
659
660\begin{description}
661\item[\texttt{*use-throwing-debugger*}] controls whether ABCL uses a
662  non-standard debugging hook function to throw a Java exception
663  instead of dropping into the debugger in case of unhandled error
664  conditions.
665  \begin{itemize}
666  \item Default value: \texttt{T}
667  \item Rationale: it is more convenient for Java programmers using
668    Lisp as a scripting language to have it return exceptions to Java
669    instead of handling them in the Lisp world.
670  \item Known Issues: the non-standard debugger hook has been reported
671    to misbehave in certain circumstances, so consider disabling it if
672    it doesn't work for you.
673  \end{itemize}
674\item[\texttt{*launch-swank-at-startup*}] If true, Swank will be launched at
675  startup. See \texttt{*swank-dir*} and \texttt{*swank-port*}.
676  \begin{itemize}
677  \item Default value: \texttt{NIL}
678  \end{itemize}
679\item[\texttt{*swank-dir*}] The directory where Swank is installed. Must be set
680  if \texttt{*launch-swank-at-startup*} is true.
681\item[\texttt{*swank-port*}] The port where Swank will listen for
682  connections. Must be set if \texttt{*launch-swank-at-startup*} is
683  true.
684  \begin{itemize}
685  \item Default value: 4005
686  \end{itemize}
687\end{description}
688
689Additionally, at startup the AbclScriptEngine will \code{(require
690  'asdf)} - in fact, it uses asdf to load Swank.
691
692\subsection{Evaluation}
693
694Code is read and evaluated in the package \code{ABCL-SCRIPT-USER}. This
695packages \texttt{USE}s the \code{COMMON-LISP}, \code{JAVA} and
696\code{ABCL-SCRIPT} packages. Future versions of the script engine might
697make this default package configurable. The \code{CL:LOAD} function is
698used under the hood for evaluating code, and thus the behavior of
699\code{LOAD} is guaranteed. This allows, among other things,
700\code{IN-PACKAGE} forms to change the package in which the loaded code
701is read.
702
703It is possible to evaluate code in what JSR-223 calls a
704``ScriptContext'' (basically a flat environment of name$\rightarrow$value
705pairs). This context is used to establish special bindings for all the
706variables defined in it; since variable names are strings from Java's
707point of view, they are first interned using \code{READ-FROM-STRING} with, as
708usual, \code{ABCL-SCRIPT-USER} as the default package. Variables are declared
709special because CL's \code{LOAD}, \code{EVAL} and \code{COMPILE}
710functions work in a null lexical environment and would ignore
711non-special bindings.
712
713Contrary to what the function \code{LOAD} does, evaluation of a series
714of forms returns the value of the last form instead of T, so the
715evaluation of short scripts does the Right Thing.
716
717\subsection{Compilation}
718
719AbclScriptEngine implements the \code{javax.script.Compilable}
720interface. Currently it only supports compilation using temporary
721files. Compiled code, returned as an instance of
722\texttt{javax.script.CompiledScript}, is read, compiled and executed by
723default in the \texttt{ABCL-SCRIPT-USER} package, just like evaluated
724code.  In contrast to evaluated code, though, due to the way the ABCL
725compiler works, compiled code contains no reference to top-level
726self-evaluating objects (like numbers or strings). Thus, when evaluated,
727a piece of compiled code will return the value of the last
728non-self-evaluating form: for example the code ``\code{(do-something)
729  42}'' will return 42 when interpreted, but will return the result of
730(do-something) when compiled and later evaluated. To ensure consistency
731of behavior between interpreted and compiled code, make sure the last
732form is always a compound form - at least \code{(identity
733some-literal-object)}. Note that this issue should not matter in real
734code, where it is unlikely a top-level self-evaluating form will appear
735as the last form in a file (in fact, the Common Lisp load function
736always returns \texttt{T} upon success; with JSR-223 this policy has been changed
737to make evaluation of small code snippets work as intended).
738
739\subsection{Invocation of functions and methods}
740
741AbclScriptEngine implements the \code{javax.script.Invocable}
742interface, which allows to directly call Lisp functions and methods,
743and to obtain Lisp implementations of Java interfaces. This is only
744partially possible with Lisp since it has functions, but not methods -
745not in the traditional OO sense, at least, since Lisp methods are not
746attached to objects but belong to generic functions. Thus, the method
747\code{invokeMethod()} is not implemented and throws an
748\texttt{UnsupportedOperationException} when called. The \code{invokeFunction()}
749method should be used to call both regular and generic functions.
750
751\subsection{Implementation of Java interfaces in Lisp}
752
753ABCL can use the Java reflection-based proxy feature to implement Java
754interfaces in Lisp. It has several built-in ways to implement an
755interface, and supports definition of new ones. The
756\code{JAVA:JMAKE-PROXY} generic function is used to make such
757proxies. It has the following signature:
758
759\code{jmake-proxy interface implementation \&optional lisp-this ==> proxy}
760
761\code{interface} is a Java interface metaobject (e.g. obtained by
762invoking \code{jclass}) or a string naming a Java
763interface. \code{implementation} is the object used to implement the
764interface - several built-in methods of jmake-proxy exist for various
765types of implementations. \code{lisp-this} is an object passed to the
766closures implementing the Lisp "methods" of the interface, and
767defaults to \code{NIL}.
768
769The returned proxy is an instance of the interface, with methods
770implemented with Lisp functions.
771
772Built-in interface-implementation types include:
773
774\begin{itemize}
775\item a single Lisp function which upon invocation of any method in
776  the interface will be passed the method name, the Lisp-this object,
777  and all the parameters. Useful for interfaces with a single method,
778  or to implement custom interface-implementation strategies.
779\item a hash-map of method-name $\rightarrow$ Lisp function mappings. Function
780  signature is \code{(lisp-this \&rest args)}.
781\item a Lisp package. The name of the Java method to invoke is first
782  transformed in an idiomatic Lisp name (\code{javaMethodName} becomes
783  \code{JAVA-METHOD-NAME}) and a symbol with that name is searched in
784  the package. If it exists and is fbound, the corresponding function
785  will be called. Function signature is as the hash-table case.
786\end{itemize}
787
788This functionality is exposed by the class \code{AbclScriptEngine} via
789the two methods \code{getInterface(Class)} and
790\code{getInterface(Object, Class)}. The former returns an interface
791implemented with the current Lisp package, the latter allows the
792programmer to pass an interface-implementation object which will in turn
793be passed to the \code{jmake-proxy} generic function.
794
795\subsection{Implementation of Java classes in Lisp}
796
797See \code{JAVA:JNEW-RUNTIME-CLASS} on \ref{JAVA:JNEW-RUNTIME-CLASS}.
798
799
800\chapter{Implementation Dependent Extensions}
801
802As outlined by the CLHS ANSI conformance guidelines, we document the
803extensions to the Armed Bear Lisp implementation made accessible to
804the user by virtue of being an exported symbol in the JAVA, THREADS,
805or EXTENSIONS packages.
806
807\section{JAVA}
808
809\subsection{Modifying the JVM CLASSPATH}
810
811The JAVA:ADD-TO-CLASSPATH generic functions allows one to add the
812specified pathname or list of pathnames to the current classpath
813used by ABCL, allowing the dynamic loading of JVM objects:
814
815\begin{listing-lisp}
816CL-USER> (add-to-classpath "/path/to/some.jar")
817\end{listing-lisp}
818
819N.b \code{ADD-TO-CLASSPATH} only affects the classloader used by ABCL
820(the value of the special variable \code{JAVA:*CLASSLOADER*}. It has
821no effect on Java code outside ABCL.
822
823\subsection{Creating a synthetic Java Class at Runtime}
824
825See \code{JAVA:JNEW-RUNTIME-CLASS} on \ref{JAVA:JNEW-RUNTIME-CLASS}.
826
827% include autogen docs for the JAVA package.
828\include{java}
829
830\section{THREADS}
831
832The extensions for handling multithreaded execution are collected in
833the \code{THREADS} package.  Most of the abstractions in Doug Lea's
834excellent \code{java.util.concurrent} packages may be manipulated
835directly via the JSS contrib to great effect.
836
837% include autogen docs for the THREADS package.
838\include{threads}
839
840\section{EXTENSIONS}
841
842The symbols in the EXTENSIONS package (nicknamed ``EXT'') constitutes
843extensions to the \textsc{ANSI} standard that are potentially useful to the
844user.  They include functions for manipulating network sockets,
845running external programs, registering object finalizers, constructing
846reference weakly held by the garbage collector and others.
847
848See \cite{RHODES2007} for a generic function interface to the native
849\textsc{JVM} contract for \code{java.util.List}.
850
851% include autogen docs for the EXTENSIONS package.
852\include{extensions}
853
854\chapter{Beyond ANSI}
855
856Naturally, in striving to be a useful contemporary Common Lisp
857implementation, ABCL endeavors to include extensions beyond the ANSI
858specification which are either widely adopted or are especially useful
859in working with the hosting \textsc{JVM}.
860
861\section{Compiler to Java 5 Bytecode}
862
863The \code{CL:COMPILE-FILE} interface emits a packed fasl format whose
864Pathname has the type  ``abcl''.  These fasls are operating system neutral
865byte archives packaged by the zip compression format which contain
866artifacts whose loading \code{CL:LOAD} understands.
867
868\section{Pathname}
869
870We implement an extension to the \code{CL:PATHNAME} that allows for
871the description and retrieval of resources named in a
872\textsc{URI} \footnote{A \textsc{URI} is essentially a superset of
873  what is commonly understood as a \textsc{URL} We sometime suse the
874  term URL as shorthand in describing the URL Pathnames, even though
875  the corresponding encoding is more akin to a URI as described in
876  RFC3986 \cite{rfc3986}.}  scheme that the \textsc{JVM}
877``understands''.  By definition, support is built-in into the JVM to
878access the ``http'' and ``https'' schemes but additional protocol
879handlers may be installed at runtime by having \textsc{JVM} symbols
880present in the \code{sun.net.protocol.dynamic} package. See
881\cite{maso2000} for more details.
882
883\textsc{ABCL} has created specializations of the ANSI
884\code{CL:PATHNAME} object to enable to use of \textsc{URI}s to address
885dynamically loaded resources for the JVM.  The \code{EXT:URL-PATHNAME}
886specialization has a corresponding \textsc{URI} whose canonical
887representation is defined to be the \code{NAMESTRING} of the
888\code{CL:PATHNAME}. The \code{EXT:JAR-PATHNAME} extension further
889specializes the the \code{EXT:URL-PATHNAME} to provide access to
890components of zip archives. 
891
892% RDF description of type hierarchy
893% TODO Render via some LaTeX mode for graphviz?
894\begin{verbatim}
895  @prefix ext:   <http://abcl.not.org/cl-packages/extensions/> .
896  @prefix cl:    <http://abcl.not.org/cl-packages/common-lisp/> .
897 
898  <ext:jar-pathname> a <ext:url-pathname>.
899  <ext:url-pathname> a <cl:pathname>.
900  <cl:logical-pathname> a <cl:pathname> .
901\end{verbatim}
902
903\label{EXTENSIONS:URL-PATHNAME}
904\index{URL-PATHNAME}
905
906\label{EXTENSIONS:JAR-PATHNAME}
907\index{JAR-PATHNAME}
908
909Both the \code{EXT:URL-PATHNAME} and \code{EXT:JAR-PATHNAME} objects
910may be used anywhere a \code{CL:PATHNAME} is accepted with the
911following caveats:
912
913\begin{itemize}
914
915\item A stream obtained via \code{CL:OPEN} on a \code{CL:URL-PATHNAME}
916  cannot be the target of write operations.
917
918\index{URI}
919\item Any results of canonicalization procedures performed on the
920  underlying \textsc{URI} are discarded between resolutions (i.e. the
921  implementation does not attempt to cache the results of current name
922  resolution of the representing resource unless it is requested to be
923  resolved.)  Upon resolution, any canonicalization procedures
924  followed in resolving the resource (e.g. following redirects) are
925  discarded.  Users may programatically initiate a new, local
926  computation of the resolution of the resource by applying the
927  \code{CL:TRUENAME} function to a \code{EXT:URL-PATHNAME} object.
928  Depending on the reliability and properties of your local
929  \textsc{REST} infrastructure, these results may not necessarily be
930  idempotent over time\footnote {See \cite{evenson2011} for the draft
931    of the publication of the technical details}.
932
933\end{itemize}
934
935The implementation of \code{EXT:URL-PATHNAME} allows the \textsc{ABCL}
936user to dynamically load code from the network.  For example,
937\textsc{Quicklisp} (\cite{quicklisp}) may be completely installed from
938the \textsc{REPL} as the single form:
939
940\begin{listing-lisp}
941  CL-USER> (load "http://beta.quicklisp.org/quicklisp.lisp")
942\end{listing-lisp}
943
944will load and execute the Quicklisp setup code.
945
946The implementation currently breaks \textsc{ANSI} conformance by allowing the
947types able to be \code{CL:READ} for the \code{DEVICE} to return a possible \code{CONS} of
948\code{CL:PATHNAME} objects.  %% citation from CLHS needed.
949
950In order to ``smooth over'' the bit about types being \code{CL:READ}
951from \code{CL:PATHNAME} components, we extend the semantics for the
952usual PATHNAME merge semantics when \code{*DEFAULT-PATHNAME-DEFAULTS*}
953contains a \code{EXT:JAR-PATHNAME} with the ``do what I mean''
954algorithm described in \ref{section:conformance} on page
955\pageref{section:conformance}.
956
957%See \ref{_:quicklisp} on page \pageref{_:quicklisp}.
958
959\subsubsection{Implementation}
960
961The implementation of these extensions stores all the additional
962information in the \code{CL:PATHNAME} object itself in ways that while strictly
963speaking are conformant, nonetheless may trip up libraries that don't
964expect the following:
965
966\begin{itemize}
967\item \code{DEVICE} can be either a string denoting a drive letter
968  under \textsc{DOS} or a list of exactly one or two elements.  If
969  \code{DEVICE} is a list, it denotes a \code{EXT:JAR-PATHNAME}, with
970  the entries containing \code{CL:PATHNAME} objects which describe the
971  outer and (possibly inner) locations of the jar
972  archive \footnote{The case of inner and outer
973    \code{EXT:JAR-PATHNAME} \ref{EXT:JAR-PATHNAME} arises when zip
974    archives themselves contain zip archives which is the case when
975    the ABCL fasl is included in the abcl.jar zip archive.}.
976
977\item A \code{EXT:URL-PATHNAME} always has a \code{HOST} component that is a
978  property list.  The values of the \code{HOST} property list are
979  always character strings.  The allowed keys have the following meanings:
980  \begin{description}
981  \item[:SCHEME] Scheme of URI ("http", "ftp", "bundle", etc.)
982  \item[:AUTHORITY] Valid authority according to the URI scheme.  For
983    "http" this could be "example.org:8080".
984  \item[:QUERY] The query of the \textsc{URI} 
985  \item[:FRAGMENT] The fragment portion of the \textsc{URI}
986  \end{description}
987
988\item In order to encapsulate the implementation decisions for these
989  meanings, the following functions provide a SETF-able API for
990  reading and writing such values: \code{URL-PATHNAME-QUERY},
991  \code{URL-PATHNAME-FRAGMENT}, \code{URL-PATHNAME-AUTHORITY}, and
992  \code{URL-PATHNAME-SCHEME}.  The specific subtype of a Pathname may
993  be determined with the predicates \code{PATHNAME-URL-P} and
994  \code{PATHNAME-JAR-P}.
995
996\label{EXTENSIONS:URL-PATHNAME-SCHEME}
997\index{URL-PATHNAME-SCHEME}
998
999\label{EXTENSIONS:URL-PATHNAME-FRAGMENT}
1000\index{URL-PATHNAME-FRAGMENT}
1001
1002\label{EXTENSIONS:URL-PATHNAME-AUTHORITY}
1003\index{URL-PATHNAME-AUTHORITY}
1004
1005\label{EXTENSIONS:PATHNAME-URL-P}
1006\index{PATHNAME-URL-P}
1007
1008\label{EXTENSIONS:URL-PATHNAME-QUERY}
1009\index{URL-PATHNAME-QUERY}
1010
1011\end{itemize}
1012
1013\section{Package-Local Nicknames}
1014\label{sec:pack-local-nickn}
1015
1016ABCL allows giving packages local nicknames: they allow short and
1017easy-to-use names to be used without fear of name conflict associated
1018with normal nicknames.\footnote{Package-local nicknames were originally
1019developed in SBCL.}
1020
1021A local nickname is valid only when inside the package for which it
1022has been specified. Different packages can use same local nickname for
1023different global names, or different local nickname for same global
1024name.
1025
1026Symbol \code{:package-local-nicknames} in \code{*features*} denotes the
1027support for this feature.
1028
1029\index{DEFPACKAGE}
1030The options to \code{defpackage} are extended with a new option
1031\code{:local-nicknames (local-nickname actual-package-name)*}.
1032
1033The new package has the specified local nicknames for the corresponding
1034actual packages.
1035
1036Example:
1037\begin{listing-lisp}
1038(defpackage :bar (:intern "X"))
1039(defpackage :foo (:intern "X"))
1040(defpackage :quux (:use :cl)
1041  (:local-nicknames (:bar :foo) (:foo :bar)))
1042(find-symbol "X" :foo) ; => FOO::X
1043(find-symbol "X" :bar) ; => BAR::X
1044(let ((*package* (find-package :quux)))
1045  (find-symbol "X" :foo))               ; => BAR::X
1046(let ((*package* (find-package :quux)))
1047  (find-symbol "X" :bar))               ; => FOO::X
1048\end{listing-lisp}
1049
1050\index{PACKAGE-LOCAL-NICKNAMES}
1051--- Function: \textbf{package-local-nicknames} [\textbf{ext}] \textit{package-designator}
1052
1053\begin{adjustwidth}{5em}{5em}
1054  Returns an ALIST of \code{(local-nickname . actual-package)}
1055  describing the nicknames local to the designated package.
1056
1057  When in the designated package, calls to \code{find-package} with any
1058  of the local-nicknames will return the corresponding actual-package
1059  instead. This also affects all implied calls to \code{find-package},
1060  including those performed by the reader.
1061
1062  When printing a package prefix for a symbol with a package local
1063  nickname, the local nickname is used instead of the real name in order
1064  to preserve print-read consistency.
1065\end{adjustwidth}
1066
1067\index{PACKAGE-LOCALLY-NICKNAMED-BY-LIST}
1068--- Function: \textbf{package-locally-nicknamed-by-list} [\textbf{ext}] \textit{package-designator}
1069
1070\begin{adjustwidth}{5em}{5em}
1071Returns a list of packages which have a local nickname for the
1072designated package.
1073\end{adjustwidth}
1074
1075\index{ADD-PACKAGE-LOCAL-NICKNAME}
1076--- Function: \textbf{add-package-local-nickname} [\textbf{ext}] \textit{local-nickname actual-package \&optional package-designator}
1077
1078\begin{adjustwidth}{5em}{5em}
1079  Adds \code{local-nickname} for \code{actual-package} in the designated
1080  package, defaulting to current package. \code{local-nickname} must be
1081  a string designator, and \code{actual-package} must be a package
1082  designator.
1083
1084  Returns the designated package.
1085
1086  Signals an error if \code{local-nickname} is already a package local
1087  nickname for a different package, or if \code{local-nickname} is one
1088  of "CL", "COMMON-LISP", or, "KEYWORD", or if \code{local-nickname} is
1089  a global name or nickname for the package to which the nickname would
1090  be added.
1091
1092  When in the designated package, calls to \code{find-package} with the
1093  \code{local-nickname} will return the package the designated
1094  \code{actual-package} instead. This also affects all implied calls to
1095  \code{find-package}, including those performed by the reader.
1096
1097  When printing a package prefix for a symbol with a package local
1098  nickname, local nickname is used instead of the real name in order to
1099  preserve print-read consistency.
1100\end{adjustwidth}
1101
1102\index{REMOVE-PACKAGE-LOCAL-NICKNAME}
1103--- Function: \textbf{remove-package-local-nickname} [\textbf{ext}] \textit{old-nickname \&optional package-designator}
1104
1105\begin{adjustwidth}{5em}{5em}
1106  If the designated package had \code{old-nickname} as a local nickname
1107  for another package, it is removed. Returns true if the nickname
1108  existed and was removed, and \code{nil} otherwise.
1109\end{adjustwidth}
1110
1111
1112         
1113\section{Extensible Sequences}
1114
1115See Rhodes2007 \cite{RHODES2007} for the design.
1116
1117The SEQUENCE package fully implements Christopher Rhodes' proposal for
1118extensible sequences.  These user extensible sequences are used
1119directly in \code{java-collections.lisp} provide these CLOS
1120abstractions on the standard Java collection classes as defined by the
1121\code{java.util.List} contract.
1122
1123%% an Example of using java.util.Lisp in Lisp would be nice
1124
1125This extension is not automatically loaded by the implementation.   It
1126may be loaded via:
1127
1128\begin{listing-lisp}
1129CL-USER> (require 'java-collections)
1130\end{listing-lisp}
1131
1132if both extensible sequences and their application to Java collections
1133is required, or
1134
1135\begin{listing-lisp}
1136CL-USER> (require 'extensible-sequences)
1137\end{listing-lisp}
1138
1139if only the extensible sequences API as specified in \cite{RHODES2007} is
1140required.
1141
1142Note that \code{(require 'java-collections)} must be issued before
1143\code{java.util.List} or any subclass is used as a specializer in a \textsc{CLOS}
1144method definition (see the section below).
1145
1146\section{Extensions to CLOS}
1147
1148\subsection{Metaobject Protocol}
1149
1150\textsc{ABCL} implements the metaobject protocol for \textsc{CLOS} as
1151specified in \textsc{(A)MOP}.  The symbols are exported from the
1152package \code{MOP}.
1153
1154Contrary to the AMOP specification and following \textsc{SBCL}'s lead,
1155the metaclass \code{funcallable-standard-object} has
1156\code{funcallable-standard-class} as metaclass instead of
1157\code{standard-class}.
1158
1159\subsection{Specializing on Java classes}
1160
1161There is an additional syntax for specializing the parameter of a
1162generic function on a java class, viz. \code{(java:jclass CLASS-STRING)}
1163where \code{CLASS-STRING} is a string naming a Java class in dotted package
1164form.
1165
1166For instance the following specialization would perhaps allow one to
1167print more information about the contents of a java.util.Collection
1168object
1169
1170\begin{listing-lisp}
1171(defmethod print-object ((coll (java:jclass "java.util.Collection"))
1172                         stream)
1173  ;;; ...
1174)
1175\end{listing-lisp}
1176
1177If the class had been loaded via a classloader other than the original
1178the class you wish to specialize on, one needs to specify the
1179classloader as an optional third argument.
1180
1181\begin{listing-lisp}
1182
1183(defparameter *other-classloader*
1184  (jcall "getBaseLoader" cl-user::*classpath-manager*))
1185 
1186(defmethod print-object
1187   ((device-id (java:jclass "dto.nbi.service.hdm.alcatel.com.NBIDeviceID"
1188                            *other-classloader*))
1189    stream)
1190  ;;; ...
1191)
1192\end{listing-lisp}
1193
1194\section{Extensions to the Reader}
1195
1196We implement a special hexadecimal escape sequence for specifying 32
1197bit characters to the Lisp reader\footnote{This represents a
1198  compromise with contemporary in 2011 32bit hosting architecures for
1199  which we wish to make text processing efficient.  Should the User
1200  require more control over \textsc{UNICODE} processing we recommend Edi Weisz'
1201  excellent work with \textsc|{FLEXI-STREAMS}  which we fully support}, namely we
1202allow a sequences of the form \verb~#\U~\emph{\texttt{xxxx}} to be processed
1203by the reader as character whose code is specified by the hexadecimal
1204digits \emph{\texttt{xxxx}}.  The hexadecimal sequence may be one to four digits
1205long.  % Why doesn't ALEXANDRIA work?
1206
1207Note that this sequence is never output by the implementation.  Instead,
1208the corresponding Unicode character is output for characters whose
1209code is greater than 0x00ff.
1210
1211\section{Overloading of the CL:REQUIRE Mechanism}
1212
1213The \code{CL:REQUIRE} mechanism is overloaded by attaching these
1214semantics to the execution of \code{REQUIRE} on the following symbols:
1215
1216\begin{description}
1217
1218  \item{\code{ASDF}} 
1219    Loads the \textsc{ASDF} implementation shipped
1220    with the implementation.  After \textsc{ASDF} has been loaded in
1221    this manner, symbols passed to \code{CL:REQUIRE} which are
1222    otherwise unresolved, are passed to ASDF for a chance for
1223    resolution.  This means, for instance if \code{CL-PPCRE} can be
1224    located as a loadable \textsc{ASDF} system \code{(require
1225      'cl-ppcre)} is equivalent to \code{(asdf:load-system
1226      'cl-ppcre)}.
1227
1228  \item{\code{ABCL-CONTRIB}} 
1229    Locates and pushes the toplevel contents of
1230    ``abcl-contrib.jar'' into the \textsc{ASDF} central registry. 
1231
1232    \begin{enumerate}
1233      \item \code{abcl-asdf} 
1234        Functions for loading JVM artifacts
1235        dynamically, hooking into ASDF 3 objects where possible.
1236      \item \code{asdf-jar} 
1237        Package addressable JVM artifacts via
1238        \code{abcl-asdf} descriptions as a single binary artifact
1239        including recursive dependencies.
1240      \item \code{mvn} 
1241        These systems name common JVM artifacts from
1242        the distributed pom.xml graph of Maven Aether:
1243        \begin{enumerate}
1244          \item \code{jna} 
1245            Dynamically load 'jna.jar' version 4.2.2
1246            from the network \footnote{This loading can be inhibited
1247              if, at runtime, the Java class corresponding
1248              ``:classname'' clause of the system defition is present.}
1249        \end{enumerate}
1250      \item \code{quicklisp-abcl} Boot a local Quicklisp installation
1251        via the ASDF:IRI type introduced via ABCL-ASDF.
1252
1253      \item \code{jfli} A descendent of Rich Hickey's pre-Clojure work
1254        on the JVM.
1255      \item \code{jss} Introduces dynamic inspection of present
1256        symbols via the \code{SHARPSIGN-DOUBLE-QUOTE} macros as Java Syntax
1257        Sucks
1258\end{enumerate}
1259
1260\end{description}
1261
1262The user may extend the \code{CL:REQUIRE} mechanism by pushing
1263function hooks into \code{SYSTEM:*MODULE-PROVIDER-FUNCTIONS*}.  Each
1264such hook function takes a single argument containing the symbol
1265passed to \code{CL:REQUIRE} and returns a non-\code{NIL} value if it
1266can successful resolve the symbol.
1267
1268\section{JSS extension of the Reader by SHARPSIGN-DOUBLE-QUOTE}
1269
1270The JSS contrib consitutes an additional, optional extension to the
1271reader in the definition of the \code{SHARPSIGN-DOUBLE-QUOTE}
1272(``\#\"'') reader macro.  See section \ref{section:jss} on page
1273\pageref{section:jss} for more information.
1274
1275\section{ASDF}
1276
1277asdf-3.1.6 (see \cite{asdf}) is packaged as core component of \textsc{ABCL},
1278but not initialized by default, as it relies on the \textsc{CLOS} subsystem
1279which can take a bit of time to start \footnote{While this time is
1280  ``merely'' on the order of seconds for contemporary 2011 machines,
1281  for applications that need to initialize quickly, for example a web
1282  server, this time might be unnecessarily long}.  The packaged \textsc{ASDF}
1283may be loaded by the \textsc{ANSI} \code{REQUIRE} mechanism as
1284follows:
1285
1286\begin{listing-lisp}
1287CL-USER> (require 'asdf)
1288\end{listing-lisp}
1289
1290\chapter{Contrib}
1291
1292The \textsc{ABCL} contrib is packaged as a separate jar archive usually named
1293\code{abcl-contrib.jar} or possibly something like
1294\code{abcl-contrib-1.3.0.jar}.  The contrib jar is not loaded by the
1295implementation by default, and must be first intialized by the
1296\code{REQUIRE} mechanism before using any specific contrib:
1297
1298\begin{listing-lisp}
1299CL-USER> (require 'abcl-contrib)
1300\end{listing-lisp}
1301
1302\section{abcl-asdf}
1303
1304This contrib enables an additional syntax for \textsc{ASDF} system
1305definition which dynamically loads \textsc{JVM} artifacts such as jar
1306archives via encapsulation of the Maven build tool.  The Maven Aether
1307component can also be directly manipulated by the function associated
1308with the \code{ABCL-ASDF:RESOLVE-DEPENDENCIES} symbol.
1309
1310%ABCL specific contributions to ASDF system definition mainly
1311%concerned with finding JVM artifacts such as jar archives to be
1312%dynamically loaded.
1313
1314
1315When loaded, abcl-asdf adds the following objects to \textsc{ASDF}:
1316\code{JAR-FILE}, \code{JAR-DIRECTORY}, \code{CLASS-FILE-DIRECTORY} and
1317\code{MVN}, exporting them (and others) as public symbols.
1318
1319\subsection{Referencing Maven Artifacts via ASDF}
1320
1321Maven artifacts may be referenced within \textsc{ASDF} system
1322definitions, as the following example references the
1323\code{log4j-1.4.9.jar} JVM artifact which provides a widely-used
1324abstraction for handling logging systems:
1325
1326\begin{listing-lisp}
1327;;;; -*- Mode: LISP -*-
1328(in-package :asdf)
1329
1330(defsystem :log4j
1331  :components ((:mvn "log4j/log4j" :version "1.4.9")))
1332\end{listing-lisp}
1333
1334\subsection{API}
1335
1336We define an API for \textsc{ABCL-ASDF} as consisting of the following
1337ASDF classes:
1338
1339\code{JAR-DIRECTORY}, \code{JAR-FILE}, and
1340\code{CLASS-FILE-DIRECTORY} for JVM artifacts that have a currently
1341valid pathname representation.
1342
1343Both the MVN and IRI classes descend from ASDF-COMPONENT, but do not
1344directly have a filesystem location.
1345
1346For use outside of ASDF system definitions, we currently define one
1347method, \code{ABCL-ASDF:RESOLVE-DEPENDENCIES} which locates,
1348downloads, caches, and then loads into the currently executing JVM
1349process all recursive dependencies annotated in the Maven pom.xml
1350graph.
1351
1352\subsection{Directly Instructing Maven to Download JVM Artifacts}
1353
1354Bypassing \textsc{ASDF}, one can directly issue requests for the Maven
1355artifacts to be downloaded
1356
1357\begin{listing-lisp}
1358CL-USER> (abcl-asdf:resolve-dependencies "com.google.gwt"
1359                                         "gwt-user")
1360WARNING: Using LATEST for unspecified version.
1361"/Users/evenson/.m2/repository/com/google/gwt/gwt-user/2.4.0-rc1
1362/gwt-user-2.4.0-rc1.jar:/Users/evenson/.m2/repository/javax/vali
1363dation/validation-api/1.0.0.GA/validation-api-1.0.0.GA.jar:/User
1364s/evenson/.m2/repository/javax/validation/validation-api/1.0.0.G
1365A/validation-api-1.0.0.GA-sources.jar"
1366\end{listing-lisp}
1367
1368To actually load the dependency, use the \code{JAVA:ADD-TO-CLASSPATH} generic
1369function:
1370
1371\begin{listing-lisp}
1372CL-USER> (java:add-to-classpath
1373          (abcl-asdf:resolve-dependencies "com.google.gwt"
1374                                          "gwt-user"))
1375\end{listing-lisp}
1376
1377Notice that all recursive dependencies have been located and installed
1378locally from the network as well.
1379
1380More extensive documentations and examples can be found at
1381\url{http://abcl.org/svn/tags/1.3.0/contrib/abcl-asdf/README.markdown}.
1382
1383
1384\section{asdf-jar}
1385
1386The asdf-jar contrib provides a system for packaging \textsc{ASDF}
1387systems into jar archives for \textsc{ABCL}.  Given a running
1388\textsc{ABCL} image with loadable \textsc{ASDF} systems the code in
1389this package will recursively package all the required source and
1390fasls in a jar archive.
1391
1392The documentation for this contrib can be found at
1393\url{http://abcl.org/svn/tags/1.3.0/contrib/asdf-jar/README.markdown}.
1394
1395
1396\section{jss}
1397\label{section:jss}
1398
1399To one used to the more universal syntax of Lisp pairs upon which the
1400definition of read and compile time macros is quite
1401natural \footnote{See Graham's ``On Lisp''
1402  http://lib.store.yahoo.net/lib/paulgraham/onlisp.pdf.}, the Java
1403syntax available to the Java programmer may be said to suck.  To
1404alleviate this situation, the JSS contrib introduces the
1405\code{SHARPSIGN-DOUBLE-QUOTE} (\code{\#"}) reader macro, which allows
1406the the specification of the name of invoking function as the first
1407element of the relevant s-expr which tends to be more congruent to how
1408Lisp programmers seem to be wired to think.
1409
1410While quite useful, we don't expect that the JSS contrib will be the
1411last experiment in wrangling Java from Common Lisp.
1412
1413\subsection{JSS usage}
1414
1415Example:
1416
1417\begin{listing-lisp}
1418CL-USER> (require 'abcl-contrib)
1419==> ("ABCL-CONTRIB")
1420CL-USER> (require 'jss)
1421==> ("JSS")
1422CL-USER) (#"getProperties" 'java.lang.System)
1423==> #<java.util.Properties {java.runtime.name=Java.... {2FA21ACF}>
1424CL-USER) (#"propertyNames" (#"getProperties" 'java.lang.System))
1425==> #<java.util.Hashtable$Enumerator java.util.Has.... {36B4361A}>
1426\end{listing-lisp} %$ <-- un-confuse Emacs font-lock
1427
1428Some more information on jss can be found in its documentation at
1429\url{http://abcl.org/svn/tags/1.3.0/contrib/jss/README.markdown}
1430
1431\section{jfli}
1432\label{section:jfli}
1433
1434The contrib contains a pure-Java version of JFLI.
1435
1436\url{http://abcl.org/svn/tags/1.3.0/contrib/jfli/README}.
1437
1438
1439\chapter{History}
1440\index{History}
1441
1442\textsc{ABCL} was originally the extension language for the J editor, which was
1443started in 1998 by Peter Graves.  Sometime in 2003, a whole lot of
1444code that had previously not been released publically was suddenly
1445committed that enabled ABCL to be plausibly termed an emergent ANSI
1446Common Lisp implementation candidate.
1447
1448From 2006 to 2008, Peter manned the development lists, incorporating
1449patches as made sense.  After a suitable search, Peter nominated Erik
1450H\"{u}lsmann to take over the project.
1451
1452In 2008, the implementation was transferred to the current
1453maintainers, who have strived to improve its usability as a
1454contemporary Common Lisp implementation.
1455
1456On October 22, 2011, with the publication of this Manual explicitly
1457stating the conformance of Armed Bear Common Lisp to \textsc{ANSI}, we
1458released abcl-1.0.0.  We released abcl-1.0.1 as a maintainence release
1459on January 10, 2012.
1460
1461In December 2012, we revised the implementation by adding
1462\textsc{(A)MOP} with the release of abcl-1.1.0.  We released
1463abcl-1.1.1 as a maintainence release on Feburary 14, 2013.
1464
1465At the beginning of June 2013, we enhanced the stability of the
1466implementation with the release of abcl-1.2.1.
1467
1468In March 2014, we introduced the Fourth Edition of the implementation
1469with abcl-1.3.0.  At the end of April 2014, we released abcl-1.3.1 as
1470a maintainence release.
1471
1472\appendix 
1473
1474\chapter{The MOP Dictionary}
1475
1476\include{mop}
1477
1478\chapter{The SYSTEM Dictionary}
1479
1480The public interfaces in this package are subject to change with
1481\textsc{ABCL} 1.5.
1482
1483\include{system}
1484
1485\chapter{The JSS Dictionary}
1486
1487These public interfaces are provided by the JSS contrib.
1488
1489\include{jss}
1490
1491\bibliography{abcl}
1492\bibliographystyle{alpha}
1493
1494\printindex
1495
1496\end{document}
Note: See TracBrowser for help on using the repository browser.