source: branches/1.1.x/doc/manual/abcl.tex @ 14292

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

manual: spellcheck and line-editing.

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