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

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

Bump trunk to abcl-1.2-dev

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