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

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

Merging a "plain file" path on non-Windows gets an :UNSPECIFIC DEVICE.

If the defaults contain a JAR-PATHNAME, and the pathname to be be
merged does not have a specified DEVICE, a specified HOST, and doesn't
contain a relative DIRECTORY, then on non-MSDOG, set its device to
:UNSPECIFIC.

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