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

Last change on this file since 15341 was 15341, checked in by Mark Evenson, 15 months ago

1.7.1: metadata for abcl-1.7.1

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