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

Last change on this file since 15464 was 15464, checked in by Mark Evenson, 9 months ago

abcl 1.8.0 metadata

rc14

TODO manual needs much description about pathnames

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