% -*- mode: latex; -*-
% http://en.wikibooks.org/wiki/LaTeX/
\documentclass[10pt]{book}
\usepackage{abcl}

\begin{document}
\title{A Manual for Armed Bear Common Lisp}
\date{August 4, 2011}
\author{Mark~Evenson, Erik~Huelsmann, Alessio~Stallo, Ville~Voutilainen}

\maketitle

\chapter{Introduction}

Armed Bear is a mostly conforming implementation of the ANSI Common
Lisp standard.  This manual documents the Armed Bear Common Lisp
implementation for users of the system.

\subsection{Version}
This manual corresponds to abcl-0.27.0, as yet unreleased.


\chapter{Running}

ABCL is packaged as a single jar file (usually named either
``abcl.jar'' or something like``abcl-0.27.1.jar'' if you are using a
versioned package) that can be executed under the
control of a suitable JVM as follows

\begin{listing-shell}
  cmd\$ java -jar abcl.jar
\end{listing-shell}

For this command to work, the ``java'' exectuable needs to be in your
path.

To make it easier to faciliate the use of ABCL in tool chains (such as
SLIME) the invocation is wrapped in a Bourne shell script under UNIX
or a DOS command script under Windows so that ABCL may be executed
simplly as:

\begin{listing-shell}
  cmd\$ abcl
\end{listing-shell}

\section{Options}

ABCL supports the following options:

\begin{verbatim}
--help
    Displays this message.
--noinform
    Suppresses the printing of startup information and banner.
--noinit
    Suppresses the loading of the '~/.abclrc' startup file.
--nosystem
    Suppresses loading the 'system.lisp' customization file. 
--eval <FORM>
    Evaluates the <FORM> before initializing REPL.
--load <FILE>
    Loads the file <FILE> before initializing REPL.
--load-system-file <FILE>
    Loads the system file <FILE> before initializing REPL.
--batch
    The process evaluates forms specified by arguments and possibly by those
    by those in the intialization file '~/.abcl', and then exits.

The occurance of '--' copies the remaining arguments, unprocessed, into
the variable EXTENSIONS:*COMMAND-LINE-ARGUMENT-LIST*.
\end{verbatim}

All of the command line arguments which follow the occurance of ``--''
are passed into a list bound to the EXT:*COMMAND-LINE-ARGUMENT-LIST*
variable.

\section{Initialization}

If the ABCL process is started without the ``--noinit'' flag, it
attempts to load a file named ``.abclrc'' located in the user's home
directory and then interpret its contents.  

The user's home directory is determined by the value of the JVM system
property ``user.home''.

\chapter{Conformance}

\section{ANSI Common Lisp}
ABCL is currently a non-conforming ANSI Common Lisp implementation due
to the following (known) issues:

\begin{itemize}
  \item Lack of long form of DEFINE-METHOD-COMBINATION
  \item Missing statement of conformance in accompanying documentation
\end{itemize}

ABCL aims to be be a fully conforming ANSI Common Lisp
implementation.  Any other behavior should be reported as a bug.

\section{Contemporary Common Lisp}
In addition to ANSI conformance, ABCL strives to implement features
expected of a contemporary Common Lisp.
\begin{itemize}
  \item Incomplete MOP 
    % N.B. 
    % TODO go through AMOP with symbols, starting by looking for
    % matching function signature.
    % XXX is this really blocking ANSI conformance?  Answer: we have
    % to start with such a ``census'' to determine what we have.
  \item Incomplete Gray Streams
\end{itemize}

\chapter{Interaction with host JVM}

% describe calling Java from Lisp, and calling Lisp from Java,
% probably in two separate sections.  Presumably, we can partition our
% audience into those who are more comfortable with Java, and those
% that are more comforable with Lisp

\section{Lisp to Java}

ABCL offers a number of mechanisms to manipulate Java libraries from
Lisp.

\begin{itemize}
\item Java values are accessible as objects of type JAVA:JAVA-OBJECT.
\item The Java FFI presents a Lisp package (JAVA) with many useful
  symbols for manipulating the artifacts of expectation on the JVM,
  including creation of new objects \ref{JAVA:JNEW}, \ref{JAVA:JMETHOD}), the
  introspection of values \ref{JAVA:JFIELD}, the execution of methods
  (\ref{JAVA:JCALL}, \ref{JAVA:JCALL-RAW}, \ref{JAVA:JSTATIC})
