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

Last change on this file since 13801 was 13801, checked in by rschlatte, 10 years ago

Make manual compile again. Also BibTeX-ify bibliography.

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