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