\item The JSS package (\ref{JSS}) in contrib introduces a convenient macro
  syntax \ref{JSS:SHARPSIGN_DOUBLEQUOTE_MACRO} for accessing Java
  methods, and additional convenience functions.
\item Java classes and libraries may be dynamically added to the
  classpath at runtime (JAVA:ADD-TO-CLASSPATH).
\end{itemize}

\section{Lisp from Java}

Manipulation of the Lisp API is currently lacking a stable interface,
so what is documented here is subject to change.  

\begin{itemize}
\item All Lisp values are descendants of LispObject.java
\item Lisp symbols are accessible via either directly referencing the
  Symbol.java instance or by dynamically introspecting the
  corresponding Package.java instance.
\item The Lisp dynamic environment may be saved via
  \code{LispThread.bindSpecial(Binding)} and restored via
  \code{LispThread.resetSpecialBindings(Mark)}.
\item Functions may be executed by invocation of the
  Function.execute(args [...]) 
\end{itemize}

\subsection{Lisp FFI}

FFI stands for "Foreign Function Interface" which is the phase which
the contemporary Lisp world refers to methods of "calling out" from
Lisp into "foreign" languages and environments.  This document
describes the various ways that one interacts with Lisp world of ABCL
from Java, considering the hosted Lisp as the "Foreign Function" that
needs to be "Interfaced".

\subsection{Calling Lisp from Java}

Note: As the entire ABCL Lisp system resides in the org.armedbear.lisp
package the following code snippets do not show the relevant import
statements in the interest of brevity.  An example of the import
statement would be

\begin{listing-java}
  import org.armedbear.lisp.*;
\end{listing-java}

