source: branches/1.0.x/abcl/doc/manual/abcl.tex @ 13643

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

Smooth more nits in Manual.

File size: 36.9 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 21, 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-1.0.0, release on October 22, 2011.
21
22\chapter{Running}
23
24\textsc{ABCL} is packaged as a single jar file usually named either
25``abcl.jar'' or possibly``abcl-1.0.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  \item The TIME form does not return a proper VALUES to its caller.
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, \textsc{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
126\textsc{ABCL} offers a number of mechanisms to interact with Java from its
127Lisp environment. It allows calling both instance and static methods
128of Java objects, manipulation of instance and static fields on Java
129objects, and construction of new Java objects.
130
131When calling Java routines, some values will automatically be
132converted by the FFI \footnote{FFI stands for Foreign Function
133  Interface which is the term of art which describes how a Lisp
134  implementation encapsulates invocation in other languages.}  from
135Lisp values to Java values. These conversions typically apply to
136strings, integers and floats. Other values need to be converted to
137their Java equivalents by the programmer before calling the Java
138object method. Java values returned to Lisp are also generally
139converted back to their Lisp counterparts. Some operators make an
140exception to this rule and do not perform any conversion; those are
141the ``raw'' counterparts of certain FFI functions and are recognizable
142by their name ending with \code{-RAW}.
143
144\subsection{Low-level Java API}
145
146There's a higher level Java API defined in the
147\ref{topic:Higher level Java API: JSS}(JSS package) which is available
148in the \code{contrib/} directory. This package is described later in this
149document.  This section covers the lower level API directly available
150after evaluating \code{(require 'JAVA)}.
151
152\subsubsection{Calling Java object methods}
153
154There are two ways to call a Java object method in the basic API:
155
156\begin{itemize}
157\item Call a specific method reference (which was previously acquired)
158\item Dynamic dispatch using the method name and
159  the call-specific arguments provided by finding the
160  \ref{section:Parameter matching for FFI dynamic dispatch}{best match}.
161\end{itemize}
162
163The dynamic dispatch variant is discussed in the next section.
164
165\code{JAVA:JMETHOD} is used to acquire a specific method reference.
166The function takes at two or more arguments. The first is Java class designator
167(a \code{JAVA:JAVA-CLASS} object returned by \code{JAVA:JCLASS} or a string naming
168a Java class). The second is a string naming the method.
169
170Any arguments beyond the first two should be strings naming Java classes with
171one exception as listed in the next paragraph. These
172classes specify the types of the arguments for the method to be returned.
173
174There's additional calling convention to the \code{JAVA:JMETHOD} function:
175When the method is called with three parameters and the last parameter is an
176integer, the first method by that name and matching number of parameters is
177returned.
178
179Once you have a reference to the method, you can call it using \code{JAVA:JCALL},
180which takes the method as the first argument. The second argument is the
181object instance to call the method on, or \code{NIL} in case of a static method.
182Any remaining parameters are used as the remaining arguments for the call.
183
184\subsubsection{Calling Java object methods: dynamic dispatch}
185
186The second way of calling Java object methods is by using dynamic dispatch.
187In this case \code{JAVA:JCALL} is used directly without acquiring a method
188reference first. In this case, the first argument provided to \code{JAVA:JCALL}
189is a string naming the method to be called. The second argument is the instance
190on which the method should be called and any further arguments are used to
191select the best matching method and dispatch the call.
192
193\subsubsection{Dynamic dispatch: caveats}
194
195Dynamic dispatch is performed by using the Java reflection
196API \footnote{The Java reflection API is found in the
197  \code{java.lang.reflect} package}. Generally the dispatch works
198fine, but there are corner cases where the API does not correctly
199reflect all the details involved in calling a Java method. An example
200is the following Java code:
201
202\begin{listing-java}
203ZipFile jar = new ZipFile("/path/to/some.jar");
204Object els = jar.entries();
205Method method = els.getClass().getMethod("hasMoreElements");
206method.invoke(els);
207\end{listing-java}
208
209even though the method \code{hasMoreElements()} is public in \code{Enumeration},
210the above code fails with
211
212\begin{listing-java}
213java.lang.IllegalAccessException: Class ... can
214not access a member of class java.util.zip.ZipFile\$2 with modifiers
215"public"
216       at sun.reflect.Reflection.ensureMemberAccess(Reflection.java:65)
217       at java.lang.reflect.Method.invoke(Method.java:583)
218       at ...
219\end{listing-java}
220
221because the method has been overridden by a non-public class and the
222reflection API, unlike javac, is not able to handle such a case.
223
224While code like that is uncommon in Java, it is typical of ABCL's FFI
225calls. The code above corresponds to the following Lisp code:
226
227\begin{listing-lisp}
228(let ((jar (jnew "java.util.zip.ZipFile" "/path/to/some.jar")))
229  (let ((els (jcall "entries" jar)))
230    (jcall "hasMoreElements" els)))
231\end{listing-lisp}
232
233except that the dynamic dispatch part is not shown.
234
235To avoid such pitfalls, all Java objects in \textsc{ABCL} carry an extra
236field representing the ``intended class'' of the object. That is the class
237that is used first by \code{JAVA:JCALL} and similar to resolve methods;
238the actual class of the object is only tried if the method is not found
239in the intended class. Of course, the intended class is always a super-class
240of the actual class - in the worst case, they coincide. The intended class
241is deduced by the return type of the method that originally returned
242the Java object; in the case above, the intended class of \code{ELS}
243is \code{java.util.Enumeration} because that's the return type of
244the \code{entries} method.
245
246While this strategy is generally effective, there are cases where the
247intended class becomes too broad to be useful. The typical example
248is the extraction of an element from a collection, since methods in
249the collection API erase all types to \code{Object}. The user can
250always force a more specific intended class by using the \code{JAVA:JCOERCE}
251operator.
252
253% \begin{itemize}
254% \item Java values are accessible as objects of type JAVA:JAVA-OBJECT.
255% \item The Java FFI presents a Lisp package (JAVA) with many useful
256%   symbols for manipulating the artifacts of expectation on the JVM,
257%   including creation of new objects \ref{JAVA:JNEW}, \ref{JAVA:JMETHOD}), the
258%   introspection of values \ref{JAVA:JFIELD}, the execution of methods
259%   (\ref{JAVA:JCALL}, \ref{JAVA:JCALL-RAW}, \ref{JAVA:JSTATIC})
260% \item The JSS package (\ref{JSS}) in contrib introduces a convenient macro
261%   syntax \ref{JSS:SHARPSIGN_DOUBLEQUOTE_MACRO} for accessing Java
262%   methods, and additional convenience functions.
263% \item Java classes and libraries may be dynamically added to the
264%   classpath at runtime (JAVA:ADD-TO-CLASSPATH).
265% \end{itemize}
266
267\subsubsection{Calling Java class static methods}
268
269Like with non-static methods, references to static methods can be acquired
270by using the \code{JAVA:JMETHOD} primitive. In order to call this method,
271it's not possible to use the \code{JAVA:JCALL} primitive however: there's a
272separate API to retrieve a reference to static methods. This
273primitive is called \code{JAVA:JSTATIC}.
274
275Like \code{JAVA:JCALL}, \code{JAVA:JSTATIC} supports dynamic dispatch by
276passing the name of the method as a string instead of passing a method reference.
277The parameter values should be values to pass in the function call instead of
278a specification of classes for each parameter.
279
280\subsubsection{Parameter matching for FFI dynamic dispatch}
281
282The algorithm used to resolve the best matching method given the name
283and the arguments' types is the same as described in the Java Language
284Specification. Any deviation should be reported as a bug.
285
286% ###TODO reference to correct JLS section
287
288\subsubsection{Instantiating Java objects}
289
290Java objects can be instantiated (created) from Lisp by calling
291a constructor from the class of the object to be created. The same way
292\code{JAVA:JMETHOD} is used to acquire a method reference, the
293\code{JAVA:JCONSTRUCTOR} primitive can be used to acquire a constructor
294reference. It's arguments specify the types of arguments of the constructor
295method the same way as with \code{JAVA:JMETHOD}.
296
297The constructor can't be passed to \code{JAVA:JCALL}, but instead should
298be passed as an argument to \code{JAVA:JNEW}.
299
300\section{Lisp from Java}
301
302In order to access the Lisp world from Java, one needs to be aware
303of a few things. The most important ones are listed below.
304
305\begin{itemize}
306\item All Lisp values are descendants of LispObject.java
307\item In order to
308\item Lisp symbols are accessible via either directly referencing the
309  Symbol.java instance or by dynamically introspecting the
310  corresponding Package.java instance.
311\item The Lisp dynamic environment may be saved via
312  \code{LispThread.bindSpecial(Binding)} and restored via
313  \code{LispThread.resetSpecialBindings(Mark)}.
314\item Functions may be executed by invocation of the
315  Function.execute(args [...])
316\end{itemize}
317
318\subsection{Lisp FFI}
319
320FFI stands for "Foreign Function Interface" which is the phase which
321the contemporary Lisp world refers to methods of "calling out" from
322Lisp into "foreign" languages and environments.  This document
323describes the various ways that one interacts with Lisp world of ABCL
324from Java, considering the hosted Lisp as the "Foreign Function" that
325needs to be "Interfaced".
326
327\subsection{Calling Lisp from Java}
328
329Note: As the entire ABCL Lisp system resides in the org.armedbear.lisp
330package the following code snippets do not show the relevant import
331statements in the interest of brevity.  An example of the import
332statement would be
333
334\begin{listing-java}
335  import org.armedbear.lisp.*;
336\end{listing-java}
337
338to potentially import all the JVM symbol from the `org.armedbear.lisp'
339namespace.
340
341Per JVM, there can only ever be a single Lisp interpreter.  This is
342started by calling the static method `Interpreter.createInstance()`.
343
344\begin{listing-java}
345  Interpreter interpreter = Interpreter.createInstance();
346\end{listing-java}
347
348If this method has already been invoked in the lifetime of the current
349Java process it will return null, so if you are writing Java whose
350life-cycle is a bit out of your control (like in a Java servlet), a
351safer invocation pattern might be:
352
353\begin{listing-java}
354  Interpreter interpreter = Interpreter.getInstance();
355  if (interpreter == null) {
356    interpreter = Interpreter.createInstance();
357  }
358\end{listing-java}
359
360
361The Lisp \code{eval} primitive may be simply passed strings for evaluation,
362as follows
363
364\begin{listing-java}
365  String line = "(load \"file.lisp\")";
366  LispObject result = interpreter.eval(line);
367\end{listing-java}
368
369Notice that all possible return values from an arbitrary Lisp
370computation are collapsed into a single return value.  Doing useful
371further computation on the ``LispObject'' depends on knowing what the
372result of the computation might be, usually involves some amount
373of \code{instanceof} introspection, and forms a whole topic to itself
374(c.f. [Introspecting a LispObject])
375
376Using \code{eval} involves the Lisp interpreter.  Lisp functions may
377be directly invoked by Java method calls as follows.  One simply
378locates the package containing the symbol, then obtains a reference to
379the symbol, and then invokes the \code{execute()} method with the
380desired parameters.
381
382\begin{listing-java}
383    interpreter.eval("(defun foo (msg) (format nil \"You told me '~A'~%\" msg))");
384    Package pkg = Packages.findPackage("CL-USER");
385    Symbol foo = pkg.findAccessibleSymbol("FOO");
386    Function fooFunction = (Function)foo.getSymbolFunction();
387    JavaObject parameter = new JavaObject("Lisp is fun!");
388    LispObject result = fooFunction.execute(parameter);
389    // How to get the "naked string value"?
390    System.out.println("The result was " + result.writeToString());
391\end{listing-java}
392
393If one is calling an primitive function in the CL package the syntax
394becomes considerably simpler.  If we can locate the instance of
395definition in the ABCL Java source, we can invoke the symbol directly.
396For instance, to tell if a `LispObject` contains a reference to a symbol.
397
398\begin{listing-java}
399    boolean nullp(LispObject object) {
400      LispObject result = Primitives.NULL.execute(object);
401      if (result == NIL) { // the symbol 'NIL' is explicitly named in the Java
402                           // namespace at ``Symbol.NIL''
403                           // but is always present in the
404                           // local namespace in its unadorned form for
405                           // the convenience of the User.
406        return false;
407      }
408      return true;
409   }
410\end{listing-java}
411
412\subsubsection{Introspecting a LispObject}
413\label{topic:Introspecting a LispObject}
414
415We present various patterns for introspecting an an arbitrary
416`LispObject` which can represent the result of every Lisp evaluation
417into semantics that Java can meaningfully deal with.
418
419\subsubsection{LispObject as \code{boolean}}
420
421If the LispObject a generalized boolean values, one can use
422\code{getBooleanValue()} to convert to Java:
423
424\begin{listing-java}
425     LispObject object = Symbol.NIL;
426     boolean javaValue = object.getBooleanValue();
427\end{listing-java}
428
429Although since in Lisp, any value other than NIL means "true"
430(so-called generalized Boolean), the use of Java equality it quite a
431bit easier to type and more optimal in terms of information it conveys
432to the compiler would be:
433
434\begin{listing-java}
435    boolean javaValue = (object != Symbol.NIL);
436\end{listing-java}
437
438\paragraph{LispObject is a list}
439
440If LispObject is a list, it will have the type `Cons`.  One can then use
441the \code{copyToArray} to make things a bit more suitable for Java
442iteration.
443
444\begin{listing-java}
445    LispObject result = interpreter.eval("'(1 2 4 5)");
446    if (result instanceof Cons) {
447      LispObject array[] = ((Cons)result.copyToArray());
448      ...
449    }
450\end{listing-java}
451
452A more Lispy way to iterated down a list is to use the `cdr()` access
453function just as like one would traverse a list in Lisp:;
454
455\begin{listing-java}
456    LispObject result = interpreter.eval("'(1 2 4 5)");
457    while (result != Symbol.NIL) {
458      doSomething(result.car());
459      result = result.cdr();
460    }
461\end{listing-java}
462
463\subsection{Java Scripting API (JSR-223)}
464
465ABCL can be built with support for JSR-223, which offers a
466language-agnostic API to invoke other languages from Java. The binary
467distribution downloadable from ABCL's common-lisp.net home is built
468with JSR-223 support. If you're building ABCL from source on a pre-1.6
469JVM, you need to have a JSR-223 implementation in your CLASSPATH (such
470as Apache Commons BSF 3.x or greater) in order to build ABCL with
471JSR-223 support; otherwise, this feature will not be built.
472
473This section describes the design decisions behind the ABCL JSR-223
474support. It is not a description of what JSR-223 is or a tutorial on
475how to use it. See
476http://trac.common-lisp.net/armedbear/browser/trunk/abcl/examples/jsr-223
477for example usage.
478
479\subsubsection{Conversions}
480
481In general, ABCL's implementation of the JSR-223 API performs implicit
482conversion from Java objects to Lisp objects when invoking Lisp from
483Java, and the opposite when returning values from Java to Lisp. This
484potentially reduces coupling between user code and ABCL. To avoid such
485conversions, wrap the relevant objects in \code{JavaObject} instances.
486
487\subsubsection{Implemented JSR-223 interfaces}
488
489JSR-223 defines three main interfaces, of which two (Invocable and
490Compilable) are optional. ABCL implements all the three interfaces -
491ScriptEngine and the two optional ones - almost completely. While the
492JSR-223 API is not specific to a single scripting language, it was
493designed with languages with a more or less Java-like object model in
494mind: languages such as Javascript, Python, Ruby, which have a concept
495of "class" or "object" with "fields" and "methods". Lisp is a bit
496different, so certain adaptations were made, and in one case a method
497has been left unimplemented since it does not map at all to Lisp.
498
499\subsubsection{The ScriptEngine}
500
501The main interface defined by JSR-223, javax.script.ScriptEngine, is
502implemented by the class
503\code{org.armedbear.lisp.scripting.AbclScriptEngine}. AbclScriptEngine
504is a singleton, reflecting the fact that ABCL is a singleton as
505well. You can obtain an instance of AbclScriptEngine using the
506AbclScriptEngineFactory or by using the service provider mechanism
507through ScriptEngineManager (refer to the javax.script documentation).
508
509\subsubsection{Startup and configuration file}
510
511At startup (i.e. when its constructor is invoked, as part of the
512static initialization phase of AbclScriptEngineFactory) the ABCL
513script engine attempts to load an "init file" from the classpath
514(/abcl-script-config.lisp). If present, this file can be used to
515customize the behaviour of the engine, by setting a number of
516variables in the ABCL-SCRIPT package. Here is a list of the available
517variables:
518
519\begin{itemize}
520\item *use-throwing-debugger* Controls whether ABCL uses a
521  non-standard debugging hook function to throw a Java exception
522  instead of dropping into the debugger in case of unhandled error
523  conditions.
524  \begin{itemize}
525  \item Default value: T
526  \item Rationale: it is more convenient for Java programmers using
527    Lisp as a scripting language to have it return exceptions to Java
528    instead of handling them in the Lisp world.
529  \item Known Issues: the non-standard debugger hook has been reported
530    to misbehave in certain circumstances, so consider disabling it if
531    it doesn't work for you.
532  \end{itemize}
533\item *launch-swank-at-startup* If true, Swank will be launched at
534  startup. See *swank-dir* and *swank-port*.
535  \begin{itemize}
536  \item Default value: NIL
537  \end{itemize}
538\item *swank-dir* The directory where Swank is installed. Must be set
539  if *launch-swank-at-startup* is true.
540\item *swank-port* The port where Swank will listen for
541  connections. Must be set if *launch-swank-at-startup* is true.
542  \begin{itemize}
543  \item Default value: 4005
544  \end{itemize}
545\end{itemize}
546
547Additionally, at startup the AbclScriptEngine will \code{(require
548  'asdf)} - in fact, it uses asdf to load Swank.
549
550\subsubsection{Evaluation}
551
552Code is read and evaluated in the package ABCL-SCRIPT-USER. This
553packages USEs the COMMON-LISP, JAVA and ABCL-SCRIPT packages. Future
554versions of the script engine might make this default package
555configurable. The \code{CL:LOAD} function is used under the hood for
556evaluating code, and thus the same behavior of LOAD is
557guaranteed. This allows, among other things, \code{IN-PACKAGE} forms
558to change the package in which the loaded code is read.
559
560It is possible to evaluate code in what JSR-223 calls a
561"ScriptContext" (basically a flat environment of name->value
562pairs). This context is used to establish special bindings for all the
563variables defined in it; since variable names are strings from Java's
564point of view, they are first interned using READ-FROM-STRING with, as
565usual, ABCL-SCRIPT-USER as the default package. Variables are declared
566special because CL's \code{LOAD}, \code{EVAL} and \code{COMPILE}
567functions work in a null lexical environment and would ignore
568non-special bindings.
569
570Contrary to what the function \code{LOAD} does, evaluation of a series
571of forms returns the value of the last form instead of T, so the
572evaluation of short scripts does the Right Thing.
573
574\subsubsection{Compilation}
575
576AbclScriptEngine implements the javax.script.Compilable
577interface. Currently it only supports compilation using temporary
578files. Compiled code, returned as an instance of
579javax.script.CompiledScript, is read, compiled and executed by default
580in the ABCL-SCRIPT-USER package, just like evaluated code. Differently
581from evaluated code, though, due to the way the ABCL compiler works,
582compiled code contains no reference to top-level self-evaluating
583objects (like numbers or strings). Thus, when evaluated, a piece of
584compiled code will return the value of the last non-self-evaluating
585form: for example the code "(do-something) 42" will return 42 when
586interpreted, but will return the result of (do-something) when
587compiled and later evaluated. To ensure consistency of behavior
588between interpreted and compiled code, make sure the last form is
589always a compound form - at least (identity some-literal-object). Note
590that this issue should not matter in real code, where it is unlikely a
591top-level self-evaluating form will appear as the last form in a file
592(in fact, the Common Lisp load function always returns T upon success;
593with JSR-223 this policy has been changed to make evaluation of small
594code snippets work as intended).
595
596\subsubsection{Invocation of functions and methods}
597
598AbclScriptEngine implements the \code{javax.script.Invocable}
599interface, which allows to directly call Lisp functions and methods,
600and to obtain Lisp implementations of Java interfaces. This is only
601partially possible with Lisp since it has functions, but not methods -
602not in the traditional OO sense, at least, since Lisp methods are not
603attached to objects but belong to generic functions. Thus, the method
604\code{invokeMethod()} is not implemented and throws an
605UnsupportedOperationException when called. The \code{invokeFunction()}
606method should be used to call both regular and generic functions.
607
608\subsubsection{Implementation of Java interfaces in Lisp}
609
610ABCL can use the Java reflection-based proxy feature to implement Java
611interfaces in Lisp. It has several built-in ways to implement an
612interface, and supports definition of new ones. The
613\code{JAVA:JMAKE-PROXY} generic function is used to make such
614proxies. It has the following signature:
615
616\code{jmake-proxy interface implementation \&optional lisp-this ==> proxy}
617
618\code{interface} is a Java interface metaobject (e.g. obtained by
619invoking \code{jclass}) or a string naming a Java
620interface. \code{implementation} is the object used to implement the
621interface - several built-in methods of jmake-proxy exist for various
622types of implementations. \code{lisp-this} is an object passed to the
623closures implementing the Lisp "methods" of the interface, and
624defaults to \code{NIL}.
625
626The returned proxy is an instance of the interface, with methods
627implemented with Lisp functions.
628
629Built-in interface-implementation types include:
630
631\begin{itemize}
632\item a single Lisp function which upon invocation of any method in
633  the interface will be passed the method name, the Lisp-this object,
634  and all the parameters. Useful for interfaces with a single method,
635  or to implement custom interface-implementation strategies.
636\item a hash-map of method-name -> Lisp function mappings. Function
637  signature is \code{(lisp-this \&rest args)}.
638\item a Lisp package. The name of the Java method to invoke is first
639  transformed in an idiomatic Lisp name (\code{javaMethodName} becomes
640  \code{JAVA-METHOD-NAME}) and a symbol with that name is searched in
641  the package. If it exists and is fbound, the corresponding function
642  will be called. Function signature is as the hash-table case.
643\end{itemize}
644
645This functionality is exposed by the AbclScriptEngine with the two
646methods getInterface(Class) and getInterface(Object, Class). The
647former returns an interface implemented with the current Lisp package,
648the latter allows the programmer to pass an interface-implementation
649object which will in turn be passed to the jmake-proxy generic
650function.
651
652\chapter{Implementation Dependent Extensions}
653
654As outlined by the CLHS ANSI conformance guidelines, we document the
655extensions to the Armed Bear Lisp implementation made accessible to
656the user by virtue of being an exported symbol in the JAVA, THREADS,
657or EXTENSIONS packages.
658
659\section{JAVA}
660
661\subsection{Modifying the JVM CLASSPATH}
662
663The JAVA:ADD-TO-CLASSPATH generic functions allows one to add the
664specified pathname or list of pathnames to the current classpath
665used by ABCL, allowing the dynamic loading of JVM objects:
666
667\begin{listing-lisp}
668CL-USER> (add-to-classpath "/path/to/some.jar")
669\end{listing-lisp}
670
671NB \code{add-to-classpath} only affects the classloader used by ABCL
672(the value of the special variable \code{JAVA:*CLASSLOADER*}. It has
673no effect on Java code outside ABCL.
674
675\subsection{API}
676
677% include autogen docs for the JAVA package.
678\include{java}
679
680\section{THREADS}
681
682Multithreading
683
684\subsection{API}
685
686% include autogen docs for the THREADS package.
687\include{threads}
688
689\section{EXTENSIONS}
690
691The symbols in the EXTENSIONS package (nicknamed ``EXT'') constitutes
692extensions to the ANSI standard that are potentially useful to the
693user.  They include functions for manipulating network sockets,
694running external programs, registering object finalizers, constructing
695reference weakly held by the garbage collector and others.
696
697See \ref{Extensible Sequences} for a generic function interface to
698the native JVM contract for \code{java.util.List}.
699
700\subsection{API}
701
702% include autogen docs for the EXTENSIONS package.
703\include{extensions}
704
705\chapter{Beyond ANSI}
706
707Naturally, in striving to be a useful contemporary Common Lisp
708implementation, ABCL endeavors to include extensions beyond the ANSI
709specification which are either widely adopted or are especially useful
710in working with the hosting JVM.
711
712\section{Implementation Dependent}
713\begin{enumerate}
714  \item Compiler to JVM 5 bytecode
715  \item Pathname extensions
716\end{enumerate}
717
718\section{Pathname}
719
720We implment an extension to the Pathname that allows for the
721description and retrieval of resources named in a URI scheme that the
722JVM ``understands''.  Support is built-in to the ``http'' and
723``https'' implementations but additional protocol handlers may be
724installed at runtime by having JVM symbols present in the
725sun.net.protocol.dynmamic pacakge. See [JAVA2006] for more details.
726
727ABCL has created specializations of the ANSI Pathname object to
728enable to use of URIs to address dynamically loaded resources for the
729JVM.  A URL-PATHNAME has a corresponding URL whose cannoical
730representation is defined to be the NAMESTRING of the Pathname.
731
732PATHNAME : URL-PATHNAME : JAR-PATHNAME
733
734Both URL-PATHNAME and JAR-PATHNAME may be used anu where will a
735PATHNAME is accepted witht the following caveats
736
737A stream obtained via OPEN on a URL-PATHNAME cannot be the target of
738write operations.
739
740No canonicalization is performed on the underlying URI (i.e. the
741implementation does not attempt to compute the current name of the
742representing resource unless it is requested to be resolved.)  Upon
743resolution, any cannoicalization procedures followed in resolving the
744resource (e.g. following redirects) are discarded. 
745
746The implementation of URL-PATHNAME allows the ABCL user to laod dynamically
747code from the network.  For example, for Quicklisp.
748
749\begin{listing-lisp}
750  CL-USER> (load "http://beta.quicklisp.org/quicklisp.lisp")
751\end{listing-lisp}
752
753will load and execute the Quicklisp setup code.
754
755\ref{XACH2011}
756         
757\section{Extensible Sequences}
758
759See \ref{RHODES2007} RHODES2007 for the design.
760
761The SEQUENCE package fully implements Christopher Rhodes' proposal for
762extensible sequences.  These user extensible sequences are used
763directly in \code{java-collections.lisp} provide these CLOS
764abstractions on the standard Java collection classes as defined by the
765\code{java.util.List} contract.
766
767This extension is not automatically loaded by the implementation.   It
768may be loaded via:
769
770\begin{listing-lisp}
771CL-USER> (require 'java-collections)
772\end{listing-lisp}
773
774if both extensible sequences and their application to Java collections
775is required, or
776
777\begin{listing-lisp}
778CL-USER> (require 'extensible-sequences)
779\end{listing-lisp}
780
781if only the extensible sequences API as specified in \ref{RHODES2007} is
782required.
783
784Note that \code{(require 'java-collections)} must be issued before
785\code{java.util.List} or any subclass is used as a specializer in a CLOS
786method definition (see the section below).
787
788\section{Extensions to CLOS}
789
790There is an additional syntax for specializing the parameter of a
791generic function on a java class, viz. \code{(java:jclass CLASS-STRING)}
792where \code{CLASS-STRING} is a string naming a Java class in dotted package
793form.
794
795For instance the following specialization would perhaps allow one to
796print more information about the contents of a java.util.Collection
797object
798
799\begin{listing-lisp}
800(defmethod print-object ((coll (java:jclass "java.util.Collection"))
801                         stream)
802  ;;; ...
803)
804\end{listing-lisp}
805
806If the class had been loaded via a classloader other than the original
807the class you wish to specialize on, one needs to specify the
808classloader as an optional third argument.
809
810\begin{listing-lisp}
811
812(defparameter *other-classloader*
813  (jcall "getBaseLoader" cl-user::*classpath-manager*))
814 
815(defmethod print-object ((device-id (java:jclass "dto.nbi.service.hdm.alcatel.com.NBIDeviceID" *other-classloader*))
816                         stream)
817  ;;; ...
818)
819\end{listing-lisp}
820
821\section{Extensions to the Reader}
822
823We implement a special hexadecimal escape sequence for specifying
824characters to the Lisp reader, namely we allow a sequences of the form
825\# \textbackslash Uxxxx to be processed by the reader as character whose code is
826specified by the hexadecimal digits ``xxxx''.  The hexadecimal sequence
827must be exactly four digits long, padded by leading zeros for values
828less than 0x1000.
829
830Note that this sequence is never output by the implementation.  Instead,
831the corresponding Unicode character is output for characters whose
832code is greater than 0x00ff.
833
834\subsection{JSS optionally extends the Reader}
835
836The JSS contrib consitutes an additional, optional extension to the
837reader in the definition of the \#\" reader macro.
838
839\section{ASDF}
840
841asdf-2.017 is packaged as core component of ABCL, but not intialized
842by default, as it relies on the CLOS subsystem which can take a bit of
843time to initialize.  It may be initialized by the ANSI
844\textsc{REQUIRE} mechanism as follows:
845
846\begin{listing-lisp}
847CL-USER> (require 'asdf)
848\end{listing-lisp}
849
850\chapter{Contrib}
851
852\section{abcl-asdf}
853
854This contrib to ABCL enables an additional syntax for ASDF system
855definition which dynamically loads JVM artifacts such as jar archives
856via a Maven encapsulation.
857
858The following ASDF components are added:  JAR-FILE, JAR-DIRECTORY, CLASS-FILE-DIRECTORY
859and MVN.
860
861\section{asdf-jar}
862
863ASDF-JAR provides a system for packaging ASDF systems into jar
864archives for ABCL.  Given a running ABCL image with loadable ASDF
865systems the code in this package will recursively package all the
866required source and fasls in a jar archive.
867
868\section{abcl-asdf}
869
870ABCL specific contributions to ASDF system definition mainly concerned
871with finding JVM artifacts such as jar archives to be dynamically loaded.
872
873\subsection{ABCL-ASDF Examples}
874
875\begin{listing-lisp}
876    ;;;; -*- Mode: LISP -*-
877    (in-package :asdf)
878
879    (defsystem :log4j
880      :components ((:mvn "log4j/log4j"
881                    :version "1.4.9")))
882\end{listing-lisp}
883
884\subsection{abcl-asdf API}
885
886We define an API as consisting of the following ASDF classes:
887
888\textsc{JAR-DIRECTORY}, \textsc{JAR-FILE}, and
889\textsc{CLASS-FILE-DIRECTORY} for JVM artifacts that have a currently
890valid pathname representation
891
892And the MVN and IRI classes descend from ASDF-COMPONENT, but do not
893directly have a filesystem location.
894
895For use outside of ASDF, we currently define one method,
896\textsc{RESOLVE-DEPENDENCIES} which locates, downloads, caches, and then loads
897into the currently executing JVM process all recursive dependencies
898annotated in the Maven pom.xml graph.
899
900\subsection{ABCL-ASDF Example 2}
901
902Bypassing ASDF, one can directly issue requests for the Maven
903artifacts to be downloaded
904
905\begin{listing-lisp}
906    CL-USER> (abcl-asdf:resolve-dependencies "com.google.gwt" "gwt-user")
907    WARNING: Using LATEST for unspecified version.
908    "/Users/evenson/.m2/repository/com/google/gwt/gwt-user/2.4.0-rc1/gwt-user-2.4.0-rc1.jar:/Users/evenson/.m2/repository/javax/validation/validation-api/1.0.0.GA/validation-api-1.0.0.GA.jar:/Users/evenson/.m2/repository/javax/validation/validation-api/1.0.0.GA/validation-api-1.0.0.GA-sources.jar"
909\end{listing-lisp}
910
911To actually load the dependency, use the JAVA:ADD-TO-CLASSPATH generic
912function:
913
914\begin{listing-lisp}
915    CL-USER> (java:add-to-classpath (abcl-asdf:resolve-dependencies "com.google.gwt" "gwt-user"))
916\end{listing-lisp}
917
918Notice that all recursive dependencies have been located and installed
919locally from the network as well.
920
921\section{jss}
922
923To one used to a syntax that can construct macros, the Java syntax
924sucks, so we introduce the \#" macro.
925
926\subsection{JSS usage}
927
928Example:
929
930\begin{listing-lisp}
931  CL-USER> (require 'jss)
932
933  CL-USER) (#"getProperties" 'java.lang.System)
934
935  CL-USER) (#"propertyNames" (#"getProperties" 'java.lang.System))
936\end{listing-lisp}
937
938\section{asdf-install}
939
940An implementation of ASDF-INSTALL.  Superseded by Quicklisp (qv.)
941
942\chapter{History}
943
944ABCL was originally the extension language for the J editor, which was
945started in 1998 by Peter Graves.  Sometime in 2003, it seems that a
946lot of code that had previously not been released publically was
947suddenly committed that enabled ABCL to be plausibly termed an ANSI
948Common Lisp implementation.
949
950In 2006, the implementation was transferred to the current
951maintainers, who have strived to improve its usability as a
952contemporary Common Lisp implementation.
953
954In 201x, with the publication of this Manual explicitly stating the
955conformance of Armed Bear Common Lisp to ANSI, we release abcl-1.0.
956
957
958
959
960\section{References}
961
962[Java2000]:  A New Era for Java Protocol Handlers.
963\url{http://java.sun.com/developer/onlineTraining/protocolhandlers/}
964
965[Xach2011]:  Quicklisp:  A system for quickly constructing Common Lisp
966libraries.  \url{http://www.quicklisp.org/}
967
968
969\end{document}
970
971% TODO
972%   1.  Create mechanism for swigging DocString and Lisp docs into
973%       sections.
974
Note: See TracBrowser for help on using the repository browser.