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

Last change on this file since 14615 was 14615, checked in by Mark Evenson, 8 years ago

Documentation & metadata updates prior to abcl-1.3.0 branch.

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