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

Last change on this file since 13628 was 13628, checked in by Mark Evenson, 10 years ago

Adjustments to voice and presentation in the manual.

File size: 34.3 KB
Line 
1% -*- mode: latex; -*-
2% http://en.wikibooks.org/wiki/LaTeX/
3\documentclass[10pt]{book}
4\usepackage{abcl}
5
6\begin{document}
7\title{A Manual for Armed Bear Common Lisp}
8\date{October 13, 2011}
9\author{Mark~Evenson, Erik~Huelsmann, Alessio~Stalla, Ville~Voutilainen}
10
11\maketitle
12
13\chapter{Introduction}
14
15Armed Bear is a mostly conforming implementation of the ANSI Common
16Lisp standard.  This manual documents the Armed Bear Common Lisp
17implementation for users of the system.
18
19\subsection{Version}
20This manual corresponds to abcl-0.28.0, as yet unreleased.
21
22\chapter{Running}
23
24\textsc{ABCL} is packaged as a single jar file usually named either
25``abcl.jar'' or something like``abcl-0.28.0.jar'' if you are using a
26versioned package from your system vendor.  This byte archive can be
27executed under the control of a suitable JVM by using the ``-jar''
28option to parse the manifest, and select the named class
29(\code{org.armedbear.lisp.Main}) for excution:
30
31\begin{listing-shell}
32  cmd$ java -jar abcl.jar
33\end{listing-shell}
34
35N.b. for the proceeding command to work, the ``java'' executable needs
36to be in your path.
37
38To make it easier to facilitate the use of ABCL in tool chains (such as
39SLIME) the invocation is wrapped in a Bourne shell script under UNIX
40or a DOS command script under Windows so that ABCL may be executed
41simply as:
42
43\begin{listing-shell}
44  cmd$ abcl
45\end{listing-shell}
46
47\section{Options}
48
49ABCL supports the following command line options:
50
51\begin{verbatim}
52--help
53    Displays this message.
54--noinform
55    Suppresses the printing of startup information and banner.
56--noinit
57    Suppresses the loading of the '~/.abclrc' startup file.
58--nosystem
59    Suppresses loading the 'system.lisp' customization file.
60--eval <FORM>
61    Evaluates the <FORM> before initializing REPL.
62--load <FILE>
63    Loads the file <FILE> before initializing REPL.
64--load-system-file <FILE>
65    Loads the system file <FILE> before initializing REPL.
66--batch
67    The process evaluates forms specified by arguments and possibly by those
68    by those in the intialization file '~/.abcl', and then exits.
69
70The occurance of '--' copies the remaining arguments, unprocessed, into
71the variable EXTENSIONS:*COMMAND-LINE-ARGUMENT-LIST*.
72\end{verbatim}
73
74All of the command line arguments which follow the occurrence of ``--''
75are passed into a list bound to the EXT:*COMMAND-LINE-ARGUMENT-LIST*
76variable.
77
78\section{Initialization}
79
80If the ABCL process is started without the ``--noinit'' flag, it
81attempts to load a file named ``.abclrc'' located in the user's home
82directory and then interpret its contents. 
83
84The user's home directory is determined by the value of the JVM system
85property ``user.home''.
86
87\chapter{Conformance}
88
89\section{ANSI Common Lisp}
90\textsc{ABCL} is currently a non-conforming ANSI Common Lisp implementation due
91to the following issues:
92
93\begin{itemize}
94  \item The generic function signatures of the DOCUMENTATION symbol do
95    not match the CLHS.
96\end{itemize}
97
98ABCL aims to be be a fully conforming ANSI Common Lisp
99implementation.  Any other behavior should be reported as a bug.
100
101\section{Contemporary Common Lisp}
102In addition to ANSI conformance, \textsc{ABCL} strives to implement features
103expected of a contemporary Common Lisp.
104\begin{itemize}
105  \item Incomplete (A)MOP
106    % N.B.
107    % TODO go through AMOP with symbols, starting by looking for
108    % matching function signature.
109    % XXX is this really blocking ANSI conformance?  Answer: we have
110    % to start with such a ``census'' to determine what we have.
111  \item Incomplete Streams:  need suitable abstraction between ANSI
112    and Gray streams.
113   
114\end{itemize}
115
116\chapter{Interaction with host JVM}
117
118% describe calling Java from Lisp, and calling Lisp from Java,
119% probably in two separate sections.  Presumably, we can partition our
120% audience into those who are more comfortable with Java, and those
121% that are more comforable with Lisp
122
123\section{Lisp to Java}
124
125\textsc{ABCL} offers a number of mechanisms to interact with Java from its
126Lisp environment. It allows calling both instance and static methods
127of Java objects, manipulation of instance and static fields on Java
128objects, and construction of new Java objects.
129
130When calling Java routines, some values will automatically be
131converted by the FFI \footnote{FFI stands for Foreign Function
132  Interface which is the term of art which describes how a Lisp
133  implementation encapsulates invocation in other languages.}  from
134Lisp values to Java values. These conversions typically apply to
135strings, integers and floats. Other values need to be converted to
136their Java equivalents by the programmer before calling the Java
137object method. Java values returned to Lisp are also generally
138converted back to their Lisp counterparts. Some operators make an
139exception to this rule and do not perform any conversion; those are
140the ``raw'' counterparts of certain FFI functions and are recognizable
141by their name ending with \code{-RAW}.
142
143\subsection{Lowlevel Java API}
144
145There's a higher level Java API defined in the
146\ref{topic:Higher level Java API: JSS}(JSS package) which is available
147in the \code{contrib/} directory. This package is described later in this
148document.  This section covers the lower level API directly available
149after evaluating \code{(require 'JAVA)}.
150
151\subsubsection{Calling Java object methods}
152
153There are two ways to call a Java object method in the basic API:
154
155\begin{itemize}
156\item Call a specific method reference (pre-acquired)
157\item Dynamic dispatch using the method name and
158  the call-specific arguments provided by finding the
159  \ref{section:Parameter matching for FFI dynamic dispatch}{best match}.
160\end{itemize}
161
162The dynamic dispatch variant is discussed in the next section.
163
164\code{JAVA:JMETHOD} is used to acquire a specific method reference.
165The function takes at two or more arguments. The first is Java class designator
166(a \code{JAVA:JAVA-CLASS} object returned by \code{JAVA:JCLASS} or a string naming
167a Java class). The second is a string naming the method.
168
169Any arguments beyond the first two should be strings naming Java classes with
170one exception as listed in the next paragraph. These
171classes specify the types of the arguments for the method to be returned.
172
173There's additional calling convention to the \code{JAVA:JMETHOD} function:
174When the method is called with three parameters and the last parameter is an
175integer, the first method by that name and matching number of parameters is
176returned.
177
178Once you have a reference to the method, you can call it using \code{JAVA:JCALL},
179which takes the method as the first argument. The second argument is the
180object instance to call the method on, or \code{NIL} in case of a static method.
181Any remaining parameters are used as the remaining arguments for the call.
182
183\subsubsection{Calling Java object methods: dynamic dispatch}
184
185The second way of calling Java object methods is by using dynamic dispatch.
186In this case \code{JAVA:JCALL} is used directly without acquiring a method
187reference first. In this case, the first argument provided to \code{JAVA:JCALL}
188is a string naming the method to be called. The second argument is the instance
189on which the method should be called and any further arguments are used to
190select the best matching method and dispatch the call.
191
192\subsubsection{Dynamic dispatch: caveats}
193
194Dynamic dispatch is performed by using the Java reflection
195API \footnote{The Java reflection API is found in the
196  \code{java.lang.reflect} package}. Generally the dispatch works
197fine, but there are corner cases where the API does not correctly
198reflect all the details involved in calling a Java method. An example
199is the following Java code:
200
201\begin{listing-java}
202ZipFile jar = new ZipFile("/path/to/some.jar");
203Object els = jar.entries();
204Method method = els.getClass().getMethod("hasMoreElements");
205method.invoke(els);
206\end{listing-java}
207
208even though the method \code{hasMoreElements()} is public in \code{Enumeration},
209the above code fails with
210
211\begin{listing-java}
212java.lang.IllegalAccessException: Class ... can
213not access a member of class java.util.zip.ZipFile$2 with modifiers
214"public"
215       at sun.reflect.Reflection.ensureMemberAccess(Reflection.java:65)
216       at java.lang.reflect.Method.invoke(Method.java:583)
217       at ...
218\end{listing-java}
219
220because the method has been overridden by a non-public class and the
221reflection API, unlike javac, is not able to handle such a case.
222
223While code like that is uncommon in Java, it is typical of ABCL's FFI
224calls. The code above corresponds to the following Lisp code:
225
226\begin{listing-lisp}
227(let ((jar (jnew "java.util.zip.ZipFile" "/path/to/some.jar")))
228  (let ((els (jcall "entries" jar)))
229    (jcall "hasMoreElements" els)))
230\end{listing-lisp}
231
232except that the dynamic dispatch part is not shown.
233
234To avoid such pitfalls, all Java objects in \textsc{ABCL} carry an extra
235field representing the ``intended class'' of the object. That is the class
236that is used first by \code{JAVA:JCALL} and similar to resolve methods;
237the actual class of the object is only tried if the method is not found
238in the intended class. Of course, the intended class is always a superclass
239of the actual class - in the worst case, they coincide. The intended class
240is deduced by the return type of the method that originally returned
241the Java object; in the case above, the intended class of \code{ELS}
242is \code{java.util.Enumeration} because that's the return type of
243the \code{entries} method.
244
245While this strategy is generally effective, there are cases where the
246intended class becomes too broad to be useful. The typical example
247is the extraction of an element from a collection, since methods in
248the collection API erase all types to \code{Object}. The user can
249always force a more specific intended class by using the \code{JAVA:JCOERCE}
250operator.
251
252% \begin{itemize}
253% \item Java values are accessible as objects of type JAVA:JAVA-OBJECT.
254% \item The Java FFI presents a Lisp package (JAVA) with many useful
255%   symbols for manipulating the artifacts of expectation on the JVM,
256%   including creation of new objects \ref{JAVA:JNEW}, \ref{JAVA:JMETHOD}), the
257%   introspection of values \ref{JAVA:JFIELD}, the execution of methods
258%   (\ref{JAVA:JCALL}, \ref{JAVA:JCALL-RAW}, \ref{JAVA:JSTATIC})
259% \item The JSS package (\ref{JSS}) in contrib introduces a convenient macro
260%   syntax \ref{JSS:SHARPSIGN_DOUBLEQUOTE_MACRO} for accessing Java
261%   methods, and additional convenience functions.
262% \item Java classes and libraries may be dynamically added to the
263%   classpath at runtime (JAVA:ADD-TO-CLASSPATH).
264% \end{itemize}
265
266\subsubsection{Calling Java class static methods}
267
268Like with non-static methods, references to static methods can be acquired
269by using the \code{JAVA:JMETHOD} primitive. In order to call this method,
270it's not possible to use the \code{JAVA:JCALL} primitive however: there's a
271separate API to retrieve a reference to static methods. This
272primitive is called \code{JAVA:JSTATIC}.
273
274Like \code{JAVA:JCALL}, \code{JAVA:JSTATIC} supports dynamic dispatch by
275passing the name of the method as a string instead of passing a method reference.
276The parameter values should be values to pass in the function call instead of
277a specification of classes for each parameter.
278
279\subsubsection{Parameter matching for FFI dynamic dispatch}
280
281The algorithm used to resolve the best matching method given the name
282and the arguments' types is the same as described in the Java Language
283Specification. Any deviation should be reported as a bug.
284
285% ###TODO reference to correct JLS section
286
287\subsubsection{Instantiating Java objects}
288
289Java objects can be instantiated (created) from Lisp by calling
290a constructor from the class of the object to be created. The same way
291\code{JAVA:JMETHOD} is used to acquire a method reference, the
292\code{JAVA:JCONSTRUCTOR} primitive can be used to acquire a constructor
293reference. It's arguments specify the types of arguments of the constructor
294method the same way as with \code{JAVA:JMETHOD}.
295
296The constructor can't be passed to \code{JAVA:JCALL}, but instead should
297be passed as an argument to \code{JAVA:JNEW}.
298
299\section{Lisp from Java}
300
301In order to access the Lisp world from Java, one needs to be aware
302of a few things. The most important ones are listed below.
303
304\begin{itemize}
305\item All Lisp values are descendants of LispObject.java
306\item In order to
307\item Lisp symbols are accessible via either directly referencing the
308  Symbol.java instance or by dynamically introspecting the
309  corresponding Package.java instance.
310\item The Lisp dynamic environment may be saved via
311  \code{LispThread.bindSpecial(Binding)} and restored via
312  \code{LispThread.resetSpecialBindings(Mark)}.
313\item Functions may be executed by invocation of the
314  Function.execute(args [...]) 
315\end{itemize}
316
317\subsection{Lisp FFI}
318
319FFI stands for "Foreign Function Interface" which is the phase which
320the contemporary Lisp world refers to methods of "calling out" from
321Lisp into "foreign" languages and environments.  This document
322describes the various ways that one interacts with Lisp world of ABCL
323from Java, considering the hosted Lisp as the "Foreign Function" that
324needs to be "Interfaced".
325
326\subsection{Calling Lisp from Java}
327
328Note: As the entire ABCL Lisp system resides in the org.armedbear.lisp
329package the following code snippets do not show the relevant import
330statements in the interest of brevity.  An example of the import
331statement would be
332
333\begin{listing-java}
334  import org.armedbear.lisp.*;
335\end{listing-java}
336
337to potentially import all the JVM symbol from the `org.armedbear.lisp'
338namespace.
339
340Per JVM, there can only ever be a single Lisp interpreter.  This is
341started by calling the static method `Interpreter.createInstance()`.
342
343\begin{listing-java}
344  Interpreter interpreter = Interpreter.createInstance();
345\end{listing-java}
346
347If this method has already been invoked in the lifetime of the current
348Java process it will return null, so if you are writing Java whose
349life-cycle is a bit out of your control (like in a Java servlet), a
350safer invocation pattern might be:
351
352\begin{listing-java}
353  Interpreter interpreter = Interpreter.getInstance();
354  if (interpreter == null) {
355    interpreter = Interpreter.createInstance();
356  }
357\end{listing-java}
358
359
360The Lisp \code{eval} primitive may be simply passed strings for evaluation,
361as follows
362
363\begin{listing-java}
364  String line = "(load \"file.lisp\")";
365  LispObject result = interpreter.eval(line);
366\end{listing-java}
367
368Notice that all possible return values from an arbitrary Lisp
369computation are collapsed into a single return value.  Doing useful
370further computation on the ``LispObject'' depends on knowing what the
371result of the computation might be, usually involves some amount
372of \code{instanceof} introspection, and forms a whole topic to itself
373(c.f. [Introspecting a LispObject])
374
375Using \code{eval} involves the Lisp interpreter.  Lisp functions may
376be directly invoked by Java method calls as follows.  One simply
377locates the package containing the symbol, then obtains a reference to
378the symbol, and then invokes the \code{execute()} method with the
379desired parameters.
380
381\begin{listing-java}
382    interpreter.eval("(defun foo (msg) (format nil \"You told me '~A'~%\" msg))");
383    Package pkg = Packages.findPackage("CL-USER");
384    Symbol foo = pkg.findAccessibleSymbol("FOO");
385    Function fooFunction = (Function)foo.getSymbolFunction();
386    JavaObject parameter = new JavaObject("Lisp is fun!");
387    LispObject result = fooFunction.execute(parameter);
388    // How to get the "naked string value"?
389    System.out.println("The result was " + result.writeToString());
390\end{listing-java}
391
392If one is calling an primitive function in the CL package the syntax
393becomes considerably simpler.  If we can locate the instance of
394definition in the ABCL Java source, we can invoke the symbol directly.
395For instnace, to tell if a `LispObject` contains a reference to a symbol.
396
397\begin{listing-java}
398    boolean nullp(LispObject object) {
399      LispObject result = Primitives.NULL.execute(object);
400      if (result == NIL) { // the symbol 'NIL' is explicity named in the Java
401                           // namespace at ``Symbol.NIL''
402                           // but is always present in the
403                           // localnamespace in its unadorned form for
404                           // the convenience of the User.
405        return false;
406      }
407      return true;
408   }
409\end{listing-java}
410
411\subsubsection{Introspecting a LispObject}
412\label{topic:Introspecting a LispObject}
413
414We present various patterns for introspecting an an arbitrary
415`LispObject` which can represent the result of every Lisp evaluation
416into semantics that Java can meaningfully deal with.
417
418\subsubsection{LispObject as \code{boolean}}
419
420If the LispObject a generalized boolean values, one can use
421\code{getBooleanValue()} to convert to Java:
422
423\begin{listing-java}
424     LispObject object = Symbol.NIL;
425     boolean javaValue = object.getBooleanValue();
426\end{listing-java}
427
428Although since in Lisp, any value other than NIL means "true"
429(so-called generalized Boolean), the use of Java equality it quite a
430bit easier to type and more optimal in terms of information it conveys
431to the compiler would be:
432
433\begin{listing-java}
434    boolean javaValue = (object != Symbol.NIL);
435\end{listing-java}
436
437\paragraph{LispObject is a list}
438
439If LispObject is a list, it will have the type `Cons`.  One can then use
440the \code{copyToArray} to make things a bit more suitable for Java
441iteration.
442
443\begin{listing-java}
444    LispObject result = interpreter.eval("'(1 2 4 5)");
445    if (result instanceof Cons) {
446      LispObject array[] = ((Cons)result.copyToArray());
447      ...
448    }
449\end{listing-java}
450
451A more Lispy way to iterated down a list is to use the `cdr()` access
452function just as like one would traverse a list in Lisp:;
453
454\begin{listing-java}
455    LispObject result = interpreter.eval("'(1 2 4 5)");
456    while (result != Symbol.NIL) {
457      doSomething(result.car());
458      result = result.cdr();
459    }
460\end{listing-java}
461
462\subsection{Java Scripting API (JSR-223)}
463
464ABCL can be built with support for JSR-223, which offers a language-agnostic
465API to invoke other languages from Java. The binary distribution downloadable
466from ABCL's common-lisp.net home is built with JSR-223 support. If you're building
467ABCL from source on a pre-1.6 JVM, you need to have a JSR-223 implementation in your
468CLASSPATH (such as Apache Commons BSF 3.x or greater) in order to build ABCL
469with JSR-223 support; otherwise, this feature will not be built.
470
471This section describes the design decisions behind the ABCL JSR-223 support. It is not a description of what JSR-223 is or a tutorial on how to use it. See http://trac.common-lisp.net/armedbear/browser/trunk/abcl/examples/jsr-223 for example usage.
472
473\subsubsection{Conversions}
474
475In general, ABCL's implementation of the JSR-223 API performs implicit conversion from Java objects to Lisp objects when invoking Lisp from Java, and the opposite when returning values from Java to Lisp. This potentially reduces coupling between user code and ABCL. To avoid such conversions, wrap the relevant objects in \code{JavaObject} instances.
476
477\subsubsection{Implemented JSR-223 interfaces}
478
479JSR-223 defines three main interfaces, of which two (Invocable and Compilable) are optional. ABCL implements all the three interfaces - ScriptEngine and the two optional ones - almost completely. While the JSR-223 API is not specific to a single scripting language, it was designed with languages with a more or less Java-like object model in mind: languages such as Javascript, Python, Ruby, which have a concept of "class" or "object" with "fields" and "methods". Lisp is a bit different, so certain adaptations were made, and in one case a method has been left unimplemented since it does not map at all to Lisp.
480
481\subsubsection{The ScriptEngine}
482
483The main interface defined by JSR-223, javax.script.ScriptEngine, is implemented by the class \code{org.armedbear.lisp.scripting.AbclScriptEngine}. AbclScriptEngine is a singleton, reflecting the fact that ABCL is a singleton as well. You can obtain an instance of AbclScriptEngine using the  AbclScriptEngineFactory or by using the service provider mechanism through ScriptEngineManager (refer to the javax.script documentation).
484
485\subsubsection{Startup and configuration file}
486
487At startup (i.e. when its constructor is invoked, as part of the static initialization phase of AbclScriptEngineFactory) the ABCL script engine attempts to load an "init file" from the classpath (/abcl-script-config.lisp). If present, this file can be used to customize the behaviour of the engine, by setting a number of variables in the ABCL-SCRIPT package. Here is a list of the available variables:
488
489\begin{itemize}
490\item *use-throwing-debugger* Controls whether ABCL uses a non-standard debugging hook function to throw a Java exception instead of dropping into the debugger in case of unhandled error conditions.
491  \begin{itemize}
492  \item Default value: T
493  \item Rationale: it is more convenient for Java programmers using Lisp as a scripting language to have it return exceptions to Java instead of handling them in the Lisp world.
494  \item Known Issues: the non-standard debugger hook has been reported to misbehave in certain circumstances, so consider disabling it if it doesn't work for you.
495  \end{itemize}
496\item *launch-swank-at-startup* If true, Swank will be launched at startup. See *swank-dir* and *swank-port*.
497  \begin{itemize}
498  \item Default value: NIL
499  \end{itemize}
500\item *swank-dir* The directory where Swank is installed. Must be set if *launch-swank-at-startup* is true.
501\item *swank-port* The port where Swank will listen for connections. Must be set if *launch-swank-at-startup* is true.
502  \begin{itemize}
503  \item Default value: 4005
504  \end{itemize}
505\end{itemize}
506
507Additionally, at startup the AbclScriptEngine will \code{(require 'asdf)} - in fact, it uses asdf to load Swank.
508
509\subsubsection{Evaluation}
510
511Code is read and evaluated in the package ABCL-SCRIPT-USER. This packages USEs the COMMON-LISP, JAVA and ABCL-SCRIPT packages. Future versions of the script engine might make this default package configurable. The \code{CL:LOAD} function is used under the hood for evaluating code, and thus the same behavior of LOAD is guaranteed. This allows, among other things, \code{IN-PACKAGE} forms to change the package in which the loaded code is read.
512
513It is possible to evaluate code in what JSR-223 calls a "ScriptContext" (basically a flat environment of name->value pairs). This context is used to establish special bindings for all the variables defined in it; since variable names are strings from Java's point of view, they are first interned using READ-FROM-STRING with, as usual, ABCL-SCRIPT-USER as the default package. Variables are declared special because CL's \code{LOAD}, \code{EVAL} and \code{COMPILE} functions work in a null lexical environment and would ignore non-special bindings.
514
515Contrary to what the function \code{LOAD} does, evaluation of a series of forms returns the value of the last form instead of T, so the evaluation of short scripts does the Right Thing.
516
517\subsubsection{Compilation}
518
519AbclScriptEngine implements the javax.script.Compilable interface. Currently it only supports compilation using temporary files. Compiled code, returned as an instance of javax.script.CompiledScript, is read, compiled and executed by default in the ABCL-SCRIPT-USER package, just like evaluated code. Differently from evaluated code, though, due to the way the ABCL compiler works, compiled code contains no reference to top-level self-evaluating objects (like numbers or strings). Thus, when evaluated, a piece of compiled code will return the value of the last non-self-evaluating form: for example the code "(do-something) 42" will return 42 when interpreted, but will return the result of (do-something) when compiled and later evaluated. To ensure consistency of behavior between interpreted and compiled code, make sure the last form is always a compound form - at least (identity some-literal-object). Note that this issue should not matter in real code, where it is unlikely a top-level self-evaluating form will appear as the last form in a file (in fact, the Common Lisp load function always returns T upon success; with JSR-223 this policy has been changed to make evaluation of small code snippets work as intended).
520
521\subsubsection{Invocation of functions and methods}
522
523AbclScriptEngine implements the \code{javax.script.Invocable} interface, which allows to directly call Lisp functions and methods, and to obtain Lisp implementations of Java interfaces. This is only partially possible with Lisp since it has functions, but not methods - not in the traditional OO sense, at least, since Lisp methods are not attached to objects but belong to generic functions. Thus, the method \code{invokeMethod()} is not implemented and throws an UnsupportedOperationException when called. The \code{invokeFunction()} method should be used to call both regular and generic functions.
524
525\subsubsection{Implementation of Java interfaces in Lisp}
526
527ABCL can use the Java reflection-based proxy feature to implement Java interfaces in Lisp. It has several built-in ways to implement an interface, and supports definition of new ones. The \code{JAVA:JMAKE-PROXY} generic function is used to make such proxies. It has the following signature:
528
529\code{jmake-proxy interface implementation \&optional lisp-this ==> proxy}
530
531\code{interface} is a Java interface metaobject (e.g. obtained by invoking \code{jclass}) or a string naming a Java interface. \code{implementation} is the object used to implement the interface - several built-in methods of jmake-proxy exist for various types of implementations. \code{lisp-this} is an object passed to the closures implementing the Lisp "methods" of the interface, and defaults to \code{NIL}.
532
533The returned proxy is an instance of the interface, with methods implemented with Lisp functions.
534
535Built-in interface-implementation types include:
536
537\begin{itemize}
538\item a single Lisp function which upon invocation of any method in the interface will be passed the method name, the Lisp-this object, and all the parameters. Useful for interfaces with a single method, or to implement custom interface-implementation strategies.
539\item a hash-map of method-name -> Lisp function mappings. Function signature is \code{(lisp-this \&rest args)}.
540\item a Lisp package. The name of the Java method to invoke is first transformed in an idiomatic Lisp name (\code{javaMethodName} becomes \code{JAVA-METHOD-NAME}) and a symbol with that name is searched in the package. If it exists and is fbound, the corresponding function will be called. Function signature is as the hash-table case.
541\end{itemize}
542
543This functionality is exposed by the AbclScriptEngine with the two methods getInterface(Class) and getInterface(Object, Class). The former returns an interface implemented with the current Lisp package, the latter allows the programmer to pass an interface-implementation object which will in turn be passed to the jmake-proxy generic function.
544
545\chapter{Implementation Dependent Extensions}
546
547As outlined by the CLHS ANSI conformance guidelines, we document the
548extensions to the Armed Bear Lisp implementation made accessible to
549the user by virtue of being an exported symbol in the JAVA, THREADS,
550or EXTENSIONS packages.
551
552\section{JAVA}
553
554\subsection{Modifying the JVM CLASSPATH}
555
556The JAVA:ADD-TO-CLASSPATH generic functions allows one to add the
557specified pathname or list of pathnames to the current classpath
558used by ABCL, allowing the dynamic loading of JVM objects:
559
560\begin{listing-lisp}
561CL-USER> (add-to-classpath "/path/to/some.jar")
562\end{listing-lisp}
563
564NB \code{add-to-classpath} only affects the classloader used by ABCL
565(the value of the special variable \code{JAVA:*CLASSLOADER*}. It has
566no effect on Java code outside ABCL.
567
568\subsection{API}
569
570% include autogen docs for the JAVA package.
571\include{java}
572
573\section{THREADS}
574
575Multithreading
576
577\subsection{API}
578
579% include autogen docs for the THREADS package.
580\include{threads}
581
582\section{EXTENSIONS}
583
584The symbols in the EXTENSIONS package (nicknamed ``EXT'') constitutes
585extensions to the ANSI standard that are potentially useful to the
586user.  They include functions for manipulating network sockets,
587running external programs, registering object finalizers, constructing
588reference weakly held by the garbage collector and others.
589
590See \ref{Extensible Sequences} for a generic function interface to
591the native JVM contract for \code{java.util.List}.
592
593\subsection{API}
594
595% include autogen docs for the EXTENSIONS package.
596\include{extensions}
597
598\chapter{Beyond ANSI}
599
600Naturally, in striving to be a useful contemporary Common Lisp
601implementation, ABCL endeavors to include extensions beyond the ANSI
602specification which are either widely adopted or are especially useful
603in working with the hosting JVM.
604
605\section{Implementation Dependent}
606\begin{enumerate}
607  \item Compiler to JVM 5 bytecode
608  \item Pathname extensions
609\end{enumerate}
610
611\section{Pathname}
612
613We implment an extension to the Pathname that allows for the
614description and retrieval of resources named in a URI scheme that the
615JVM ``understands''.  Support is built-in to the ``http'' and
616``https'' implementations but additional protocol handlers may be
617installed at runtime by having JVM symbols present in the
618sun.net.protocol.dynmamic pacakge. See [JAVA2006] for more details.
619
620ABCL has created specializations of the ANSI Pathname object to
621enable to use of URIs to address dynamically loaded resources for the
622JVM.  A URL-PATHNAME has a corresponding URL whose cannoical
623representation is defined to be the NAMESTRING of the Pathname.
624
625PATHNAME : URL-PATHNAME : JAR-PATHNAME
626
627Both URL-PATHNAME and JAR-PATHNAME may be used anu where will a
628PATHNAME is accepted witht the following caveats
629
630A stream obtained via OPEN on a URL-PATHNAME cannot be the target of
631write operations.
632
633No canonicalization is performed on the underlying URI (i.e. the
634implementation does not attempt to compute the current name of the
635representing resource unless it is requested to be resolved.)  Upon
636resolution, any cannoicalization procedures followed in resolving the
637resource (e.g. following redirects) are discarded. 
638
639The implementation of URL-PATHNAME allows the ABCL user to laod dynamically
640code from the network.  For example, for Quicklisp.
641
642\begin{listing-lisp}
643  CL-USER> (load "http://beta.quicklisp.org/quicklisp.lisp")
644\end{listing-lisp}
645
646will load and execute the Quicklisp setup code.
647
648\ref{XACH2011}
649         
650\section{Extensible Sequences}
651
652\ref{RHODES2007}
653
654The SEQUENCE package fully implements Christopher Rhodes' proposal for
655extensible sequences.  These user extensible sequences are used
656directly in \code{java-collections.lisp} provide these CLOS
657abstractions on the standard Java collection classes as defined by the
658\code{java.util.List} contract.
659
660This extension is not automatically loaded by the implementation.   It
661may be loaded via:
662
663\begin{listing-lisp}
664CL-USER> (require 'java-collections)
665\end{listing-lisp}
666
667if both extensible sequences and their application to Java collections
668is required, or
669
670\begin{listing-lisp}
671CL-USER> (require 'extensible-sequences)
672\end{listing-lisp}
673
674if only the extensible sequences API as specified in \ref{RHODES2007} is
675required.
676
677Note that \code{(require 'java-collections)} must be issued before
678\code{java.util.List} or any subclass is used as a specializer in a CLOS
679method definition (see the section below).
680
681\section{Extensions to CLOS}
682
683There is an additional syntax for specializing the parameter of a
684generic function on a java class, viz. \code{(java:jclass CLASS-STRING)}
685where \code{CLASS-STRING} is a string naming a Java class in dotted package
686form.
687
688For instance the following specialization would perhaps allow one to
689print more information about the contents of a java.util.Collection
690object
691
692\begin{listing-lisp}
693(defmethod print-object ((coll (java:jclass "java.util.Collection"))
694                         stream)
695  ;;; ...
696)
697\end{listing-lisp}
698
699If the class had been loaded via a classloader other than the original
700the class you wish to specialize on, one needs to specify the
701classloader as an optional third argument.
702
703\begin{listing-lisp}
704
705(defparameter *other-classloader*
706  (jcall "getBaseLoader" cl-user::*classpath-manager*))
707 
708(defmethod print-object ((device-id (java:jclass "dto.nbi.service.hdm.alcatel.com.NBIDeviceID" *other-classloader*))
709                         stream)
710  ;;; ...
711)
712\end{listing-lisp}
713
714\section{Extensions to the Reader}
715
716We implement a special hexadecimal escape sequence for specifying
717characters to the Lisp reader, namely we allow a sequences of the form
718\# \textbackslash Uxxxx to be processed by the reader as character whose code is
719specified by the hexadecimal digits ``xxxx''.  The hexadecimal sequence
720must be exactly four digits long, padded by leading zeros for values
721less than 0x1000.
722
723Note that this sequence is never output by the implementation.  Instead,
724the corresponding Unicode character is output for characters whose
725code is greater than 0x00ff.
726
727\section{ASDF}
728
729asdf-2.017 is packaged as core component of ABCL.  By default, ASDF is
730not loaded, as it relies on the CLOS subsystem which can take a bit of
731time to initialize.
732
733\begin{listing-lisp}
734CL-USER> (require 'asdf)
735\end{listing-lisp}
736
737\chapter{Contrib}
738
739\section{abcl-asdf}
740
741Allow ASDF system definition which dynamically loads JVM artifacts
742such as jar archives via a Maven encapsulation.
743
744ASDF components added:  JAR-FILE, JAR-DIRECTORY, CLASS-FILE-DIRECTORY
745and MVN.
746
747\section{asdf-install}
748
749An implementation of ASDF-INSTALL.  Superceded by Quicklisp (qv.)
750
751\section{asdf-jar}
752
753ASDF-JAR provides a system for packaging ASDF systems into jar
754archives for ABCL.  Given a running ABCL image with loadable ASDF
755systems the code in this package will recursively package all the
756required source and fasls in a jar archive.
757
758\section{jss}
759
760Java Syntax sucks, so we introduce the \#" macro.
761
762
763\chapter{History}
764
765ABCL was originally the extension language for the J editor, which was
766started in 1998 by Peter Graves.  Sometime in 2003, it seems that a
767lot of code that had previously not been released publically was
768suddenly committed that enabled ABCL to be plausibly termed an ANSI
769Common Lisp implementation.
770
771In 2006, the implementation was transferred to the current
772maintainers, who have strived to improve its usability as a
773contemporary Common Lisp implementation.
774
775In 201x, with the publication of this Manual explicitly stating the
776conformance of Armed Bear Common Lisp to ANSI, we release abcl-1.0.
777
778
779
780
781\section{References}
782
783[Java2000]:  A New Era for Java Protocol Handlers.
784\url{http://java.sun.com/developer/onlineTraining/protocolhandlers/}
785
786[Xach2011]:  Quicklisp:  A system for quickly constructing Common Lisp
787libraries.  \url{http://www.quicklisp.org/}
788
789
790\end{document}
791
792% TODO
793%   1.  Create mechanism for swigging DocString and Lisp docs into
794%       sections.
795
Note: See TracBrowser for help on using the repository browser.