to potentially import all the JVM symbol from the `org.armedbear.lisp'
namespace.

Per JVM, there can only ever be a single Lisp interpreter.  This is
started by calling the static method `Interpreter.createInstance()`.

\begin{listing-java}
  Interpreter interpreter = Interpreter.createInstance();
\end{listing-java}

If this method has already been invoked in the lifetime of the current
Java process it will return null, so if you are writing Java whose
life-cycle is a bit out of your control (like in a Java servlet), a
safer invocation pattern might be:

\begin{code}[java]
  Interpreter interpreter = Interpreter.getInstance();
  if (interpreter == null) {
    interpreter = Interpreter.createInstance();
  }
\end{code}

The Lisp \code{eval} primitive may be simply passed strings for evaluation,
as follows

\begin{listing-java}
  String line = "(load \"file.lisp\")";
  LispObject result = interpreter.eval(line);
\end{listing-java}

Notice that all possible return values from an arbitrary Lisp
computation are collapsed into a single return value.  Doing useful
further computation on the ``LispObject'' depends on knowing what the
result of the computation might be, usually involves some amount
of \code{instanceof} introspection, and forms a whole topic to itself
(c.f. [Introspecting a LispObject])

Using \code{eval} involves the Lisp interpreter.  Lisp functions may
be directly invoked by Java method calls as follows.  One simply
locates the package containing the symbol, then obtains a reference to
the symbol, and then invokes the \code{execute()} method with the
desired parameters.

\begin{listing-java}
    interpreter.eval("(defun foo (msg) (format nil \"You told me '~A'~%\" msg))");
    Package pkg = Packages.findPackage("CL-USER");
    Symbol foo = pkg.findAccessibleSymbol("FOO"); 
    Function fooFunction = (Function)foo.getSymbolFunction();
    JavaObject parameter = new JavaObject("Lisp is fun!");
    LispObject result = fooFunction.execute(parameter);
    // How to get the "naked string value"?
    System.out.println("The result was " + result.writeToString()); 
\end{listing-java}

If one is calling an primitive function in the CL package the syntax
becomes considerably simpler if we can locate the instance of
definition in the ABCL source, we can invoke the symbol directly.  To
tell if a `LispObject` contains a reference to a symbol.

\begin{listing-java}
    boolean nullp(LispObject object) {
      LispObject result = Primitives.NULL.execute(object);
      if (result == NIL) {
        return false;
      }
      return true;
   }
\end{listing-java}

\subsubsection{Introspecting a LispObject}
\label{topic:Introspecting a LispObject}

We present various patterns for introspecting an an arbitrary
`LispObject` which can represent the result of every Lisp evaluation
into semantics that Java can meaniningfully deal with.

\subsubsection{LispObject as \code{boolean}}

If the LispObject a generalized boolean values, one can use
\code{getBooleanValue()} to convert to Java:

\begin{listing-java}
     LispObject object = Symbol.NIL;
     boolean javaValue = object.getBooleanValue();
\end{listing-java}

Although since in Lisp, any value other than NIL means "true", the
use of Java equality it quite a bit easier and more optimal:

\begin{listing-java}
    boolean javaValue = (object != Symbol.NIL);
\end{listing-java}

\paragraph{LispObject is a list}

If LispObject is a list, it will have the type `Cons`.  One can then use
the \code{copyToArray} to make things a bit more suitable for Java
iteration.

\begin{listing-java}
    LispObject result = interpreter.eval("'(1 2 4 5)");
    if (result instanceof Cons) {
      LispObject array[] = ((Cons)result.copyToArray());
      ...
    }
\end{listing-java}
    
A more Lispy way to iterated down a list is to use the `cdr()` access
function just as like one would traverse a list in Lisp:;

\begin{listing-java}
    LispObject result = interpreter.eval("'(1 2 4 5)");
    while (result != Symbol.NIL) {
      doSomething(result.car());
      result = result.cdr();
    }
\end{listing-java}


\section{Java}

% include autogen docs for the JAVA package.
\include{java}

\section{Multithreading}

% TODO document the THREADS package.
\include{threads}

\section{Extensions}

The symbols in the EXTENSIONS package consititutes extensions to the
ANSI standard that are potentially useful to the user.  They include
functions for manipulating network sockets, running external programs,
registering object finalizers, constructing reference weakly held by
the garbage collector and others.

\include{extensions}

\chapter{Beyond ANSI}

Naturally, in striving to be a useful contemporary Common Lisp
implementation, ABCL endeavors to include extensions beyond the ANSI
specification which are either widely adopted or are especially useful
in working with the hosting JVM.

\section{Extensions to CLOS}

There is an additional syntax for specializing the parameter of a
generic function on a java class, viz. \code{(java:jclass CLASS-STRING)}
where \code{CLASS-STRING} is a string naming a Java class in dotted package
form.

For instance the following specialization would perhaps allow one to
print more information about the contents of a java.util.Collection
object

\begin{listing-lisp}
(defmethod print-object ((coll (java:jclass "java.util.Collection"))
                         stream)
  ;;; ...
)
\end{listing-lisp}

If the class had been loaded via a classloader other than the original
the class you wish to specialize on, one needs to specify the
classloader as an optional third argument.

\begin{listing-lisp}

(defparameter *other-classloader*
  (jcall "getBaseLoader" cl-user::*classpath-manager*))
  
(defmethod print-object ((device-id (java:jclass "dto.nbi.service.hdm.alcatel.com.NBIDeviceID" *other-classloader*))
                         stream)
  ;;; ...
)
\end{listing-lisp}

\section{Extensions to the Reader}

We implement a special hexadecimal escape sequence for specifying
characters to the Lisp reader, namely we allow a sequences of the form
\# \textbackslash Uxxxx to be processed by the reader as character whose code is
specified by the hexadecimal digits ``xxxx''.  The hexadecimal sequence
must be exactly four digits long, padded by leading zeros for values
less than 0x1000.

Note that this sequence is never output by the implementation.  Instead,
the corresponding Unicode character is output for characters whose
code is greater than 0x00ff.

\chapter{History}

ABCL was originally the extension language for the J editor, which was
started in 1998 by Peter Graves.  Sometime in 2003, it seems that a
lot of code that had previously not been released publically was
suddenly committed that enabled ABCL to be plausibly termed an ANSI
Common Lisp implementation.  

In 2006, the implementation was transferred to the current
maintainers, who have strived to improve its usability as a
contemporary Common Lisp implementation.


\end{document}

% TODO
%   1.  Create mechanism for swigging DocString and Lisp docs into
%       sections.

