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

Last change on this file since 13634 was 13634, checked in by Mark Evenson, 9 years ago

Examples of JSS usage.

Re-formatted JSR-223 constribution (Thanks Alessio!)

File size: 34.8 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 20, 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 execution:
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{Low-level 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 (which was previously 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 super-class
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 instance, 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 explicitly named in the Java
401                           // namespace at ``Symbol.NIL''
402                           // but is always present in the
403                           // local namespace 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
465language-agnostic API to invoke other languages from Java. The binary
466distribution downloadable from ABCL's common-lisp.net home is built
467with JSR-223 support. If you're building ABCL from source on a pre-1.6
468JVM, you need to have a JSR-223 implementation in your CLASSPATH (such
469as Apache Commons BSF 3.x or greater) in order to build ABCL with
470JSR-223 support; otherwise, this feature will not be built.
471
472This section describes the design decisions behind the ABCL JSR-223
473support. It is not a description of what JSR-223 is or a tutorial on
474how to use it. See
475http://trac.common-lisp.net/armedbear/browser/trunk/abcl/examples/jsr-223
476for example usage.
477
478\subsubsection{Conversions}
479
480In general, ABCL's implementation of the JSR-223 API performs implicit
481conversion from Java objects to Lisp objects when invoking Lisp from
482Java, and the opposite when returning values from Java to Lisp. This
483potentially reduces coupling between user code and ABCL. To avoid such
484conversions, wrap the relevant objects in \code{JavaObject} instances.
485
486\subsubsection{Implemented JSR-223 interfaces}
487
488JSR-223 defines three main interfaces, of which two (Invocable and
489Compilable) are optional. ABCL implements all the three interfaces -
490ScriptEngine and the two optional ones - almost completely. While the
491JSR-223 API is not specific to a single scripting language, it was
492designed with languages with a more or less Java-like object model in
493mind: languages such as Javascript, Python, Ruby, which have a concept
494of "class" or "object" with "fields" and "methods". Lisp is a bit
495different, so certain adaptations were made, and in one case a method
496has been left unimplemented since it does not map at all to Lisp.
497
498\subsubsection{The ScriptEngine}
499
500The main interface defined by JSR-223, javax.script.ScriptEngine, is
501implemented by the class
502\code{org.armedbear.lisp.scripting.AbclScriptEngine}. AbclScriptEngine
503is a singleton, reflecting the fact that ABCL is a singleton as
504well. You can obtain an instance of AbclScriptEngine using the
505AbclScriptEngineFactory or by using the service provider mechanism
506through ScriptEngineManager (refer to the javax.script documentation).
507
508\subsubsection{Startup and configuration file}
509
510At startup (i.e. when its constructor is invoked, as part of the
511static initialization phase of AbclScriptEngineFactory) the ABCL
512script engine attempts to load an "init file" from the classpath
513(/abcl-script-config.lisp). If present, this file can be used to
514customize the behaviour of the engine, by setting a number of
515variables in the ABCL-SCRIPT package. Here is a list of the available
516variables:
517
518\begin{itemize}
519\item *use-throwing-debugger* Controls whether ABCL uses a
520  non-standard debugging hook function to throw a Java exception
521  instead of dropping into the debugger in case of unhandled error
522  conditions.
523  \begin{itemize}
524  \item Default value: T
525  \item Rationale: it is more convenient for Java programmers using
526    Lisp as a scripting language to have it return exceptions to Java
527    instead of handling them in the Lisp world.
528  \item Known Issues: the non-standard debugger hook has been reported
529    to misbehave in certain circumstances, so consider disabling it if
530    it doesn't work for you.
531  \end{itemize}
532\item *launch-swank-at-startup* If true, Swank will be launched at
533  startup. See *swank-dir* and *swank-port*.
534  \begin{itemize}
535  \item Default value: NIL
536  \end{itemize}
537\item *swank-dir* The directory where Swank is installed. Must be set
538  if *launch-swank-at-startup* is true.
539\item *swank-port* The port where Swank will listen for
540  connections. Must be set if *launch-swank-at-startup* is true.
541  \begin{itemize}
542  \item Default value: 4005
543  \end{itemize}
544\end{itemize}
545
546Additionally, at startup the AbclScriptEngine will \code{(require
547  'asdf)} - in fact, it uses asdf to load Swank.
548
549\subsubsection{Evaluation}
550
551Code is read and evaluated in the package ABCL-SCRIPT-USER. This
552packages USEs the COMMON-LISP, JAVA and ABCL-SCRIPT packages. Future
553versions of the script engine might make this default package
554configurable. The \code{CL:LOAD} function is used under the hood for
555evaluating code, and thus the same behavior of LOAD is
556guaranteed. This allows, among other things, \code{IN-PACKAGE} forms
557to change the package in which the loaded code is read.
558
559It is possible to evaluate code in what JSR-223 calls a
560"ScriptContext" (basically a flat environment of name->value
561pairs). This context is used to establish special bindings for all the
562variables defined in it; since variable names are strings from Java's
563point of view, they are first interned using READ-FROM-STRING with, as
564usual, ABCL-SCRIPT-USER as the default package. Variables are declared
565special because CL's \code{LOAD}, \code{EVAL} and \code{COMPILE}
566functions work in a null lexical environment and would ignore
567non-special bindings.
568
569Contrary to what the function \code{LOAD} does, evaluation of a series
570of forms returns the value of the last form instead of T, so the
571evaluation of short scripts does the Right Thing.
572
573\subsubsection{Compilation}
574
575AbclScriptEngine implements the javax.script.Compilable
576interface. Currently it only supports compilation using temporary
577files. Compiled code, returned as an instance of
578javax.script.CompiledScript, is read, compiled and executed by default
579in the ABCL-SCRIPT-USER package, just like evaluated code. Differently
580from evaluated code, though, due to the way the ABCL compiler works,
581compiled code contains no reference to top-level self-evaluating
582objects (like numbers or strings). Thus, when evaluated, a piece of
583compiled code will return the value of the last non-self-evaluating
584form: for example the code "(do-something) 42" will return 42 when
585interpreted, but will return the result of (do-something) when
586compiled and later evaluated. To ensure consistency of behavior
587between interpreted and compiled code, make sure the last form is
588always a compound form - at least (identity some-literal-object). Note
589that this issue should not matter in real code, where it is unlikely a
590top-level self-evaluating form will appear as the last form in a file
591(in fact, the Common Lisp load function always returns T upon success;
592with JSR-223 this policy has been changed to make evaluation of small
593code snippets work as intended).
594
595\subsubsection{Invocation of functions and methods}
596
597AbclScriptEngine implements the \code{javax.script.Invocable}
598interface, which allows to directly call Lisp functions and methods,
599and to obtain Lisp implementations of Java interfaces. This is only
600partially possible with Lisp since it has functions, but not methods -
601not in the traditional OO sense, at least, since Lisp methods are not
602attached to objects but belong to generic functions. Thus, the method
603\code{invokeMethod()} is not implemented and throws an
604UnsupportedOperationException when called. The \code{invokeFunction()}
605method should be used to call both regular and generic functions.
606
607\subsubsection{Implementation of Java interfaces in Lisp}
608
609ABCL can use the Java reflection-based proxy feature to implement Java
610interfaces in Lisp. It has several built-in ways to implement an
611interface, and supports definition of new ones. The
612\code{JAVA:JMAKE-PROXY} generic function is used to make such
613proxies. It has the following signature:
614
615\code{jmake-proxy interface implementation \&optional lisp-this ==> proxy}
616
617\code{interface} is a Java interface metaobject (e.g. obtained by
618invoking \code{jclass}) or a string naming a Java
619interface. \code{implementation} is the object used to implement the
620interface - several built-in methods of jmake-proxy exist for various
621types of implementations. \code{lisp-this} is an object passed to the
622closures implementing the Lisp "methods" of the interface, and
623defaults to \code{NIL}.
624
625The returned proxy is an instance of the interface, with methods
626implemented with Lisp functions.
627
628Built-in interface-implementation types include:
629
630\begin{itemize}
631\item a single Lisp function which upon invocation of any method in
632  the interface will be passed the method name, the Lisp-this object,
633  and all the parameters. Useful for interfaces with a single method,
634  or to implement custom interface-implementation strategies.
635\item a hash-map of method-name -> Lisp function mappings. Function
636  signature is \code{(lisp-this \&rest args)}.
637\item a Lisp package. The name of the Java method to invoke is first
638  transformed in an idiomatic Lisp name (\code{javaMethodName} becomes
639  \code{JAVA-METHOD-NAME}) and a symbol with that name is searched in
640  the package. If it exists and is fbound, the corresponding function
641  will be called. Function signature is as the hash-table case.
642\end{itemize}
643
644This functionality is exposed by the AbclScriptEngine with the two
645methods getInterface(Class) and getInterface(Object, Class). The
646former returns an interface implemented with the current Lisp package,
647the latter allows the programmer to pass an interface-implementation
648object which will in turn be passed to the jmake-proxy generic
649function.
650
651\chapter{Implementation Dependent Extensions}
652
653As outlined by the CLHS ANSI conformance guidelines, we document the
654extensions to the Armed Bear Lisp implementation made accessible to
655the user by virtue of being an exported symbol in the JAVA, THREADS,
656or EXTENSIONS packages.
657
658\section{JAVA}
659
660\subsection{Modifying the JVM CLASSPATH}
661
662The JAVA:ADD-TO-CLASSPATH generic functions allows one to add the
663specified pathname or list of pathnames to the current classpath
664used by ABCL, allowing the dynamic loading of JVM objects:
665
666\begin{listing-lisp}
667CL-USER> (add-to-classpath "/path/to/some.jar")
668\end{listing-lisp}
669
670NB \code{add-to-classpath} only affects the classloader used by ABCL
671(the value of the special variable \code{JAVA:*CLASSLOADER*}. It has
672no effect on Java code outside ABCL.
673
674\subsection{API}
675
676% include autogen docs for the JAVA package.
677\include{java}
678
679\section{THREADS}
680
681Multithreading
682
683\subsection{API}
684
685% include autogen docs for the THREADS package.
686\include{threads}
687
688\section{EXTENSIONS}
689
690The symbols in the EXTENSIONS package (nicknamed ``EXT'') constitutes
691extensions to the ANSI standard that are potentially useful to the
692user.  They include functions for manipulating network sockets,
693running external programs, registering object finalizers, constructing
694reference weakly held by the garbage collector and others.
695
696See \ref{Extensible Sequences} for a generic function interface to
697the native JVM contract for \code{java.util.List}.
698
699\subsection{API}
700
701% include autogen docs for the EXTENSIONS package.
702\include{extensions}
703
704\chapter{Beyond ANSI}
705
706Naturally, in striving to be a useful contemporary Common Lisp
707implementation, ABCL endeavors to include extensions beyond the ANSI
708specification which are either widely adopted or are especially useful
709in working with the hosting JVM.
710
711\section{Implementation Dependent}
712\begin{enumerate}
713  \item Compiler to JVM 5 bytecode
714  \item Pathname extensions
715\end{enumerate}
716
717\section{Pathname}
718
719We implment an extension to the Pathname that allows for the
720description and retrieval of resources named in a URI scheme that the
721JVM ``understands''.  Support is built-in to the ``http'' and
722``https'' implementations but additional protocol handlers may be
723installed at runtime by having JVM symbols present in the
724sun.net.protocol.dynmamic pacakge. See [JAVA2006] for more details.
725
726ABCL has created specializations of the ANSI Pathname object to
727enable to use of URIs to address dynamically loaded resources for the
728JVM.  A URL-PATHNAME has a corresponding URL whose cannoical
729representation is defined to be the NAMESTRING of the Pathname.
730
731PATHNAME : URL-PATHNAME : JAR-PATHNAME
732
733Both URL-PATHNAME and JAR-PATHNAME may be used anu where will a
734PATHNAME is accepted witht the following caveats
735
736A stream obtained via OPEN on a URL-PATHNAME cannot be the target of
737write operations.
738
739No canonicalization is performed on the underlying URI (i.e. the
740implementation does not attempt to compute the current name of the
741representing resource unless it is requested to be resolved.)  Upon
742resolution, any cannoicalization procedures followed in resolving the
743resource (e.g. following redirects) are discarded. 
744
745The implementation of URL-PATHNAME allows the ABCL user to laod dynamically
746code from the network.  For example, for Quicklisp.
747
748\begin{listing-lisp}
749  CL-USER> (load "http://beta.quicklisp.org/quicklisp.lisp")
750\end{listing-lisp}
751
752will load and execute the Quicklisp setup code.
753
754\ref{XACH2011}
755         
756\section{Extensible Sequences}
757
758\ref{RHODES2007}
759
760The SEQUENCE package fully implements Christopher Rhodes' proposal for
761extensible sequences.  These user extensible sequences are used
762directly in \code{java-collections.lisp} provide these CLOS
763abstractions on the standard Java collection classes as defined by the
764\code{java.util.List} contract.
765
766This extension is not automatically loaded by the implementation.   It
767may be loaded via:
768
769\begin{listing-lisp}
770CL-USER> (require 'java-collections)
771\end{listing-lisp}
772
773if both extensible sequences and their application to Java collections
774is required, or
775
776\begin{listing-lisp}
777CL-USER> (require 'extensible-sequences)
778\end{listing-lisp}
779
780if only the extensible sequences API as specified in \ref{RHODES2007} is
781required.
782
783Note that \code{(require 'java-collections)} must be issued before
784\code{java.util.List} or any subclass is used as a specializer in a CLOS
785method definition (see the section below).
786
787\section{Extensions to CLOS}
788
789There is an additional syntax for specializing the parameter of a
790generic function on a java class, viz. \code{(java:jclass CLASS-STRING)}
791where \code{CLASS-STRING} is a string naming a Java class in dotted package
792form.
793
794For instance the following specialization would perhaps allow one to
795print more information about the contents of a java.util.Collection
796object
797
798\begin{listing-lisp}
799(defmethod print-object ((coll (java:jclass "java.util.Collection"))
800                         stream)
801  ;;; ...
802)
803\end{listing-lisp}
804
805If the class had been loaded via a classloader other than the original
806the class you wish to specialize on, one needs to specify the
807classloader as an optional third argument.
808
809\begin{listing-lisp}
810
811(defparameter *other-classloader*
812  (jcall "getBaseLoader" cl-user::*classpath-manager*))
813 
814(defmethod print-object ((device-id (java:jclass "dto.nbi.service.hdm.alcatel.com.NBIDeviceID" *other-classloader*))
815                         stream)
816  ;;; ...
817)
818\end{listing-lisp}
819
820\section{Extensions to the Reader}
821
822We implement a special hexadecimal escape sequence for specifying
823characters to the Lisp reader, namely we allow a sequences of the form
824\# \textbackslash Uxxxx to be processed by the reader as character whose code is
825specified by the hexadecimal digits ``xxxx''.  The hexadecimal sequence
826must be exactly four digits long, padded by leading zeros for values
827less than 0x1000.
828
829Note that this sequence is never output by the implementation.  Instead,
830the corresponding Unicode character is output for characters whose
831code is greater than 0x00ff.
832
833\section{ASDF}
834
835asdf-2.017 is packaged as core component of ABCL, but not intialized
836by default, as it relies on the CLOS subsystem which can take a bit of
837time to initialize.  It may be initialized by the ANSI
838\textsc{REQUIRE} mechanism as follows:
839
840\begin{listing-lisp}
841CL-USER> (require 'asdf)
842\end{listing-lisp}
843
844\chapter{Contrib}
845
846\section{abcl-asdf}
847
848This contrib to ABCL enables an additional syntax for ASDF system
849definition which dynamically loads JVM artifacts such as jar archives
850via a Maven encapsulation.
851
852The following ASDF components are added:  JAR-FILE, JAR-DIRECTORY, CLASS-FILE-DIRECTORY
853and MVN.
854
855\section{asdf-install}
856
857An implementation of ASDF-INSTALL.  Superceded by Quicklisp (qv.)
858
859\section{asdf-jar}
860
861ASDF-JAR provides a system for packaging ASDF systems into jar
862archives for ABCL.  Given a running ABCL image with loadable ASDF
863systems the code in this package will recursively package all the
864required source and fasls in a jar archive.
865
866\section{jss}
867
868To one used to a syntax that can construct macros, the Java syntax
869sucks, so we introduce the \#" macro.
870
871\subsection{JSS usage}
872
873Example:
874
875\begin{listing-lisp}
876  CL-USER> (require 'jss)
877
878  CL-USER) (#"getProperties" 'java.lang.System)
879
880  CL-USER) (#"propertyNames" (#"getProperties" 'java.lang.System))
881\end{listing-lisp}
882
883\chapter{History}
884
885ABCL was originally the extension language for the J editor, which was
886started in 1998 by Peter Graves.  Sometime in 2003, it seems that a
887lot of code that had previously not been released publically was
888suddenly committed that enabled ABCL to be plausibly termed an ANSI
889Common Lisp implementation.
890
891In 2006, the implementation was transferred to the current
892maintainers, who have strived to improve its usability as a
893contemporary Common Lisp implementation.
894
895In 201x, with the publication of this Manual explicitly stating the
896conformance of Armed Bear Common Lisp to ANSI, we release abcl-1.0.
897
898
899
900
901\section{References}
902
903[Java2000]:  A New Era for Java Protocol Handlers.
904\url{http://java.sun.com/developer/onlineTraining/protocolhandlers/}
905
906[Xach2011]:  Quicklisp:  A system for quickly constructing Common Lisp
907libraries.  \url{http://www.quicklisp.org/}
908
909
910\end{document}
911
912% TODO
913%   1.  Create mechanism for swigging DocString and Lisp docs into
914%       sections.
915
Note: See TracBrowser for help on using the repository browser.