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

Last change on this file since 15261 was 15261, checked in by Mark Evenson, 2 years ago

abcl-1.6.1: update version metadata for release

Note CHANGES.

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