# source:trunk/abcl/doc/manual/abcl.tex@13815

Last change on this file since 13815 was 13815, checked in by rschlatte, 11 years ago

Minor manual prettification.

File size: 43.9 KB
Line
1% -*- mode: latex; -*-
2% http://en.wikibooks.org/wiki/LaTeX/
3\documentclass[10pt]{book}
4\usepackage{abcl}
5
6\begin{document}
7\title{A Manual for Armed Bear Common Lisp}
8\date{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
27
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
58abcl.jar'' or possiblyabcl-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
93--nosystem
95--eval <FORM>
96    Evaluates the <FORM> before initializing REPL.
98    Loads the file <FILE> before initializing REPL.
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 Section~\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 512LispObject 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 816https'' 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" :version "1.4.9"))) 1012\end{listing-lisp} 1013 1014\subsection{API} 1015 1016We define an API for \textsc{ABCL-ASDF} as consisting of the following 1017ASDF classes: 1018 1019\code{JAR-DIRECTORY}, \code{JAR-FILE}, and 1020\code{CLASS-FILE-DIRECTORY} for JVM artifacts that have a currently 1021valid pathname representation. 1022 1023Both the MVN and IRI classes descend from ASDF-COMPONENT, but do not 1024directly have a filesystem location. 1025 1026For use outside of ASDF system definitions, we currently define one 1027method, \code{ABCL-ASDF:RESOLVE-DEPENDENCIES} which locates, 1028downloads, caches, and then loads into the currently executing JVM 1029process all recursive dependencies annotated in the Maven pom.xml 1030graph. 1031 1032\subsection{Directly Instructing Maven to Download JVM Artifacts} 1033 1034Bypassing \textsc{ASDF}, one can directly issue requests for the Maven 1035artifacts to be downloaded 1036 1037\begin{listing-lisp} 1038CL-USER> (abcl-asdf:resolve-dependencies "com.google.gwt" 1039 "gwt-user") 1040WARNING: Using LATEST for unspecified version. 1041"/Users/evenson/.m2/repository/com/google/gwt/gwt-user/2.4.0-rc1 1042/gwt-user-2.4.0-rc1.jar:/Users/evenson/.m2/repository/javax/vali 1043dation/validation-api/1.0.0.GA/validation-api-1.0.0.GA.jar:/User 1044s/evenson/.m2/repository/javax/validation/validation-api/1.0.0.G 1045A/validation-api-1.0.0.GA-sources.jar" 1046\end{listing-lisp} 1047 1048To actually load the dependency, use the \code{JAVA:ADD-TO-CLASSPATH} generic 1049function: 1050 1051\begin{listing-lisp} 1052CL-USER> (java:add-to-classpath 1053 (abcl-asdf:resolve-dependencies "com.google.gwt" 1054 "gwt-user")) 1055\end{listing-lisp} 1056 1057Notice that all recursive dependencies have been located and installed 1058locally from the network as well. 1059 1060\section{asdf-jar} 1061 1062The asdf-jar contrib provides a system for packaging ASDF systems into 1063jar archives for ABCL. Given a running ABCL image with loadable ASDF 1064systems the code in this package will recursively package all the 1065required source and fasls in a jar archive. 1066 1067The documentation for this contrib can be found at 1068\url{http://svn.common-lisp.net/armedbear/trunk/abcl/contrib/asdf-jar/README.markdown}. 1069 1070 1071\section{jss} 1072\label{section:jss} 1073 1074To one used to the more universal syntax of Lisp pairs for which the 1075definition of read and compile time macros is quite natural, the Java 1076syntax available to the Java programmer may be said to suck. To 1077alleviate this situation, we introduce the 1078\code{SHARPSIGN-DOUBLE-QUOTE} (\code{\#"}) reader macro, the first of perhaps 1079 many exper 1080 1081\subsection{JSS usage} 1082 1083Example: 1084 1085\begin{listing-lisp} 1086CL-USER> (require 'abcl-contrib) 1087==> ("ABCL-CONTRIB") 1088CL-USER> (require 'jss) 1089==> ("JSS") 1090CL-USER) (#"getProperties" 'java.lang.System) 1091==> #<java.util.Properties {java.runtime.name=Java.... {2FA21ACF}> 1092CL-USER) (#"propertyNames" (#"getProperties" 'java.lang.System)) 1093==> #<java.util.Hashtable$Enumerator java.util.Has.... {36B4361A}>
1094\end{listing-lisp} %\$ <-- un-confuse Emacs font-lock
1095
1096Some more information on jss can be found in its documentation at
1098
1099\section{asdf-install}
1100
1101The asdf-install contrib provides an implementation of ASDF-INSTALL.
1102Superseded by Quicklisp (see Xach2011 \cite{quicklisp}).
1103
1104The \code{require} of the \code{asdf-install} symbol has the side
1105effect of pushing the directory `~/.asdf-install-dir/systems/'' into
1106the value of the \textsc{ASDF} central registry in
1107\code{asdf:*central-registry*}, providing a convenient mechanism for
1108stashing \textsc{ABCL} specific system definitions for convenient
1109access.
1110
1111\chapter{History}
1112
1113\textsc{ABCL} was originally the extension language for the J editor, which was
1114started in 1998 by Peter Graves.  Sometime in 2003, a whole lot of
1115code that had previously not been released publically was suddenly
1116committed that enabled ABCL to be plausibly termed an emergent ANSI
1117Common Lisp implementation canidate.
1118
1119From 2006 to 2008, Peter manned the development lists, incorporating
1120patches as made sense.  After a suitable search, Peter nominated Erik
1121H\"{u}lsmann to take over the project.
1122
1123In 2008, the implementation was transferred to the current
1124maintainers, who have strived to improve its usability as a
1125contemporary Common Lisp implementation.
1126
1127On October 22, 2011, with the publication of this Manual explicitly
1128stating the conformance of Armed Bear Common Lisp to \textsc{ANSI}, we
1129released abcl-1.0.0.  We released abcl-1.0.1 as a maintainence release
1130on January 10, 2012.
1131
1132\bibliography{abcl}
1133\bibliographystyle{alpha}
1134
1135\printindex
1136
1137\end{document}
1138
1139% TODO
1140%   1.  Create mechanism for swigging DocString and Lisp docs into
1141%       sections ('grovel.lisp')
1142
Note: See TracBrowser for help on using the repository browser.