Changeset 13853


Ignore:
Timestamp:
02/04/12 21:58:39 (9 years ago)
Author:
rschlatte
Message:

Linkify manual. Also some light adjustments to contents.

Location:
trunk/abcl/doc/manual
Files:
3 edited

Legend:

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

    r13805 r13853  
    11@Misc{maso2000,
    22  author =    {Brian Maso},
    3   title =     {{A New Era for Java Protocol Handlers}},
     3  title =     {A New Era for {Java} Protocol Handlers},
    44  howpublished = {\url{http://java.sun.com/developer/onlineTraining/protocolhandlers/}},
    55  month =     aug,
     
    4040}
    4141
     42@Misc{CLHS,
     43  key =       {CLHS},
     44  author =    {Pitman, Kent and others},
     45  title =     {{Common Lisp HyperSpec}},
     46  howpublished = {\url{http://www.lispworks.com/documentation/HyperSpec/Front/index.htm}},
     47  year =      1996,
     48  note =      {Last accessed Feb 4, 2012},
     49}
     50
     51@Misc{AMOPspec,
     52  key =       {AMOP},
     53  author =    {Kiczales, Gregor and des RiviÚres, Jim and Bobrow, Daniel G.},
     54  title =     {{The Common Lisp Object System} MetaObject Protocol},
     55  howpublished = {\url{http://www.alu.org/mop/index.html}},
     56  year =      1997,
     57  note =      {Last accessed Feb 4, 2012},
     58}
     59
     60@Misc{slime,
     61  key =       {slime},
     62  title =     {{SLIME: The Superior Lisp Interaction Mode for Emacs}},
     63  howpublished = {\url{http://common-lisp.net/project/slime/}},
     64  note =      {Last accessed Feb 4, 2012},
     65}
     66
     67@TechReport{jsr-223,
     68  author =       {Mike Grogan},
     69  title =        {Scripting for the {Java} Platform},
     70  institution =  {Sun Microsystems, Inc.},
     71  year =         2006,
     72  type =      {Final Draft Specification},
     73  number =    {JSR-223},
     74  note =      {\url{http://jcp.org/aboutJava/communityprocess/final/jsr223/index.html}},
     75}
     76
  • trunk/abcl/doc/manual/abcl.sty

    r13815 r13853  
    1313\usepackage{a4wide}
    1414
    15 \newcommand{\code}[1]{
    16   \texttt{#1}
     15\newcommand{\code}[1]{%
     16  \texttt{#1}%
    1717}
    1818
  • trunk/abcl/doc/manual/abcl.tex

    r13842 r13853  
    44\usepackage{abcl}
    55
     6\usepackage{hyperref} % Put this one last, it redefines lots of internals
     7
     8
    69\begin{document}
    7 \title{A Manual for Armed Bear Common Lisp}
    8 \date{January 25, 2012}
    9 \author{Mark~Evenson, Erik~H\"{u}lsmann, Rudi~Schlatte, Alessio~Stalla, Ville~Voutilainen}
     10\title{Armed Bear Common Lisp User Manual}
     11\date{Version 1.1.0-dev\\
     12\smallskip
     13January 25, 2012}
     14\author{Mark Evenson \and Erik H\"{u}lsmann \and Rudolf Schlatte \and
     15  Alessio Stalla \and Ville Voutilainen}
    1016
    1117\maketitle
     
    1521\chapter{Introduction}
    1622
    17 Armed Bear is a conforming implementation of the ANSI Common Lisp
    18 standard (see \ref{chapter:conformance} on page
    19 \pageref{chapter:conformance} which states the details of the
    20 conformance level.  This manual documents the Armed Bear Common Lisp
    21 implementation for users of the system.
    22 
    23 \subsection{Version}
    24 This manual corresponds to abcl-1.1.0-dev, as yet unreleased..
    25 
    26 \subsection{License}
    27 
    28 The implementation is licensed under the terms of the GPL v2 of June
    29 1991 with the ``classpath-exception'' that makes its deployment in
    30 commercial settings quite reasonable.  The license is viral in the
    31 sense that if you change the implementation, and redistribute those
    32 changes, you are required to provide the source to those changes back
    33 to be merged with the public trunk.
    34 
    35 \subsection{Contributors}
    36 
    37 % TODO format this better, optionally link to URI
    38 
     23Armed Bear Common Lisp (ABCL) is an implementation of Common Lisp that
     24runs on the Java Virtual Machine.  It compiles to Java bytecode and
     25integrates with Java code and libraries in a seamless way:
    3926\begin{itemize}
    40 \item Philipp Marek
    41 \texttt{Thanks for the markup}
    42 \item Douglas Miles
    43 \texttt{Thanks for the whacky IKVM stuff and keeping the flame alive
     27\item Lisp code can create Java objects and call their methods (see
     28  Section~\ref{sec:lisp-java}, page~\pageref{sec:lisp-java}).
     29\item Java code can call Lisp functions and generic functions, either
     30  directly (Section~\ref{sec:calling-lisp-from-java},
     31  page~\pageref{sec:calling-lisp-from-java}) or via \texttt{JSR-223}
     32  (Section~\ref{sec:java-scripting-api},
     33  page~\pageref{sec:java-scripting-api}).
     34\item \code{jinterface-implementation} creates Lisp-side implementations
     35  of Java interfaces that can be used as listeners for Swing classes and
     36  similar.
     37\end{itemize}
     38ABCL is supported by the Lisp library manager
     39QuickLisp\footnote{\url{http://quicklisp.org/}} and can run many of the
     40programs and libraries provided therein out-of-the-box.
     41
     42\section{Conformance}
     43\label{section:conformance}
     44
     45\subsection{ANSI Common Lisp}
     46\textsc{ABCL} is currently a (non)-conforming ANSI Common Lisp
     47implementation due to the following known issues:
     48
     49\begin{itemize}
     50\item The generic function signatures of the \code{DOCUMENTATION} symbol
     51  do not match the specification.
     52\item The \code{TIME} form does not return a proper \code{VALUES}
     53  environment to its caller.
     54\end{itemize}
     55
     56Somewhat confusingly, this statement of non-conformance in the
     57accompanying user documentation fulfills the requirements that
     58\textsc{ABCL} is a conforming ANSI Common Lisp implementation according
     59to the Common Lisp HyperSpec~\cite{CLHS}.  Clarifications to this point
     60are solicited.
     61
     62ABCL aims to be be a fully conforming ANSI Common Lisp implementation.
     63Any other behavior should be reported as a bug.
     64
     65\subsection{Contemporary Common Lisp}
     66In addition to ANSI conformance, \textsc{ABCL} strives to implement
     67features expected of a contemporary Common Lisp, i.e. a Lisp of the
     68post-2005 Renaissance.
     69
     70The following known problems detract from \textsc{ABCL} being a proper
     71contemporary Common Lisp.
     72\begin{itemize}
     73\item An incomplete implementation of interactive debugging mechanisms,
     74  namely a no-op version of \code{STEP} \footnote{Somewhat surprisingly
     75    allowed by \textsc{ANSI}}, the inability to inspect local variables
     76  in a given call frame, and the inability to resume a halted
     77  computation at an arbitrarily selected call frame.
     78\item An incomplete implementation of a proper metaobject protocol
     79  (c.f. the (A)MOP specification~\cite{AMOP, AMOPspec})
     80\item Incomplete streams abstraction, in that \textsc{ABCL} needs
     81  suitable abstraction between ANSI and Gray streams.  The streams could
     82  be optimized to the JVM NIO abstractions at great profit for binary
     83  byte-level manipulations.
     84\item Incomplete documentation (missing docstrings from exported symbols
     85  and the draft status of this user manual).
     86\end{itemize}
     87
     88
     89
     90\section{License}
     91
     92ABCL is licensed under the terms of the GPL v2 of June 1991 with the
     93``classpath-exception'' (see the file \texttt{COPYING} in the source
     94distribution for the license, term 13 in the same file for the classpath
     95exception).  This license broadly means that you must distribute the
     96sources to ABCL, including any changes you make, together with a program
     97that includes ABCL, but that you are not required to distribute the
     98sources of the whole program.  Submitting your changes upstream to the
     99ABCL development team is actively encouraged and very much appreciated,
     100of course.
     101
     102\section{Contributors}
     103
     104\begin{itemize}
     105\item Philipp Marek \texttt{Thanks for the markup}
     106\item Douglas Miles \texttt{Thanks for the whacky IKVM stuff and keeping the flame alive
    44107  in the dark years.}
    45 
    46 
    47 \item Alan Ruttenberg
    48 \texttt{Thanks for JSS.}
    49 
     108\item Alan Ruttenberg \texttt{Thanks for JSS.}
    50109\item and of course
    51110\emph{Peter Graves}
     
    53112
    54113
    55 \chapter{Running}
     114\chapter{Running ABCL}
    56115
    57116\textsc{ABCL} is packaged as a single jar file usually named either
    58 ``abcl.jar'' or possibly``abcl-1.0.1.jar'' if one is using a versioned
    59 package on the local filesystem from your system vendor.  This byte
    60 archive can be executed under the control of a suitable JVM \footnote
    61 {Java Virtual Machine} by using the ``-jar'' option to parse the
    62 manifest, and select the class named therein
    63 ``\code{org.armedbear.lisp.Main}'' for execution, viz:
     117\texttt{abcl.jar} or possibly something like \texttt{abcl-1.0.1.jar} if
     118using a versioned package on the local filesystem from your system
     119vendor.  This jar file can be executed from the command line to obtain a
     120REPL\footnote{Read-Eval Print Loop, a Lisp commandline}, viz:
    64121
    65122\begin{listing-shell}
    66123  cmd$ java -jar abcl.jar
    67 \end{listing-shell}
    68 
    69 \emph{N.b.} for the proceeding command to work, the ``java'' executable needs
    70 to be in your path.
    71 
    72 To make it easier to facilitate the use of ABCL in tool chains (such
    73 as SLIME \footnote{SLIME is the Superior Lisp Mode for Interaction
    74   under Emacs}) the invocation is wrapped in a Bourne shell script
    75 under \textsc{UNIX} or a \textsc{DOS} command script under Windows so that ABCL may be
    76 executed simply as:
     124\end{listing-shell} %$ unconfuse Emacs syntax highlighting
     125
     126\emph{N.b.} for the proceeding command to work, the \texttt{java}
     127executable needs to be in your path.
     128
     129To facilitate the use of ABCL in tool chains such as SLIME~\cite{slime}
     130(the Superior Lisp Interaction Mode for Emacs), we provide both a Bourne
     131shell script and a \textsc{DOS} batch file.  If you or your
     132administrator adjusted the path properly, ABCL may be executed simply
     133as:
    77134
    78135\begin{listing-shell}
    79136  cmd$ abcl
    80 \end{listing-shell}
     137\end{listing-shell}%$
     138
     139Probably the easiest way of setting up an editing environment using the
     140Emacs editor is to use QuickLisp and follow the instructions at
     141\url{http://www.quicklisp.org/beta/#slime}.
    81142
    82143\section{Options}
     
    84145ABCL supports the following command line options:
    85146
    86 \begin{verbatim}
    87 --help
    88     Displays this message.
    89 --noinform
    90     Suppresses the printing of startup information and banner.
    91 --noinit
    92     Suppresses the loading of the '~/.abclrc' startup file.
    93 --nosystem
    94     Suppresses loading the 'system.lisp' customization file.
    95 --eval <FORM>
    96     Evaluates the <FORM> before initializing REPL.
    97 --load <FILE>
    98     Loads the file <FILE> before initializing REPL.
    99 --load-system-file <FILE>
    100     Loads the system file <FILE> before initializing REPL.
    101 --batch
    102     The process evaluates forms specified by arguments and possibly by those
    103     by those in the intialization file '~/.abcl', and then exits.
    104 
    105 The occurance of '--' copies the remaining arguments, unprocessed, into
    106 the variable EXTENSIONS:*COMMAND-LINE-ARGUMENT-LIST*.
    107 \end{verbatim}
    108 
    109 All of the command line arguments which follow the occurrence of ``----''
    110 are passed into a list bound to the EXT:*COMMAND-LINE-ARGUMENT-LIST*
    111 variable.
     147\begin{description}
     148\item[\texttt{--help}] displays a help message.
     149\item[\texttt{--noinform}] Suppresses the printing of startup information and banner.
     150\item[\texttt{--noinit}] suppresses the loading of the \texttt{\~/.abclrc} startup file.
     151\item[\texttt{--nosystem}] suppresses loading the \texttt{system.lisp} customization file.
     152\item[\texttt{--eval FORM}] evaluates FORM before initializing the REPL.
     153\item[\texttt{--load FILE}] loads the file FILE before initializing the REPL.
     154\item[\texttt{--load-system-file FILE}] loads the system file FILE before initializing the REPL.
     155\item[\texttt{--batch}] evaluates forms specified by arguments and in
     156  the intialization file \texttt{\~/.abclrc}, and then exits without
     157  starting a REPL.
     158\end{description}
     159
     160All of the command line arguments following the occurrence of \verb+--+
     161are passed unprocessed into a list of strings accessible via the
     162variable \code{EXT:*COMMAND-LINE-ARGUMENT-LIST*} from within ABCL.
    112163
    113164\section{Initialization}
    114165
    115 If the \textsc{ABCL} process is started without the ``--noinit'' flag, it
    116 attempts to load a file named ``.abclrc'' located in the user's home
    117 directory and then interpret its contents. 
     166If the \textsc{ABCL} process is started without the \code{--noinit}
     167flag, it attempts to load a file named \code{.abclrc} in the user's home
     168directory and then interpret its contents.
    118169
    119170The user's home directory is determined by the value of the JVM system
    120 property ``user.home''.  This value may--or may not--correspond to the
    121 value of the HOME system environment variable at the discretion of the
    122 JVM implementation that \textsc{ABCL} finds itself hosted upon.
    123 
    124 \chapter{Conformance}
    125 \label{chapter:conformance}
    126 
    127 \section{ANSI Common Lisp}
    128 \textsc{ABCL} is currently a (non)-conforming ANSI Common Lisp
    129 implementation due to the following known issues:
    130 
    131 \begin{itemize}
    132   \item The generic function signatures of the DOCUMENTATION symbol do
    133     not match the CLHS.
    134   \item The TIME form does not return a proper VALUES environment to
    135     its caller.
    136 \end{itemize}
    137 
    138 Somewhat confusingly, this statement of non-conformance in the
    139 accompanying user documentation fulfills the requirements that
    140 \textsc{ABCL} is a conforming ANSI Common Lisp implementation
    141 according to the CLHS \footnote{Common Lisp Hyperspec language
    142   reference document.}.  Clarifications to this point are solicited.
    143 
    144 ABCL aims to be be a fully conforming ANSI Common Lisp implementation.
    145 Any other behavior should be reported as a bug.
    146 
    147 \section{Contemporary Common Lisp}
    148 In addition to ANSI conformance, \textsc{ABCL} strives to implement features
    149 expected of a contemporary Common Lisp \footnote{i.e. a Lisp of the
    150   post 2005 Renaissance}
    151 
    152 \subsection{Deficiencies}
    153 The following known problems detract from \textsc{ABCL} being a proper
    154 contemporary Common Lisp.
    155 \begin{itemize}
    156 
    157   \item An incomplete implementation of interactive debugging
    158     mechanisms namely a no-op version of
    159     \code{STEP} \footnote{Somewhat surprisingly allowed by
    160       \textsc{ANSI}}, the inability to inspect local variables in a
    161     given call frame, and the inability to resume a halted computation
    162     at an arbitrarily selected call frame.
    163 
    164   \item An incomplete implementation of a properly named metaobject
    165     protocol (c.f. the (A)MOP \footnote{The Art of the  Metaobject Protocol} specification)
    166 
    167     % N.b.
    168     % TODO go through AMOP with symbols, starting by looking for
    169     % matching function signature.
    170     % XXX is this really blocking ANSI conformance?  Answer: we have
    171     % to start with such a ``census'' to determine what we have.
    172 
    173   \item Incomplete streams abstraction, in that \textsc{ABCL} needs suitable
    174     abstraction between ANSI and Gray streams.  The streams could be
    175     optimized to the JVM NIO abstractions at great profit for binary
    176     byte-level manipulations.
    177    
    178   \item Incomplete documentation (missing docstrings from exported
    179     symbols and the draft status of the User Manual).
    180 
    181 \end{itemize}
    182 
    183 \chapter{Interaction with Hosting JVM}
     171property \texttt{user.home}.  This value may or may not correspond
     172to the value of the \texttt{HOME} system environment variable, at the
     173discretion of the JVM implementation that \textsc{ABCL} finds itself
     174hosted upon.
     175
     176\chapter{Interaction with the Hosting JVM}
    184177
    185178%  Plan of Attack
     
    195188
    196189\section{Lisp to Java}
     190\label{sec:lisp-java}
    197191
    198192\textsc{ABCL} offers a number of mechanisms to interact with Java from its
     
    201195objects, and construction of new Java objects.
    202196
    203 When calling Java routines, some values will automatically be
    204 converted by the FFI \footnote{FFI stands for Foreign Function
    205   Interface which is the term of art which describes how a Lisp
    206   implementation encapsulates invocation in other languages.}  from
    207 Lisp values to Java values. These conversions typically apply to
    208 strings, integers and floats. Other values need to be converted to
    209 their Java equivalents by the programmer before calling the Java
    210 object method. Java values returned to Lisp are also generally
     197When calling Java routines, some values will automatically be converted
     198by the FFI\footnote{Foreign Function Interface, the term for the part of
     199  a Lisp implementation that implements calling code written in other
     200  languages.}  from Lisp values to Java values. These conversions
     201typically apply to strings, integers and floats. Other values need to be
     202converted to their Java equivalents by the programmer before calling the
     203Java object method. Java values returned to Lisp are also generally
    211204converted back to their Lisp counterparts. Some operators make an
    212 exception to this rule and do not perform any conversion; those are
    213 the ``raw'' counterparts of certain FFI functions and are recognizable
    214 by their name ending with \code{-RAW}.
     205exception to this rule and do not perform any conversion; those are the
     206``raw'' counterparts of certain FFI functions and are recognizable by
     207their name ending with \code{-RAW}.
    215208
    216209\subsection{Low-level Java API}
    217210
    218 We define a higher level Java API in the topic:Higher level Java JSS
    219 package developed by Alan Ruttenberg which is available in the
    220 \code{contrib/} directory, see the  . This package is
    221 described later in this document, see Section~\ref{section:jss} on page
    222 \pageref{section:jss}.  This section covers the lower level API
    223 directly available after evaluating \code{(require 'JAVA)}.
     211This subsection covers the low-level API available after evaluating
     212\code{(require 'JAVA)}.  A higher level Java API, developed by Alan
     213Ruttenberg, is available in the \code{contrib/} directory and described
     214later in this document, see Section~\ref{section:jss} on page
     215\pageref{section:jss}.
    224216
    225217\subsubsection{Calling Java Object Methods}
     
    234226\end{itemize}
    235227
    236 The dynamic dispatch variant is discussed in the next section.
    237 
    238 \code{JAVA:JMETHOD} is used to acquire a specific method reference.
    239 The function takes at two or more arguments. The first is Java class designator
    240 (a \code{JAVA:JAVA-CLASS} object returned by \code{JAVA:JCLASS} or a string naming
    241 a Java class). The second is a string naming the method.
    242 
    243 Any arguments beyond the first two should be strings naming Java classes with
    244 one exception as listed in the next paragraph. These
    245 classes specify the types of the arguments for the method to be returned.
    246 
    247 There's additional calling convention to the \code{JAVA:JMETHOD} function:
    248 When the method is called with three parameters and the last parameter is an
    249 integer, the first method by that name and matching number of parameters is
    250 returned.
    251 
    252 Once one has a reference to the method, one may invoke it using
     228\code{JAVA:JMETHOD} is used to acquire a specific method reference.  The
     229function takes two or more arguments. The first is a Java class
     230designator (a \code{JAVA:JAVA-CLASS} object returned by
     231\code{JAVA:JCLASS} or a string naming a Java class). The second is a
     232string naming the method.
     233
     234Any arguments beyond the first two should be strings naming Java
     235classes, with one exception as listed in the next paragraph. These
     236classes specify the types of the arguments for the method.
     237
     238When \code{JAVA:JMETHOD} is called with three parameters and the last
     239parameter is an integer, the first method by that name and matching
     240number of parameters is returned.
     241
     242Once a method reference has been acquired, it can be invoked using
    253243\code{JAVA:JCALL}, which takes the method as the first argument. The
    254244second argument is the object instance to call the method on, or
     
    281271\end{listing-java}
    282272
    283 even though the method \code{hasMoreElements()} is public in \code{Enumeration},
    284 the above code fails with
     273Even though the method \code{hasMoreElements()} is public in
     274\code{Enumeration}, the above code fails with
    285275
    286276\begin{listing-java}
     
    293283\end{listing-java}
    294284
    295 because the method has been overridden by a non-public class and the
    296 reflection API, unlike javac, is not able to handle such a case.
     285This is because the method has been overridden by a non-public class and
     286the reflection API, unlike \texttt{javac}, is not able to handle such a case.
    297287
    298288While code like that is uncommon in Java, it is typical of ABCL's FFI
     
    308298
    309299To avoid such pitfalls, all Java objects in \textsc{ABCL} carry an extra
    310 field representing the ``intended class'' of the object. That is the class
    311 that is used first by \code{JAVA:JCALL} and similar to resolve methods;
    312 the actual class of the object is only tried if the method is not found
    313 in the intended class. Of course, the intended class is always a super-class
    314 of the actual class - in the worst case, they coincide. The intended class
    315 is deduced by the return type of the method that originally returned
    316 the Java object; in the case above, the intended class of \code{ELS}
    317 is \code{java.util.Enumeration} because that's the return type of
    318 the \code{entries} method.
     300field representing the ``intended class'' of the object. That class is
     301used first by \code{JAVA:JCALL} and similar to resolve methods; the
     302actual class of the object is only tried if the method is not found in
     303the intended class. Of course, the intended class is always a
     304super-class of the actual class -- in the worst case, they coincide. The
     305intended class is deduced by the return type of the method that
     306originally returned the Java object; in the case above, the intended
     307class of \code{ELS} is \code{java.util.Enumeration} because that is the
     308return type of the \code{entries} method.
    319309
    320310While this strategy is generally effective, there are cases where the
     
    341331\subsubsection{Calling Java class static methods}
    342332
    343 Like with non-static methods, references to static methods can be acquired
    344 by using the \code{JAVA:JMETHOD} primitive. In order to call this method,
    345 it's not possible to use the \code{JAVA:JCALL} primitive however: there's a
    346 separate API to retrieve a reference to static methods. This
    347 primitive is called \code{JAVA:JSTATIC}.
     333Like non-static methods, references to static methods can be acquired by
     334using the \code{JAVA:JMETHOD} primitive. Static methods are called with
     335\code{JAVA:JSTATIC} instead of \code{JAVA:JCALL}.
    348336
    349337Like \code{JAVA:JCALL}, \code{JAVA:JSTATIC} supports dynamic dispatch by
     
    364352
    365353Java objects can be instantiated (created) from Lisp by calling
    366 a constructor from the class of the object to be created. The same way
    367 \code{JAVA:JMETHOD} is used to acquire a method reference, the
    368 \code{JAVA:JCONSTRUCTOR} primitive can be used to acquire a constructor
     354a constructor from the class of the object to be created. The
     355\code{JAVA:JCONSTRUCTOR} primitive is used to acquire a constructor
    369356reference. It's arguments specify the types of arguments of the constructor
    370357method the same way as with \code{JAVA:JMETHOD}.
    371358
    372 The constructor can't be passed to \code{JAVA:JCALL}, but instead should
    373 be passed as an argument to \code{JAVA:JNEW}.
    374 
    375 \subsubsection{Accessing Java object fields}
    376 
    377 Fields in Java objects can be accessed using the getter and setter functions
    378 \code{JAVA:GETFIELD} and \code{JAVA:PUTFIELD}. This applies to values stored in object
    379 instances. If you want to access static fields: see the next section.
     359The obtained constructor is passed as an argument to \code{JAVA:JNEW},
     360together with any arguments.  \code{JAVA:JNEW} can also be invoked with
     361a string naming the class as its first argument.
     362
     363\subsubsection{Accessing Java object and class fields}
     364
     365Fields in Java objects can be accessed using the getter and setter
     366functions \code{JAVA:JFIELD} and \code{(SETF JAVA:JFIELD)}.  Static
     367(class) fields are accessed the same way, but with a class object or
     368string naming a class as first argument.
    380369
    381370Like \code{JAVA:JCALL} and friends, values returned from these accessors carry
    382 an intended class around and values which can be converted to Lisp values will
     371an intended class around, and values which can be converted to Lisp values will
    383372be converted.
    384373
    385 \subsubsection{Accessing Java static fields}
    386 
    387 Static fields in Java objects (class fields) can be accessed using the getter
    388 and setter functions \code{JAVA:GETSTATIC} and \code{JAVA:PUTSTATIC}. Values
    389 stored in object instance fields can be accessed as described in the previous
    390 section.
    391 
    392 Like \code{JAVA:JCALL} and friends, values returned from these accessors carry
    393 an intended class around and values which can be converted to Lisp values will
    394 be converted.
    395 
    396 \section{Lisp from Java}
    397 
    398 In order to access the Lisp world from Java, one needs to be aware
    399 of a few things. The most important ones are listed below.
     374\section{Java to Lisp}
     375
     376This section describes the various ways that one interacts with Lisp
     377from Java code.  In order to access the Lisp world from Java, one needs
     378to be aware of a few things, the most important ones being listed below:
    400379
    401380\begin{itemize}
    402 \item All Lisp values are descendants of LispObject.java
    403 \item In order to
    404 \item Lisp symbols are accessible via either directly referencing the
    405   Symbol.java instance or by dynamically introspecting the
    406   corresponding Package.java instance.
     381\item All Lisp values are descendants of \code{LispObject}.
     382\item Lisp symbols are accessible either via static members of the
     383  \code{Symbol} class, or by dynamically introspecting a \code{Package}
     384  object.
    407385\item The Lisp dynamic environment may be saved via
    408386  \code{LispThread.bindSpecial(Binding)} and restored via
    409387  \code{LispThread.resetSpecialBindings(Mark)}.
    410 \item Functions may be executed by invocation of the
    411   Function.execute(args [...])
     388\item Functions can be executed by invoking \code{LispObject.execute(args
     389    [...])}
    412390\end{itemize}
    413391
    414 \subsection{Lisp FFI}
    415 
    416 FFI stands for "Foreign Function Interface" which is the phase which
    417 the contemporary Lisp world refers to methods of "calling out" from
    418 Lisp into "foreign" languages and environments.  This document
    419 describes the various ways that one interacts with Lisp world of ABCL
    420 from Java, considering the hosted Lisp as the "Foreign Function" that
    421 needs to be "Interfaced".
    422 
    423392\subsection{Calling Lisp from Java}
    424 
    425 Note: As the entire ABCL Lisp system resides in the org.armedbear.lisp
    426 package the following code snippets do not show the relevant import
    427 statements in the interest of brevity.  An example of the import
    428 statement would be
    429 
     393\label{sec:calling-lisp-from-java}
     394
     395Note: the entire ABCL Lisp system resides in the
     396\texttt{org.armedbear.lisp} package, but the following code snippets do
     397not show the relevant import statements in the interest of brevity.  An
     398example of the import statement would be
    430399\begin{listing-java}
    431400  import org.armedbear.lisp.*;
    432401\end{listing-java}
    433 
    434402to potentially import all the JVM symbol from the `org.armedbear.lisp'
    435403namespace.
    436404
    437 Per JVM, there can only ever be a single Lisp interpreter.  This is
    438 started by calling the static method `Interpreter.createInstance()`.
     405There can only ever be a single Lisp interpreter per JVM instance.  A
     406reference to this interpreter is obtained by calling the static method
     407\code{Interpreter.createInstance()}.
    439408
    440409\begin{listing-java}
     
    443412
    444413If this method has already been invoked in the lifetime of the current
    445 Java process it will return null, so if you are writing Java whose
    446 life-cycle is a bit out of your control (like in a Java servlet), a
    447 safer invocation pattern might be:
     414Java process it will return \texttt{null}, so if you are writing Java
     415whose life-cycle is a bit out of your control (like in a Java servlet),
     416a safer invocation pattern might be:
    448417
    449418\begin{listing-java}
     
    455424
    456425
    457 The Lisp \code{eval} primitive may be simply passed strings for evaluation,
    458 as follows
     426The Lisp \code{eval} primitive may simply be passed strings for evaluation:
    459427
    460428\begin{listing-java}
     
    465433Notice that all possible return values from an arbitrary Lisp
    466434computation are collapsed into a single return value.  Doing useful
    467 further computation on the ``LispObject'' depends on knowing what the
    468 result of the computation might be, usually involves some amount
     435further computation on the \code{LispObject} depends on knowing what the
     436result of the computation might be.  This usually involves some amount
    469437of \code{instanceof} introspection, and forms a whole topic to itself
    470 (c.f. [Introspecting a LispObject])
     438(see Section~\ref{topic:Introspecting a LispObject},
     439page~\pageref{topic:Introspecting a LispObject}).
    471440
    472441Using \code{eval} involves the Lisp interpreter.  Lisp functions may
    473 be directly invoked by Java method calls as follows.  One simply
    474 locates the package containing the symbol, then obtains a reference to
    475 the symbol, and then invokes the \code{execute()} method with the
    476 desired parameters.
     442also be directly invoked by Java method calls as follows.  One simply
     443locates the package containing the symbol, obtains a reference to the
     444symbol, and then invokes the \code{execute()} method with the desired
     445parameters.
    477446
    478447\begin{listing-java}
    479     interpreter.eval("(defun foo (msg) (format nil \"You told me '~A'~%\" msg))");
    480     Package pkg = Packages.findPackage("CL-USER");
    481     Symbol foo = pkg.findAccessibleSymbol("FOO");
    482     Function fooFunction = (Function)foo.getSymbolFunction();
    483     JavaObject parameter = new JavaObject("Lisp is fun!");
    484     LispObject result = fooFunction.execute(parameter);
    485     // How to get the "naked string value"?
    486     System.out.println("The result was " + result.writeToString());
     448  interpreter.eval("(defun foo (msg)" +
     449    "(format nil \"You told me '~A'~%\" msg))");
     450  Package pkg = Packages.findPackage("CL-USER");
     451  Symbol foo = pkg.findAccessibleSymbol("FOO");
     452  Function fooFunction = (Function)foo.getSymbolFunction();
     453  JavaObject parameter = new JavaObject("Lisp is fun!");
     454  LispObject result = fooFunction.execute(parameter);
     455  // How to get the "naked string value"?
     456  System.out.println("The result was " + result.writeToString());
    487457\end{listing-java}
    488458
    489 If one is calling an primitive function in the CL package the syntax
    490 becomes considerably simpler.  If we can locate the instance of
    491 definition in the ABCL Java source, we can invoke the symbol directly.
    492 For instance, to tell if a `LispObject` contains a reference to a symbol.
     459If one is calling a function in the CL package, the syntax can become
     460considerably simpler.  If we can locate the instance of definition in
     461the ABCL Java source, we can invoke the symbol directly.  For instance,
     462to tell if a \code{LispObject} is (Lisp) \texttt{NIL}, we can invoke the
     463CL function \code{NULL} in the following way:
    493464
    494465\begin{listing-java}
    495     boolean nullp(LispObject object) {
    496       LispObject result = Primitives.NULL.execute(object);
    497       if (result == NIL) { // the symbol 'NIL' is explicitly named in the Java
    498                            // namespace at ``Symbol.NIL''
    499                            // but is always present in the
    500                            // local namespace in its unadorned form for
    501                            // the convenience of the User.
    502         return false;
    503       }
    504       return true;
    505    }
     466  boolean nullp(LispObject object) {
     467    LispObject result = Primitives.NULL.execute(object);
     468    if (result == NIL) { // the symbol 'NIL' is explicitly named in the Java
     469                         // namespace at ``Symbol.NIL''
     470                         // but is always present in the
     471                         // local namespace in its unadorned form for
     472                         // the convenience of the User.
     473      return false;
     474    }
     475    return true;
     476 }
    506477\end{listing-java}
    507478
     
    509480\label{topic:Introspecting a LispObject}
    510481
    511 We present various patterns for introspecting an an arbitrary
    512 `LispObject` which can represent the result of every Lisp evaluation
     482We present various patterns for introspecting an arbitrary
     483\code{LispObject} which can hold the result of every Lisp evaluation
    513484into semantics that Java can meaningfully deal with.
    514485
    515 \subsubsection{LispObject as \code{boolean}}
    516 
    517 If the LispObject a generalized boolean values, one can use
    518 \code{getBooleanValue()} to convert to Java:
     486\paragraph{LispObject as \code{boolean}}
     487
     488If the \code{LispObject} is to be interpreted as a generalized boolean
     489value, one can use \code{getBooleanValue()} to convert to Java:
    519490
    520491\begin{listing-java}
    521      LispObject object = Symbol.NIL;
    522      boolean javaValue = object.getBooleanValue();
     492   LispObject object = Symbol.NIL;
     493   boolean javaValue = object.getBooleanValue();
    523494\end{listing-java}
    524495
    525 Although since in Lisp, any value other than NIL means "true"
    526 (so-called generalized Boolean), the use of Java equality it quite a
    527 bit easier to type and more optimal in terms of information it conveys
    528 to the compiler would be:
     496Since in Lisp any value other than \code{NIL} means "true", Java
     497equality can also be used, which is a bit easier to type and better in
     498terms of information it conveys to the compiler:
    529499
    530500\begin{listing-java}
     
    532502\end{listing-java}
    533503
    534 \paragraph{LispObject is a list}
    535 
    536 If LispObject is a list, it will have the type `Cons`.  One can then use
    537 the \code{copyToArray} to make things a bit more suitable for Java
    538 iteration.
     504\paragraph{LispObject as a list}
     505
     506If \code{LispObject} is a list, it will have the type \code{Cons}.  One
     507can then use the \code{copyToArray} method to make things a bit more
     508suitable for Java iteration.
    539509
    540510\begin{listing-java}
    541     LispObject result = interpreter.eval("'(1 2 4 5)");
    542     if (result instanceof Cons) {
    543       LispObject array[] = ((Cons)result.copyToArray());
    544       ...
    545     }
     511  LispObject result = interpreter.eval("'(1 2 4 5)");
     512  if (result instanceof Cons) {
     513    LispObject array[] = ((Cons)result.copyToArray());
     514    ...
     515  }
    546516\end{listing-java}
    547517
    548 A more Lispy way to iterated down a list is to use the `cdr()` access
     518A more Lispy way to iterate down a list is to use the `cdr()` access
    549519function just as like one would traverse a list in Lisp:;
    550520
    551521\begin{listing-java}
    552     LispObject result = interpreter.eval("'(1 2 4 5)");
    553     while (result != Symbol.NIL) {
    554       doSomething(result.car());
    555       result = result.cdr();
    556     }
     522  LispObject result = interpreter.eval("'(1 2 4 5)");
     523  while (result != Symbol.NIL) {
     524    doSomething(result.car());
     525    result = result.cdr();
     526  }
    557527\end{listing-java}
    558528
    559 \subsection{Java Scripting API (JSR-223)}
    560 
    561 ABCL can be built with support for JSR-223, which offers a
    562 language-agnostic API to invoke other languages from Java. The binary
    563 distribution download-able from ABCL's common-lisp.net home is built
    564 with JSR-223 support. If you're building ABCL from source on a pre-1.6
    565 JVM, you need to have a JSR-223 implementation in your CLASSPATH (such
    566 as Apache Commons BSF 3.x or greater) in order to build ABCL with
    567 JSR-223 support; otherwise, this feature will not be built.
     529\section{Java Scripting API (JSR-223)}
     530\label{sec:java-scripting-api}
     531
     532ABCL can be built with support for JSR-223~\cite{jsr-223}, which offers
     533a language-agnostic API to invoke other languages from Java. The binary
     534distribution download-able from ABCL's homepage is built with JSR-223
     535support. If you're building ABCL from source on a pre-1.6 JVM, you need
     536to have a JSR-223 implementation in your classpath (such as Apache
     537Commons BSF 3.x or greater) in order to build ABCL with JSR-223 support;
     538otherwise, this feature will not be built.
    568539
    569540This section describes the design decisions behind the ABCL JSR-223
    570541support. It is not a description of what JSR-223 is or a tutorial on
    571542how to use it. See
    572 http://trac.common-lisp.net/armedbear/browser/trunk/abcl/examples/jsr-223
     543\url{http://trac.common-lisp.net/armedbear/browser/trunk/abcl/examples/jsr-223}
    573544for example usage.
    574545
    575 \subsubsection{Conversions}
     546\subsection{Conversions}
    576547
    577548In general, ABCL's implementation of the JSR-223 API performs implicit
     
    581552conversions, wrap the relevant objects in \code{JavaObject} instances.
    582553
    583 \subsubsection{Implemented JSR-223 interfaces}
    584 
    585 JSR-223 defines three main interfaces, of which two (Invocable and
    586 Compilable) are optional. ABCL implements all the three interfaces -
    587 ScriptEngine and the two optional ones - almost completely. While the
    588 JSR-223 API is not specific to a single scripting language, it was
    589 designed with languages with a more or less Java-like object model in
    590 mind: languages such as Javascript, Python, Ruby, which have a concept
    591 of "class" or "object" with "fields" and "methods". Lisp is a bit
    592 different, so certain adaptations were made, and in one case a method
    593 has been left unimplemented since it does not map at all to Lisp.
     554\subsection{Implemented JSR-223 interfaces}
     555
     556JSR-223 defines three main interfaces, of which two (\code{Invocable}
     557and \code{Compilable}) are optional. ABCL implements all the three
     558interfaces - \code{ScriptEngine} and the two optional ones - almost
     559completely. While the JSR-223 API is not specific to a single scripting
     560language, it was designed with languages with a more or less Java-like
     561object model in mind: languages such as Javascript, Python, Ruby, which
     562have a concept of "class" or "object" with "fields" and "methods". Lisp
     563is a bit different, so certain adaptations were made, and in one case a
     564method has been left unimplemented since it does not map at all to Lisp.
    594565
    595566\subsubsection{The ScriptEngine}
    596567
    597 The main interface defined by JSR-223, javax.script.ScriptEngine, is
    598 implemented by the class
    599 \code{org.armedbear.lisp.scripting.AbclScriptEngine}. AbclScriptEngine
     568The main interface defined by JSR-223, \code{javax.script.ScriptEngine},
     569is implemented by the class
     570\code{org.armedbear.lisp.scripting.AbclScriptEngine}. \code{AbclScriptEngine}
    600571is a singleton, reflecting the fact that ABCL is a singleton as
    601 well. You can obtain an instance of AbclScriptEngine using the
    602 AbclScriptEngineFactory or by using the service provider mechanism
    603 through ScriptEngineManager (refer to the javax.script documentation).
    604 
    605 \subsubsection{Start-up and configuration file}
     572well. You can obtain an instance of \code{AbclScriptEngine} using the
     573\code{AbclScriptEngineFactory} or by using the service provider
     574mechanism through \code{ScriptEngineManager} (refer to the
     575\texttt{javax.script} documentation).
     576
     577\subsection{Start-up and configuration file}
    606578
    607579At start-up (i.e. when its constructor is invoked, as part of the
    608 static initialization phase of AbclScriptEngineFactory) the ABCL
     580static initialization phase of \code{AbclScriptEngineFactory}) the ABCL
    609581script engine attempts to load an "init file" from the classpath
    610 (/abcl-script-config.lisp). If present, this file can be used to
     582(\texttt{/abcl-script-config.lisp}). If present, this file can be used to
    611583customize the behavior of the engine, by setting a number of
    612 variables in the ABCL-SCRIPT package. Here is a list of the available
     584variables in the \code{ABCL-SCRIPT} package. Here is a list of the available
    613585variables:
    614586
    615 \begin{itemize}
    616 \item *use-throwing-debugger* Controls whether ABCL uses a
     587\begin{description}
     588\item[\texttt{*use-throwing-debugger*}] controls whether ABCL uses a
    617589  non-standard debugging hook function to throw a Java exception
    618590  instead of dropping into the debugger in case of unhandled error
    619591  conditions.
    620592  \begin{itemize}
    621   \item Default value: T
     593  \item Default value: \texttt{T}
    622594  \item Rationale: it is more convenient for Java programmers using
    623595    Lisp as a scripting language to have it return exceptions to Java
     
    627599    it doesn't work for you.
    628600  \end{itemize}
    629 \item *launch-swank-at-startup* If true, Swank will be launched at
    630   startup. See *swank-dir* and *swank-port*.
     601\item[\texttt{*launch-swank-at-startup*}] If true, Swank will be launched at
     602  startup. See \texttt{*swank-dir*} and \texttt{*swank-port*}.
    631603  \begin{itemize}
    632   \item Default value: NIL
     604  \item Default value: \texttt{NIL}
    633605  \end{itemize}
    634 \item *swank-dir* The directory where Swank is installed. Must be set
    635   if *launch-swank-at-startup* is true.
    636 \item *swank-port* The port where Swank will listen for
    637   connections. Must be set if *launch-swank-at-startup* is true.
     606\item[\texttt{*swank-dir*}] The directory where Swank is installed. Must be set
     607  if \texttt{*launch-swank-at-startup*} is true.
     608\item[\texttt{*swank-port*}] The port where Swank will listen for
     609  connections. Must be set if \texttt{*launch-swank-at-startup*} is
     610  true.
    638611  \begin{itemize}
    639612  \item Default value: 4005
    640613  \end{itemize}
    641 \end{itemize}
     614\end{description}
    642615
    643616Additionally, at startup the AbclScriptEngine will \code{(require
    644617  'asdf)} - in fact, it uses asdf to load Swank.
    645618
    646 \subsubsection{Evaluation}
    647 
    648 Code is read and evaluated in the package ABCL-SCRIPT-USER. This
    649 packages USEs the COMMON-LISP, JAVA and ABCL-SCRIPT packages. Future
    650 versions of the script engine might make this default package
    651 configurable. The \code{CL:LOAD} function is used under the hood for
    652 evaluating code, and thus the same behavior of LOAD is
    653 guaranteed. This allows, among other things, \code{IN-PACKAGE} forms
    654 to change the package in which the loaded code is read.
     619\subsection{Evaluation}
     620
     621Code is read and evaluated in the package \code{ABCL-SCRIPT-USER}. This
     622packages \texttt{USE}s the \code{COMMON-LISP}, \code{JAVA} and
     623\code{ABCL-SCRIPT} packages. Future versions of the script engine might
     624make this default package configurable. The \code{CL:LOAD} function is
     625used under the hood for evaluating code, and thus the behavior of
     626\code{LOAD} is guaranteed. This allows, among other things,
     627\code{IN-PACKAGE} forms to change the package in which the loaded code
     628is read.
    655629
    656630It is possible to evaluate code in what JSR-223 calls a
    657 "ScriptContext" (basically a flat environment of name->value
     631``ScriptContext'' (basically a flat environment of name$\rightarrow$value
    658632pairs). This context is used to establish special bindings for all the
    659633variables defined in it; since variable names are strings from Java's
    660 point of view, they are first interned using READ-FROM-STRING with, as
    661 usual, ABCL-SCRIPT-USER as the default package. Variables are declared
     634point of view, they are first interned using \code{READ-FROM-STRING} with, as
     635usual, \code{ABCL-SCRIPT-USER} as the default package. Variables are declared
    662636special because CL's \code{LOAD}, \code{EVAL} and \code{COMPILE}
    663637functions work in a null lexical environment and would ignore
     
    668642evaluation of short scripts does the Right Thing.
    669643
    670 \subsubsection{Compilation}
     644\subsection{Compilation}
    671645
    672646AbclScriptEngine implements the \code{javax.script.Compilable}
    673647interface. Currently it only supports compilation using temporary
    674648files. Compiled code, returned as an instance of
    675 javax.script.CompiledScript, is read, compiled and executed by default
    676 in the ABCL-SCRIPT-USER package, just like evaluated code. Differently
    677 from evaluated code, though, due to the way the ABCL compiler works,
    678 compiled code contains no reference to top-level self-evaluating
    679 objects (like numbers or strings). Thus, when evaluated, a piece of
    680 compiled code will return the value of the last non-self-evaluating
    681 form: for example the code "(do-something) 42" will return 42 when
    682 interpreted, but will return the result of (do-something) when
    683 compiled and later evaluated. To ensure consistency of behavior
    684 between interpreted and compiled code, make sure the last form is
    685 always a compound form - at least (identity some-literal-object). Note
    686 that this issue should not matter in real code, where it is unlikely a
    687 top-level self-evaluating form will appear as the last form in a file
    688 (in fact, the Common Lisp load function always returns T upon success;
    689 with JSR-223 this policy has been changed to make evaluation of small
    690 code snippets work as intended).
    691 
    692 \subsubsection{Invocation of functions and methods}
     649\texttt{javax.script.CompiledScript}, is read, compiled and executed by
     650default in the \texttt{ABCL-SCRIPT-USER} package, just like evaluated
     651code.  In contrast to evaluated code, though, due to the way the ABCL
     652compiler works, compiled code contains no reference to top-level
     653self-evaluating objects (like numbers or strings). Thus, when evaluated,
     654a piece of compiled code will return the value of the last
     655non-self-evaluating form: for example the code ``\code{(do-something)
     656  42}'' will return 42 when interpreted, but will return the result of
     657(do-something) when compiled and later evaluated. To ensure consistency
     658of behavior between interpreted and compiled code, make sure the last
     659form is always a compound form - at least \code{(identity
     660some-literal-object)}. Note that this issue should not matter in real
     661code, where it is unlikely a top-level self-evaluating form will appear
     662as the last form in a file (in fact, the Common Lisp load function
     663always returns \texttt{T} upon success; with JSR-223 this policy has been changed
     664to make evaluation of small code snippets work as intended).
     665
     666\subsection{Invocation of functions and methods}
    693667
    694668AbclScriptEngine implements the \code{javax.script.Invocable}
     
    699673attached to objects but belong to generic functions. Thus, the method
    700674\code{invokeMethod()} is not implemented and throws an
    701 UnsupportedOperationException when called. The \code{invokeFunction()}
     675\texttt{UnsupportedOperationException} when called. The \code{invokeFunction()}
    702676method should be used to call both regular and generic functions.
    703677
    704 \subsubsection{Implementation of Java interfaces in Lisp}
     678\subsection{Implementation of Java interfaces in Lisp}
    705679
    706680ABCL can use the Java reflection-based proxy feature to implement Java
     
    730704  and all the parameters. Useful for interfaces with a single method,
    731705  or to implement custom interface-implementation strategies.
    732 \item a hash-map of method-name -> Lisp function mappings. Function
     706\item a hash-map of method-name $\rightarrow$ Lisp function mappings. Function
    733707  signature is \code{(lisp-this \&rest args)}.
    734708\item a Lisp package. The name of the Java method to invoke is first
     
    739713\end{itemize}
    740714
    741 This functionality is exposed by the AbclScriptEngine with the two
    742 methods getInterface(Class) and getInterface(Object, Class). The
    743 former returns an interface implemented with the current Lisp package,
    744 the latter allows the programmer to pass an interface-implementation
    745 object which will in turn be passed to the jmake-proxy generic
    746 function.
     715This functionality is exposed by the class \code{AbclScriptEngine} via
     716the two methods \code{getInterface(Class)} and
     717\code{getInterface(Object, Class)}. The former returns an interface
     718implemented with the current Lisp package, the latter allows the
     719programmer to pass an interface-implementation object which will in turn
     720be passed to the \code{jmake-proxy} generic function.
    747721
    748722\chapter{Implementation Dependent Extensions}
     
    11031077
    11041078The \code{require} of the \code{asdf-install} symbol has the side
    1105 effect of pushing the directory ``~/.asdf-install-dir/systems/'' into
     1079effect of pushing the directory ``\~/.asdf-install-dir/systems/'' into
    11061080the value of the \textsc{ASDF} central registry in
    11071081\code{asdf:*central-registry*}, providing a convenient mechanism for
Note: See TracChangeset for help on using the changeset viewer.