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

Last change on this file since 15341 was 15341, checked in by Mark Evenson, 3 years ago

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
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
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âŠ").
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
188
190June 1991 with an added classpath-exception'' clause (see the file
191\texttt{COPYING} in the source distribution\footnote{See
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
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.
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 767ScriptContext'' (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} 980understands''. 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
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
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
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
1781    archives from the network.
1782\end{itemize}
1783
1784\url{http://abcl.org/svn/tags/1.7.1/contrib/abcl-build/}.
1785
1789
1790\code{NAMED-READTABLES} is a library that provides a namespace for
1792
1794
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.