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