Ignore:
Timestamp:
12/04/12 21:06:12 (8 years ago)
Author:
Mark Evenson
Message:

manual: spellcheck and line-editing.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • branches/1.1.x/doc/manual/abcl.tex

    r14288 r14292  
    3030runs on the Java Virtual Machine.  It compiles Common Lisp to Java 5
    3131bytecode, providing the following integration methods for interfacing
    32 with Java code and librariess:
     32with Java code and libraries:
    3333\begin{itemize}
    3434\item Lisp code can create Java objects and call their methods (see
    … …  
    6767    result of a merge won't fill in a DEVICE with the wrong "default
    6868    device for the host" in the sense of the fourth paragraph in the
    69     [CLHS description of MERGE-PATHNAMES][2] (the paragraph beginning
     69    CLHS description of MERGE-PATHNAMES (see in \cite{CLHS} the paragraph beginning
    7070    "If the PATHNAME explicitly specifies a host and not a device
").
    7171    A future version of the implementation may return to conformance
    … …  
    137137using a versioned package on the local filesystem from your system
    138138vendor.  This jar file can be executed from the command line to obtain a
    139 REPL\footnote{Read-Eval Print Loop, a Lisp commandline}, viz:
     139REPL\footnote{Read-Eval Print Loop, a Lisp command-line}, viz:
    140140
    141141\begin{listing-shell}
    … …  
    173173\item[\texttt{  --load-system-file FILE}] loads the system file FILE before initializing the REPL.
    174174\item[\texttt{  --batch}] evaluates forms specified by arguments and in
    175   the intialization file \verb+~/.abclrc+, and then exits without
     175  the initialization file \verb+~/.abclrc+, and then exits without
    176176  starting a REPL.
    177177\end{description}
    … …  
    214214objects, and construction of new Java objects.
    215215
    216 When calling Java routines, some values will automatically be converted
    217 by the FFI\footnote{Foreign Function Interface, the term for the part of
    218   a Lisp implementation that implements calling code written in other
    219   languages.}  from Lisp values to Java values. These conversions
    220 typically apply to strings, integers and floats. Other values need to be
    221 converted to their Java equivalents by the programmer before calling the
    222 Java object method. Java values returned to Lisp are also generally
    223 converted back to their Lisp counterparts. Some operators make an
    224 exception to this rule and do not perform any conversion; those are the
    225 ``raw'' counterparts of certain FFI functions and are recognizable by
    226 their name ending with \code{-RAW}.
     216When calling Java routines, some values will automatically be
     217converted by the FFI\footnote{Foreign Function Interface, is the term
     218  of art for the part of a Lisp implementation which implements
     219  calling code written in other languages, typically normalized to the
     220  local C compiler calling conventions.}  from Lisp values to Java
     221values. These conversions typically apply to strings, integers and
     222floats. Other values need to be converted to their Java equivalents by
     223the programmer before calling the Java object method. Java values
     224returned to Lisp are also generally converted back to their Lisp
     225counterparts. Some operators make an exception to this rule and do not
     226perform any conversion; those are the ``raw'' counterparts of certain
     227FFI functions and are recognizable by their name ending with
     228\code{-RAW}.
    227229
    228230\subsection{Low-level Java API}
    … …  
    739741be passed to the \code{jmake-proxy} generic function.
    740742
     743\subsection{Implementation of Java classes in Lisp}
     744
     745See \code{JAVA:JNEW-RUNTIME-CLASS} on \ref{JAVA:JNEW-RUNTIME-CLASS}.
     746
     747
    741748\chapter{Implementation Dependent Extensions}
    742749
    … …  
    761768(the value of the special variable \code{JAVA:*CLASSLOADER*}. It has
    762769no effect on Java code outside ABCL.
     770
     771\subsection{Creating a synthetic Java Class at Runtime}
     772
     773See \code{JAVA:JNEW-RUNTIME-CLASS} on \ref{JAVA:JNEW-RUNTIME-CLASS}.
    763774
    764775% include autogen docs for the JAVA package.
    … …  
    805816\section{Pathname}
    806817
    807 We implement an extension to the Pathname that allows for the
    808 description and retrieval of resources named in a
     818We implement an extension to the \code{CL:PATHNAME} that allows for
     819the description and retrieval of resources named in a
    809820\textsc{URI} \footnote{A \textsc{URI} is essentially a superset of
    810   what is commonly understood as a \textsc{URL} We sometimesuse the
     821  what is commonly understood as a \textsc{URL} We sometime suse the
    811822  term URL as shorthand in describing the URL Pathnames, even though
    812823  the corresponding encoding is more akin to a URI as described in
    813824  RFC3986 \cite{rfc3986}.}  scheme that the \textsc{JVM}
    814 ``understands''.  Support is built-in to comprehend the ``http'' and
    815 ``https'' implementations but additional protocol handlers may be
    816 installed at runtime by having \textsc{JVM} symbols present in the
    817 sun.net.protocol.dynamic pacakge. See \cite{maso2000} for more
    818 details.
    819 
    820 \textsc{ABCL} has created specializations of the ANSI Pathname object to
    821 enable to use of \textsc{URI}s to address dynamically loaded resources for the
    822 JVM.  A \code{URL-PATHNAME} has a corresponding \textsc{URI} whose canonical
    823 representation is defined to be the \code{NAMESTRING} of the Pathname.
    824 
    825 %
     825``understands''.  By definition, support is built-in into the JVM to
     826access the ``http'' and ``https'' schemes but additional protocol
     827handlers may be installed at runtime by having \textsc{JVM} symbols
     828present in the sun.net.protocol.dynamic pacakge. See \cite{maso2000}
     829for more details.
     830
     831\textsc{ABCL} has created specializations of the ANSI
     832\code{CL:PATHNAME} object to enable to use of \textsc{URI}s to address
     833dynamically loaded resources for the JVM.  The \code{EXT:URL-PATHNAME}
     834specialization. has a corresponding \textsc{URI} whose canonical
     835representation is defined to be the \code{NAMESTRING} of the
     836Pathname. The \code{EXT:JAR-PATHNAME} extension further specializes
     837the the \code{EXT:URL-PATHNAME} to provide access to components of zip
     838archives. 
     839
     840% RDF description of type hierarchy
     841% TODO Render via some LaTeX mode for graphviz?
    826842\begin{verbatim}
    827 
    828 # RDF description of type hierarchy
    829 % TODO Render via some LaTeX mode for graphviz?
    830 
    831   <jar-pathname> a <url-pathname>.
    832   <url-pathname> a <cl:pathname>.
     843  @prefix ext:   <http://abcl.not.org/cl-packages/extensions/> .
     844  @prefix cl:    <http://abcl.not.org/cl-pacages/common-lisp/> .
     845 
     846  <ext:jar-pathname> a <ext:url-pathname>.
     847  <ext:url-pathname> a <cl:pathname>.
    833848  <cl:logical-pathname> a <cl:pathname> .
    834849\end{verbatim}
    … …  
    840855\index{JAR-PATHNAME}
    841856
    842 Both \code{EXT:URL-PATHNAME} and \code{EXT:JAR-PATHNAME} may be used anywhere
    843 a \code{CL:PATHNAME} is accepted with the following caveats:
     857Both the \code{EXT:URL-PATHNAME} and \code{EXT:JAR-PATHNAME} objects
     858may be used anywhere a \code{CL:PATHNAME} is accepted with the
     859following caveats:
    844860
    845861\begin{itemize}
    … …  
    849865
    850866\index{URI}
    851 \item No canonicalization is performed on the underlying \textsc{URI}
    852   (i.e. the implementation does not attempt to compute the current
    853   name of the representing resource unless it is requested to be
     867\item Any results of canonicalization procesures performed on the
     868  underlying \textsc{URI} are discarded between resolutions (i.e. the
     869  implementation does not attempt to cache the results of current name
     870  resolution of the representing resource unless it is requested to be
    854871  resolved.)  Upon resolution, any cannoicalization procedures
    855872  followed in resolving the resource (e.g. following redirects) are
    … …  
    859876  properties of your local \textsc{REST} infrastructure, these results
    860877  may not necessarily be idempotent over time\footnote {See
    861   \cite{evenson2011} for the draft of the publication of the technical
    862   details}.
     878    \cite{evenson2011} for the draft of the publication of the
     879    technical details}.
    863880
    864881\end{itemize}
    … …  
    875892will load and execute the Quicklisp setup code.
    876893
    877 The implementation currently breaks ANSI conformance by allowing the
    878 types able to be READ for the DEVICE to return a possible CONS of
    879 PATHNAME objects.  %% citation from CLHS needed.
    880 
    881 In order to ``smooth over'' the bit about types being READ from
    882 PATHNAME components, we extend the semantics for the usual PATHNAME
    883 merge semantics when *DEFAULT-PATHNAME-DEFAULTS* contains a
    884 \code{JAR-PATHNAME}. 
     894The implementation currently breaks \textsc{ANSI} conformance by allowing the
     895types able to be READ for the DEVICE to return a possible \code{CONS} of
     896\code{CL:PATHNAME} objects.  %% citation from CLHS needed.
     897
     898In order to ``smooth over'' the bit about types being \code{CL:READ} from
     899\code{CL:PATHNAME} components, we extend the semantics for the usual PATHNAME
     900merge semantics when \code{*DEFAULT-PATHNAME-DEFAULTS*} contains a
     901\code{EXT:JAR-PATHNAME}. 
    885902
    886903%See \ref{_:quicklisp} on page \pageref{_:quicklisp}.
    … …  
    889906
    890907The implementation of these extensions stores all the additional
    891 information in the PATHNAME object itself in ways that while strictly
     908information in the \code{CL:PATHNAME} object itself in ways that while strictly
    892909speaking are conformant, nonetheless may trip up libraries that don't
    893910expect the following:
    … …  
    895912\begin{itemize}
    896913\item \code{DEVICE} can be either a string denoting a drive letter
    897   under DOS or a list of exactly one or two elements.  If
    898   \code{DEVICE} is a list, it denotes a \code{JAR-PATHNAME}, with the entries
    899   containing \code{PATHNAME} objects which describe the outer and (possibley)
    900   locations of the jar archive.
    901 
    902 \item A \code{URL-PATHNAME} always has a \code{HOST} component that is a
     914  under \textsc{DOS} or a list of exactly one or two elements.  If
     915  \code{DEVICE} is a list, it denotes a \code{EXT:JAR-PATHNAME}, with
     916  the entries containing \code{CL:PATHNAME} objects which describe the
     917  outer and (possibly inner) locations of the jar
     918  archive \footnote{The case of inner and outer
     919    \code{EXT:EJAR-PATHNAME} arises when zip archives themselves
     920    contain zip archives which is the case when the ABCL fasl is
     921    included in the abcl.jar zip archive.}.
     922
     923\item A \code{EXT:URL-PATHNAME} always has a \code{HOST} component that is a
    903924  property list.  The values of the \code{HOST} property list are
    904925  always character strings.  The allowed keys have the following meanings:
    … …  
    911932  \end{description}
    912933
    913 
    914934\item In order to encapsulate the implementation decisions for these
    915935  meanings, the following functions provide a setf-able API for
    … …  
    947967abstractions on the standard Java collection classes as defined by the
    948968\code{java.util.List} contract.
     969
     970%% an Example of using java.util.Lisp in Lisp would be nice
    949971
    950972This extension is not automatically loaded by the implementation.   It
    … …  
    11201142
    11211143
    1122 The following \textsc{ASDF} components are added: \code{JAR-FILE},
    1123 \code{JAR-DIRECTORY}, \code{CLASS-FILE-DIRECTORY} and \code{MVN}.
    1124 
     1144When loaded, abcl-asdf adds the following objects to \textsc{ASDF}:
     1145\code{JAR-FILE}, \code{JAR-DIRECTORY}, \code{CLASS-FILE-DIRECTORY} and
     1146\code{MVN}, exporting them (and others) as public symbols.
    11251147
    11261148\subsection{Referencing Maven Artifacts via ASDF}
    … …  
    12011223To one used to the more universal syntax of Lisp pairs upon which the
    12021224definition of read and compile time macros is quite
    1203 natural \footnote{See Graham's ``On Lisp'' http://lib.store.yahoo.net/lib/paulgraham/onlisp.pdf.}, the Java syntax available to
    1204 the Java programmer may be said to suck.  To alleviate this situation,
    1205 the JSS contrib introduces the \code{SHARPSIGN-DOUBLE-QUOTE}
    1206 (\code{\#"}) reader macro, which allows the the specification of the
    1207 name of invoking function as the first element of the relevant s-expr
    1208 which tends to be more congruent to how Lisp programmers seem to be
    1209 wired to think.
     1225natural \footnote{See Graham's ``On Lisp''
     1226  http://lib.store.yahoo.net/lib/paulgraham/onlisp.pdf.}, the Java
     1227syntax available to the Java programmer may be said to suck.  To
     1228alleviate this situation, the JSS contrib introduces the
     1229\code{SHARPSIGN-DOUBLE-QUOTE} (\code{\#"}) reader macro, which allows
     1230the the specification of the name of invoking function as the first
     1231element of the relevant s-expr which tends to be more congruent to how
     1232Lisp programmers seem to be wired to think.
    12101233
    12111234While quite useful, we don't expect that the JSS contrib will be the
    … …  
    12301253\url{http://svn.common-lisp.net/armedbear/trunk/abcl/contrib/jss/README.markdown}
    12311254
     1255\section{jfli}
     1256\label{section:jfli}
     1257
     1258The contrib contains a pure-Java version of JFLI.
     1259
    12321260\section{asdf-install}
    12331261
    … …  
    12631291on January 10, 2012.
    12641292
    1265 In December 2012, we we revised the implementation by adding (A)MOP
    1266 with the release of abcl-1.1.0 .
     1293In December 2012, we revised the implementation by adding (A)MOP
     1294with the release of abcl-1.1.0.
    12671295
    12681296\appendix
Note: See TracChangeset for help on using the changeset viewer.