Adjustments to voice and presentation in the manual.

parent dc787513
......@@ -5,7 +5,7 @@
\begin{document}
\title{A Manual for Armed Bear Common Lisp}
\date{October 2, 2011}
\date{October 13, 2011}
\author{Mark~Evenson, Erik~Huelsmann, Alessio~Stalla, Ville~Voutilainen}
\maketitle
......@@ -21,12 +21,12 @@ This manual corresponds to abcl-0.28.0, as yet unreleased.
\chapter{Running}
ABCL is packaged as a single jar file usually named either
\textsc{ABCL} is packaged as a single jar file usually named either
``abcl.jar'' or something like``abcl-0.28.0.jar'' if you are using a
versioned package from your system vendor. This byte archive can be
executed under the control of a suitable JVM by using the ``-jar''
option to parse the manifest, and select the named class
(org.armedbear.lisp.Main) for excution:
(\code{org.armedbear.lisp.Main}) for excution:
\begin{listing-shell}
cmd$ java -jar abcl.jar
......@@ -46,7 +46,7 @@ simply as:
\section{Options}
ABCL supports the following options:
ABCL supports the following command line options:
\begin{verbatim}
--help
......@@ -87,11 +87,10 @@ property ``user.home''.
\chapter{Conformance}
\section{ANSI Common Lisp}
ABCL is currently a non-conforming ANSI Common Lisp implementation due
\textsc{ABCL} is currently a non-conforming ANSI Common Lisp implementation due
to the following issues:
\begin{itemize}
\item Missing statement of conformance in accompanying documentation
\item The generic function signatures of the DOCUMENTATION symbol do
not match the CLHS.
\end{itemize}
......@@ -100,7 +99,7 @@ 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
In addition to ANSI conformance, \textsc{ABCL} strives to implement features
expected of a contemporary Common Lisp.
\begin{itemize}
\item Incomplete (A)MOP
......@@ -123,26 +122,29 @@ expected of a contemporary Common Lisp.
\section{Lisp to Java}
ABCL offers a number of mechanisms to interact with Java from
its lisp environment. It allows calling methods (and static methods) of
Java objects, manipulation of fields and static fields and construction
of new Java objects.
When calling Java routines, some values will automatically be converted
by the FFI from Lisp values to Java values. These conversions typically
apply to strings, integers and floats. Other values need to be converted
to their Java equivalents by the programmer before calling the Java
object method. Java values returned to Lisp are also generally converted
back to their Lisp counterparts. Some operators make an exception to this
rule and do not perform any conversion; those are the ``raw'' counterparts
of certain FFI functions and are recognizable by their name ending with
\code{-RAW}.
\textsc{ABCL} offers a number of mechanisms to interact with Java from its
Lisp environment. It allows calling both instance and static methods
of Java objects, manipulation of instance and static fields on Java
objects, and construction of new Java objects.
When calling Java routines, some values will automatically be
converted by the FFI \footnote{FFI stands for Foreign Function
Interface which is the term of art which describes how a Lisp
implementation encapsulates invocation in other languages.} from
Lisp values to Java values. These conversions typically apply to
strings, integers and floats. Other values need to be converted to
their Java equivalents by the programmer before calling the Java
object method. Java values returned to Lisp are also generally
converted back to their Lisp counterparts. Some operators make an
exception to this rule and do not perform any conversion; those are
the ``raw'' counterparts of certain FFI functions and are recognizable
by their name ending with \code{-RAW}.
\subsection{Lowlevel Java API}
There's a higher level Java API defined in the
\ref{topic:Higher level Java API: JSS}(JSS package) which is available
in the contrib/ directory. This package is described later in this
in the \code{contrib/} directory. This package is described later in this
document. This section covers the lower level API directly available
after evaluating \code{(require 'JAVA)}.
......@@ -189,10 +191,12 @@ select the best matching method and dispatch the call.
\subsubsection{Dynamic dispatch: caveats}
Dynamic dispatch is performed by using the Java reflection API. Generally
it works fine, but there are corner cases where the API does not correctly
reflect all the details involved in calling a Java method. An example is
the following Java code:
Dynamic dispatch is performed by using the Java reflection
API \footnote{The Java reflection API is found in the
\code{java.lang.reflect} package}. Generally the dispatch works
fine, but there are corner cases where the API does not correctly
reflect all the details involved in calling a Java method. An example
is the following Java code:
\begin{listing-java}
ZipFile jar = new ZipFile("/path/to/some.jar");
......@@ -201,7 +205,7 @@ Method method = els.getClass().getMethod("hasMoreElements");
method.invoke(els);
\end{listing-java}
even though the method \code{hasMoreElements} is public in \code{Enumeration},
even though the method \code{hasMoreElements()} is public in \code{Enumeration},
the above code fails with
\begin{listing-java}
......@@ -227,7 +231,7 @@ calls. The code above corresponds to the following Lisp code:
except that the dynamic dispatch part is not shown.
To avoid such pitfalls, all Java objects in ABCL carry an extra
To avoid such pitfalls, all Java objects in \textsc{ABCL} carry an extra
field representing the ``intended class'' of the object. That is the class
that is used first by \code{JAVA:JCALL} and similar to resolve methods;
the actual class of the object is only tried if the method is not found
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment