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

Last change on this file since 14892 was 14892, checked in by mevenson, 10 months ago

metadata: publish all artifacts for 1.4.0 simultaneously

Update the README <file:README>, CHANGES <file:CHANGES> and the User
manual <file:doc/manual/> for 1.4.0.

<http://abcl.org/trac/changeset/14891>

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