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

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

Backport changes to manual en masse.

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