[armedbear-cvs] r13438 - trunk/abcl/doc/manual
mevenson at common-lisp.net
mevenson at common-lisp.net
Fri Aug 5 09:30:50 UTC 2011
Author: mevenson
Date: Fri Aug 5 02:30:50 2011
New Revision: 13438
Log:
Manual renders to pdf via pdflatex.
Added:
trunk/abcl/doc/manual/abcl.sty
- copied, changed from r13437, trunk/abcl/doc/manual/index.tex
Deleted:
trunk/abcl/doc/manual/index.tex
Modified:
trunk/abcl/doc/manual/abcl.tex
trunk/abcl/doc/manual/java.tex
Copied and modified: trunk/abcl/doc/manual/abcl.sty (from r13437, trunk/abcl/doc/manual/index.tex)
==============================================================================
--- trunk/abcl/doc/manual/index.tex Thu Aug 4 09:04:45 2011 (r13437, copy source)
+++ trunk/abcl/doc/manual/abcl.sty Fri Aug 5 02:30:50 2011 (r13438)
@@ -4,8 +4,6 @@
% leaving the manual itself as much as a pure content to be
% comfortably read and modified with a text editor.
-\documentclass[10pt]{article}
-
\usepackage{color,hyperref}
\definecolor{darkblue}{rgb}{0.0,0.0,0.3}
\hypersetup{colorlinks,breaklinks,
@@ -21,9 +19,15 @@
\usepackage{listings}
-\newenvironment{xx}[1]%
- {\begin{lstlisting} }%
- {\end{lstlisting}}
+\lstnewenvironment{listing-java}
+ {\lstset{language=Java}}
+ {}
+
+
+\lstnewenvironment{listing-lisp}
+ {\lstset{language=Lisp}}
+ {}
\usepackage{verbatim}
+\ProvidesPackage{abcl}
Modified: trunk/abcl/doc/manual/abcl.tex
==============================================================================
--- trunk/abcl/doc/manual/abcl.tex Thu Aug 4 09:04:45 2011 (r13437)
+++ trunk/abcl/doc/manual/abcl.tex Fri Aug 5 02:30:50 2011 (r13438)
@@ -1,12 +1,16 @@
+% -*- mode: latex; -*-
% http://en.wikibooks.org/wiki/LaTeX/
-\include{index}
+\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}
+\author{Mark~Evenson, Erik~Huelsmann, Alessio~Stallo, Ville~Voutilainen}
-\section{Introduction}
+\maketitle
+
+\chapter{Introduction}
Armed Bear is a mostly conforming implementation of the ANSI Common
Lisp standard. This manual documents the Armed Bear Common Lisp
@@ -15,15 +19,42 @@
\subsection{Version}
This manual corresponds to abcl-0.27.0, as yet unreleased.
+\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}
-\section{Interaction with host JVM}
+\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
-\subsection{Lisp to Java}
+\section{Lisp to Java}
ABCL offers a number of mechanisms to manipulate Java libraries from
Lisp.
@@ -42,7 +73,7 @@
classpath at runtime (JAVA:ADD-TO-CLASSPATH).
\end{itemize}
-\subsection{Lisp from Java}
+\section{Lisp from Java}
Manipulation of the Lisp API is currently lacking a stable interface,
so what is documented here is subject to change.
@@ -59,7 +90,7 @@
Function.execute(args [...])
\end{itemize}
-\subsubsection{Lisp FFI}
+\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
@@ -68,17 +99,16 @@
from Java, considering the hosted Lisp as the "Foreign Function" that
needs to be "Interfaced".
-\subsubsection{Calling Lisp from Java}
+\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
-\lstset{language=Java}
-\begin{lstlisting}
+\begin{listing-java}
import org.armedbear.lisp.*;
-\end{lstliting}
+\end{listing-java}
to potentially import all the JVM symbol from the `org.armedbear.lisp'
namespace.
@@ -86,9 +116,9 @@
Per JVM, there can only ever be a single Lisp interpreter. This is
started by calling the static method `Interpreter.createInstance()`.
-\begin{code}[java]
+\begin{listing-java}
Interpreter interpreter = Interpreter.createInstance();
-\end{code}
+\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
@@ -102,14 +132,13 @@
}
\end{code}
-
The Lisp \code{eval} primitive may be simply passed strings for evaluation,
as follows
-\begin{code}[java]
+\begin{listing-java}
String line = "(load \"file.lisp\")";
LispObject result = interpreter.eval(line);
-\end{code}
+\end{listing-java}
Notice that all possible return values from an arbitrary Lisp
computation are collapsed into a single return value. Doing useful
@@ -118,13 +147,13 @@
of \code{instanceof} introspection, and forms a whole topic to itself
(c.f. [Introspecting a LispObject])
-Using ``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 `execute()` method with the desired
-parameters.
+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{code}[java]
+\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");
@@ -133,14 +162,14 @@
LispObject result = fooFunction.execute(parameter);
// How to get the "naked string value"?
System.out.println("The result was " + result.writeToString());
-\end{code}
+\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{code}[java]
+\begin{listing-java}
boolean nullp(LispObject object) {
LispObject result = Primitives.NULL.execute(object);
if (result == NIL) {
@@ -148,31 +177,31 @@
}
return true;
}
-\end{code}
+\end{listing-java}
-\paragraph{Introspecting a LispObject}
+\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.
-\paragraph{LispObject as \code{boolean}}
+\subsubsection{LispObject as \code{boolean}}
If the LispObject a generalized boolean values, one can use
\code{getBooleanValue()} to convert to Java:
-\begin{code}[java]
+\begin{listing-java}
LispObject object = Symbol.NIL;
boolean javaValue = object.getBooleanValue();
-\end{code}
+\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{code}[java]
+\begin{listing-java}
boolean javaValue = (object != Symbol.NIL);
-\end{code}
+\end{listing-java}
\paragraph{LispObject is a list}
@@ -180,47 +209,35 @@
the \code{copyToArray} to make things a bit more suitable for Java
iteration.
-\begin{code}[java]
+\begin{listing-java}
LispObject result = interpreter.eval("'(1 2 4 5)");
if (result instanceof Cons) {
LispObject array[] = ((Cons)result.copyToArray());
...
}
-\end{code}
+\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{code}[java]
+\begin{listing-java}
LispObject result = interpreter.eval("'(1 2 4 5)");
while (result != Symbol.NIL) {
doSomething(result.car());
result = result.cdr();
}
-\end{code}
+\end{listing-java}
-\subsection{JAVA}
+\section{Java}
% include autogen docs for the JAVA package.
+\include{java}
-\section{ANSI Common Lisp Conformance}
-
-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
- \item Incomplete MOP
- % 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.
-\end{itemize}
+\section{Multithreading}
-ABCL aims to be be a fully conforming ANSI Common Lisp
-implementation. Any other behavior should be reported as a bug.
+% TODO document the THREADS package.
+\include{threads}
\section{Extensions}
@@ -232,14 +249,14 @@
\include{extensions}
-\subsection{Beyond ANSI}
+\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.
-\subsubsection{Extensions to CLOS}
+\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)}
@@ -250,22 +267,29 @@
print more information about the contents of a java.util.Collection
object
-\begin{code}[lisp]
-(defmethod print-object ((coll (java:jclass "java.util.Collection")) stream)
-\ldots
-\end{code}
+\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{code}[lisp]
-(defmethod print-object ((device-id (java:jclass "dto.nbi.service.hdm.alcatel.com.nNBIDeviceID"
- (\#"getBaseLoader" cl-user::*classpath-manager*)))
-\ldots
-\end{code}
+\begin{listing-lisp}
-\subsubsection{Extensions to the Reader}
+(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
@@ -278,12 +302,7 @@
the corresponding Unicode character is output for characters whose
code is greater than 0x00ff.
-\section{Multithreading}
-
-% TODO document the THREADS package.
-\include{threads}
-
-\section{History}
+\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
Modified: trunk/abcl/doc/manual/java.tex
==============================================================================
--- trunk/abcl/doc/manual/java.tex Thu Aug 4 09:04:45 2011 (r13437)
+++ trunk/abcl/doc/manual/java.tex Fri Aug 5 02:30:50 2011 (r13438)
@@ -1,150 +1,248 @@
\begin{verbatim}
+
%JGET-PROPERTY-VALUE
Function: Gets a JavaBeans property on JAVA-OBJECT.
+
%JSET-PROPERTY-VALUE
Function: Sets a JavaBean property on JAVA-OBJECT.
-*JAVA-OBJECT-TO-STRING-LENGTH*
- Variable: Length to truncate toString() PRINT-OBJECT output for an otherwise unspecialized JAVA-OBJECT. Can be set to NIL to indicate no limit.
+
+*JAVA-OBJECT-TO-STRING-LENGTH*
+ Variable: Length to truncate toString()
+ PRINT-OBJECT output for an otherwise unspecialized JAVA-OBJECT. Can
+ be set to NIL to indicate no limit.
+
ADD-TO-CLASSPATH
Function: (not documented)
+
CHAIN
Function: (not documented)
+
DESCRIBE-JAVA-OBJECT
Function: (not documented)
+
DUMP-CLASSPATH
Function: (not documented)
+
ENSURE-JAVA-CLASS
Function: (not documented)
+
ENSURE-JAVA-OBJECT
Function: Ensures OBJ is wrapped in a JAVA-OBJECT, wrapping it if necessary.
+
GET-DEFAULT-CLASSLOADER
Function: (not documented)
+
JARRAY-COMPONENT-TYPE
Function: Returns the component type of the array type ATYPE
+
JARRAY-LENGTH
Function: (not documented)
+
JARRAY-REF
- Function: Dereferences the Java array JAVA-ARRAY using the given INDICIES, coercing the result into a Lisp object, if possible.
+ Function: Dereferences the Java array JAVA-ARRAY using the given
+ INDICIES, coercing the result into a Lisp object, if possible.
+
JARRAY-REF-RAW
- Function: Dereference the Java array JAVA-ARRAY using the given INDICIES. Does not attempt to coerce the result into a Lisp object.
+ Function: Dereference the Java array JAVA-ARRAY using the given
+ INDICIES. Does not attempt to coerce the result into a Lisp object.
+
JARRAY-SET
Function: Stores NEW-VALUE at the given index in JAVA-ARRAY.
+
JAVA-CLASS
Class: (not documented)
+
JAVA-EXCEPTION
Class: (not documented)
+
JAVA-EXCEPTION-CAUSE
Function: Returns the cause of JAVA-EXCEPTION. (The cause is the Java Throwable
+
JAVA-OBJECT
Class: (not documented)
+
JAVA-OBJECT-P
Function: Returns T if OBJECT is a JAVA-OBJECT.
+
JCALL
- Function: Invokes the Java method METHOD-REF on INSTANCE with arguments ARGS, coercing the result into a Lisp object, if possible.
+ Function: Invokes the Java method METHOD-REF on INSTANCE with
+ arguments ARGS, coercing the result into a Lisp object, if possible.
+
JCALL-RAW
- Function: Invokes the Java method METHOD-REF on INSTANCE with arguments ARGS. Does not attempt to coerce the result into a Lisp object.
+ Function: Invokes the Java method METHOD-REF on INSTANCE with
+ arguments ARGS. Does not attempt to coerce the result into a Lisp
+ object.
+
JCLASS
- Function: Returns a reference to the Java class designated by NAME-OR-CLASS-REF. If the CLASS-LOADER parameter is passed, the class is resolved with respect to the given ClassLoader.
+ Function: Returns a reference to the Java class designated by
+ NAME-OR-CLASS-REF. If the CLASS-LOADER parameter is passed, the class
+ is resolved with respect to the given ClassLoader.
+
JCLASS-ARRAY-P
Function: Returns T if CLASS is an array class
+
JCLASS-CONSTRUCTORS
Function: Returns a vector of constructors for CLASS
+
JCLASS-FIELD
Function: Returns the field named FIELD-NAME of CLASS
+
JCLASS-FIELDS
- Function: Returns a vector of all (or just the declared/public, if DECLARED/PUBLIC is true) fields of CLASS
+ Function: Returns a vector of all (or just the declared/public, if
+ DECLARED/PUBLIC is true) fields of CLASS
+
JCLASS-INTERFACE-P
Function: Returns T if CLASS is an interface
+
JCLASS-INTERFACES
Function: Returns the vector of interfaces of CLASS
+
JCLASS-METHODS
- Function: Return a vector of all (or just the declared/public, if DECLARED/PUBLIC is true) methods of CLASS
+ Function: Return a vector of all (or just the declared/public, if
+ DECLARED/PUBLIC is true) methods of CLASS
+
JCLASS-NAME
Function: When called with one argument, returns the name of the Java class
+
JCLASS-OF
Function: (not documented)
+
JCLASS-SUPERCLASS
Function: Returns the superclass of CLASS, or NIL if it hasn't got one
+
JCLASS-SUPERCLASS-P
Function: Returns T if CLASS-1 is a superclass or interface of CLASS-2
+
JCOERCE
- Function: Attempts to coerce OBJECT into a JavaObject of class INTENDED-CLASS. Raises a TYPE-ERROR if no conversion is possible.
+ Function: Attempts to coerce OBJECT into a JavaObject of class
+ INTENDED-CLASS. Raises a TYPE-ERROR if no conversion is possible.
+
JCONSTRUCTOR
- Function: Returns a reference to the Java constructor of CLASS-REF with the given PARAMETER-CLASS-REFS.
+ Function: Returns a reference to the Java constructor of CLASS-REF
+ with the given PARAMETER-CLASS-REFS.
+
JCONSTRUCTOR-PARAMS
Function: Returns a vector of parameter types (Java classes) for CONSTRUCTOR
+
JEQUAL
Function: Compares obj1 with obj2 using java.lang.Object.equals()
+
JFIELD
Function: Retrieves or modifies a field in a Java class or instance.
+
JFIELD-NAME
Function: Returns the name of FIELD as a Lisp string
+
JFIELD-RAW
Function: Retrieves or modifies a field in a Java class or instance. Does not
+
JFIELD-TYPE
Function: Returns the type (Java class) of FIELD
+
JINSTANCE-OF-P
Function: OBJ is an instance of CLASS (or one of its subclasses)
+
JINTERFACE-IMPLEMENTATION
Function: Creates and returns an implementation of a Java interface with
+
JMAKE-INVOCATION-HANDLER
Function: (not documented)
+
JMAKE-PROXY
Function: (not documented)
+
JMEMBER-PROTECTED-P
Function: MEMBER is a protected member of its declaring class
+
JMEMBER-PUBLIC-P
Function: MEMBER is a public member of its declaring class
+
JMEMBER-STATIC-P
Function: MEMBER is a static member of its declaring class
+
JMETHOD
- Function: Returns a reference to the Java method METHOD-NAME of CLASS-REF with the given PARAMETER-CLASS-REFS.
+ Function: Returns a reference to the Java method METHOD-NAME of
+ CLASS-REF with the given PARAMETER-CLASS-REFS.
+
JMETHOD-LET
Function: (not documented)
+
JMETHOD-NAME
Function: Returns the name of METHOD as a Lisp string
+
JMETHOD-PARAMS
Function: Returns a vector of parameter types (Java classes) for METHOD
+
JMETHOD-RETURN-TYPE
Function: Returns the result type (Java class) of the METHOD
+
JNEW
Function: Invokes the Java constructor CONSTRUCTOR with the arguments ARGS.
+
JNEW-ARRAY
Function: Creates a new Java array of type ELEMENT-TYPE, with the given DIMENSIONS.
+
JNEW-ARRAY-FROM-ARRAY
Function: Returns a new Java array with base type ELEMENT-TYPE (a string or a class-ref)
+
JNEW-ARRAY-FROM-LIST
Function: (not documented)
+
JNEW-RUNTIME-CLASS
Function: (not documented)
+
JNULL-REF-P
Function: Returns a non-NIL value when the JAVA-OBJECT `object` is `null`,
+
JOBJECT-CLASS
Function: Returns the Java class that OBJ belongs to
+
JOBJECT-LISP-VALUE
Function: Attempts to coerce JAVA-OBJECT into a Lisp object.
+
JPROPERTY-VALUE
Function: (not documented)
+
JREDEFINE-METHOD
Function: (not documented)
+
JREGISTER-HANDLER
Function: (not documented)
+
JRESOLVE-METHOD
- Function: Finds the most specific Java method METHOD-NAME on INSTANCE applicable to arguments ARGS. Returns NIL if no suitable method is found. The algorithm used for resolution is the same used by JCALL when it is called with a string as the first parameter (METHOD-REF).
+ Function: Finds the most specific Java method METHOD-NAME on
+ INSTANCE applicable to arguments ARGS. Returns NIL if no suitable
+ method is found. The algorithm used for resolution is the same used
+ by JCALL when it is called with a string as the first parameter
+ (METHOD-REF).
+
JRUN-EXCEPTION-PROTECTED
- Function: Invokes the function CLOSURE and returns the result. Signals an error if stack or heap exhaustion occurs.
+ Function: Invokes the function CLOSURE and returns the result.
+ Signals an error if stack or heap exhaustion occurs.
+
JRUNTIME-CLASS-EXISTS-P
Function: (not documented)
+
JSTATIC
Function: Invokes the static method METHOD on class CLASS with ARGS.
+
JSTATIC-RAW
- Function: Invokes the static method METHOD on class CLASS with ARGS. Does not attempt to coerce the arguments or result into a Lisp object.
+ Function: Invokes the static method METHOD on class CLASS with
+ ARGS. Does not attempt to coerce the arguments or result into a Lisp
+ object.
+
MAKE-CLASSLOADER
Function: (not documented)
+
MAKE-IMMEDIATE-OBJECT
Function: Attempts to coerce a given Lisp object into a java-object of the
+
REGISTER-JAVA-EXCEPTION
- Function: Registers the Java Throwable named by the symbol EXCEPTION-NAME as the condition designated by CONDITION-SYMBOL. Returns T if successful, NIL if not.
+ Function: Registers the Java Throwable named by the symbol
+ EXCEPTION-NAME as the condition designated by CONDITION-SYMBOL.
+ Returns T if successful, NIL if not.
+
UNREGISTER-JAVA-EXCEPTION
Function: Unregisters the Java Throwable EXCEPTION-NAME previously registered by REGISTER-JAVA-EXCEPTION.
+
\end{verbatim}
More information about the armedbear-cvs
mailing list