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

Last change on this file since 14587 was 14587, checked in by Mark Evenson, 9 years ago

Transform (hopefully) all occurances of old common-lisp.net URIs to abcl.org.

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