Changeset 13628


Ignore:
Timestamp:
10/13/11 05:05:20 (10 years ago)
Author:
Mark Evenson
Message:

Adjustments to voice and presentation in the manual.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/abcl/doc/manual/abcl.tex

    r13626 r13628  
    66\begin{document}
    77\title{A Manual for Armed Bear Common Lisp}
    8 \date{October 2, 2011}
     8\date{October 13, 2011}
    99\author{Mark~Evenson, Erik~Huelsmann, Alessio~Stalla, Ville~Voutilainen}
    1010
     
    2222\chapter{Running}
    2323
    24 ABCL is packaged as a single jar file usually named either
     24\textsc{ABCL} is packaged as a single jar file usually named either
    2525``abcl.jar'' or something like``abcl-0.28.0.jar'' if you are using a
    2626versioned package from your system vendor.  This byte archive can be
    2727executed under the control of a suitable JVM by using the ``-jar''
    2828option to parse the manifest, and select the named class
    29 (org.armedbear.lisp.Main) for excution:
     29(\code{org.armedbear.lisp.Main}) for excution:
    3030
    3131\begin{listing-shell}
     
    4747\section{Options}
    4848
    49 ABCL supports the following options:
     49ABCL supports the following command line options:
    5050
    5151\begin{verbatim}
     
    8888
    8989\section{ANSI Common Lisp}
    90 ABCL is currently a non-conforming ANSI Common Lisp implementation due
     90\textsc{ABCL} is currently a non-conforming ANSI Common Lisp implementation due
    9191to the following issues:
    9292
    9393\begin{itemize}
    94   \item Missing statement of conformance in accompanying documentation
    9594  \item The generic function signatures of the DOCUMENTATION symbol do
    9695    not match the CLHS.
     
    101100
    102101\section{Contemporary Common Lisp}
    103 In addition to ANSI conformance, ABCL strives to implement features
     102In addition to ANSI conformance, \textsc{ABCL} strives to implement features
    104103expected of a contemporary Common Lisp.
    105104\begin{itemize}
     
    124123\section{Lisp to Java}
    125124
    126 ABCL offers a number of mechanisms to interact with Java from
    127 its lisp environment. It allows calling methods (and static methods) of
    128 Java objects, manipulation of fields and static fields and construction
    129 of new Java objects.
    130 
    131 When calling Java routines, some values will automatically be converted
    132 by the FFI from Lisp values to Java values. These conversions typically
    133 apply to strings, integers and floats. Other values need to be converted
    134 to their Java equivalents by the programmer before calling the Java
    135 object method. Java values returned to Lisp are also generally converted
    136 back to their Lisp counterparts. Some operators make an exception to this
    137 rule and do not perform any conversion; those are the ``raw'' counterparts
    138 of certain FFI functions and are recognizable by their name ending with
    139 \code{-RAW}.
     125\textsc{ABCL} offers a number of mechanisms to interact with Java from its
     126Lisp environment. It allows calling both instance and static methods
     127of Java objects, manipulation of instance and static fields on Java
     128objects, and construction of new Java objects.
     129
     130When calling Java routines, some values will automatically be
     131converted by the FFI \footnote{FFI stands for Foreign Function
     132  Interface which is the term of art which describes how a Lisp
     133  implementation encapsulates invocation in other languages.}  from
     134Lisp values to Java values. These conversions typically apply to
     135strings, integers and floats. Other values need to be converted to
     136their Java equivalents by the programmer before calling the Java
     137object method. Java values returned to Lisp are also generally
     138converted back to their Lisp counterparts. Some operators make an
     139exception to this rule and do not perform any conversion; those are
     140the ``raw'' counterparts of certain FFI functions and are recognizable
     141by their name ending with \code{-RAW}.
    140142
    141143\subsection{Lowlevel Java API}
     
    143145There's a higher level Java API defined in the
    144146\ref{topic:Higher level Java API: JSS}(JSS package) which is available
    145 in the contrib/ directory. This package is described later in this
     147in the \code{contrib/} directory. This package is described later in this
    146148document.  This section covers the lower level API directly available
    147149after evaluating \code{(require 'JAVA)}.
     
    190192\subsubsection{Dynamic dispatch: caveats}
    191193
    192 Dynamic dispatch is performed by using the Java reflection API. Generally
    193 it works fine, but there are corner cases where the API does not correctly
    194 reflect all the details involved in calling a Java method. An example is
    195 the following Java code:
     194Dynamic dispatch is performed by using the Java reflection
     195API \footnote{The Java reflection API is found in the
     196  \code{java.lang.reflect} package}. Generally the dispatch works
     197fine, but there are corner cases where the API does not correctly
     198reflect all the details involved in calling a Java method. An example
     199is the following Java code:
    196200
    197201\begin{listing-java}
     
    202206\end{listing-java}
    203207
    204 even though the method \code{hasMoreElements} is public in \code{Enumeration},
     208even though the method \code{hasMoreElements()} is public in \code{Enumeration},
    205209the above code fails with
    206210
     
    228232except that the dynamic dispatch part is not shown.
    229233
    230 To avoid such pitfalls, all Java objects in ABCL carry an extra
     234To avoid such pitfalls, all Java objects in \textsc{ABCL} carry an extra
    231235field representing the ``intended class'' of the object. That is the class
    232236that is used first by \code{JAVA:JCALL} and similar to resolve methods;
Note: See TracChangeset for help on using the changeset viewer.