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

Last change on this file since 13626 was 13626, checked in by astalla, 10 years ago

Manual: documented the JSR-223 implementation.

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