Changeset 15067


Ignore:
Timestamp:
06/09/17 20:31:55 (6 months ago)
Author:
mevenson
Message:

First half of User Manual edits prompted by Phillip Marek's review

ABCL/DOCUMENTATION reformatting with the only intentional function
change being the introduction of the exported INDEX function to grind
the documentation from available runtime symbols. Something is still
funky about parameter lists for generic functions and macros.

Location:
trunk/abcl
Files:
7 edited

Legend:

Unmodified
Added
Removed
  • trunk/abcl/abcl.asd

    r15041 r15067  
    150150  :depends-on (swank)
    151151  :components
    152   ((:module grovel :pathname "doc/manual/" :serial t
    153             :components ((:file "package")
     152  ((:module package
     153            :pathname "doc/manual/" :components ((:file "package")))
     154   (:module grovel
     155            :depends-on (package)
     156            :pathname "doc/manual/"
     157            :components ((:file "index" :depends-on (grovel))
    154158                         (:file "grovel")))))
    155159
  • trunk/abcl/doc/manual/Makefile

    r15044 r15067  
    1111#ABCL   = abcl
    1212ABCL  = ../../abcl
    13 #ABCL = /Users/evenson/work/abcl-1.1.x/abcl
    1413
    15 # XXX TODO 1) use more compact iterated form, 2) pare down to using --noinit
     14# XXX TODO pare down to using --noinit
    1615grovel:
    1716  $(ABCL) --batch --noinform \
    1817  --eval '(require :abcl-contrib)' \
    19   --eval '(require :jss)' \
    20   --eval '(asdf:load-system :abcl/documentation)' \
    21   --eval '(in-package :abcl/documentation)' \
    22   --eval '(grovel-docstrings-as-tex :package :java)' \
    23   --eval '(grovel-docstrings-as-tex :package :extensions)' \
    24   --eval '(grovel-docstrings-as-tex :package :threads)' \
    25   --eval '(grovel-docstrings-as-tex :package :system)' \
    26   --eval '(grovel-docstrings-as-tex :package :jss)'
     18  --eval '(asdf:make :abcl/documentation)' \
     19  --eval '(abcl/documentation:index)'
    2720
    2821clean:
  • trunk/abcl/doc/manual/abcl.tex

    r15059 r15067  
    88\usepackage{hyperref} % Put this one last, it redefines lots of internals
    99
    10 
    1110\begin{document}
    1211\title{Armed Bear Common Lisp User Manual}
    13 \date{Version 1.5.0-rc-0\\
     12\date{Version 1.5.0-rc-1\\
    1413\smallskip
    1514June 2017}
     
    2827possible open access to the sources from with an JDK may both be built
    2928and run upon.  This requirement is no longer met by Java 5, so
    30 henceforth with the release of \textsc{ABCL} 1.5 ABCL will support
     29henceforth with the release of \textsc{ABCL} 1.5, we will support
    3130Java 6, Java 7 and Java 8 runtimes.
    3231
     
    4544
    4645\textsc{ABCL} 1.3 now implements an optimized implementation of the
    47 \code{org.armedbare.lisp.LispStack} abstraction thanks to Dmitry
     46\code{org.armedbear.lisp.LispStack} abstraction thanks to Dmitry
    4847Nadezhin which runs on ORCL JVMs from 1.[5-8] conformantly.
    4948
     
    6261\chapter{Introduction}
    6362
    64 Armed Bear Common Lisp (\textsc{ABCL}) is an implementation of Common
    65 Lisp that runs on the Java Virtual Machine (\textsc{JVM}).
    66 \textsc{ABCL} compiles Common Lisp to Java bytecode \footnote{The
    67   class file version is ``49.0''.}, with an efficiency that varies on
    68 the hosting JVM implementation.  \textsc{ABCL} supports Java 6, Java
    69 7, and Java 8 \textsc{JVM} implementations.
     63Armed Bear Common Lisp (\textsc{ABCL}) is an implementation of
     64\textsc{Common Lisp} that runs on the Java Virtual Machine
     65(\textsc{JVM}).  \textsc{ABCL} compiles \textsc{Common Lisp} to
     66\textsc{Java} bytecode\footnote{The class file version is ``49.0''.},
     67with an efficiency that varies on the hosting JVM implementation.
     68\textsc{ABCL} supports running on the Java 6, Java 7, and Java 8
     69\textsc{JVM} implementations.
    7070
    7171Armed Bear provides the following integration methods for interfacing
     
    8484\item \code{java:jnew-runtime-class} can inject fully synthetic Java
    8585  classes--and their objects-- into the current JVM process whose
    86   behavior is specified via closures expressed in Common Lisp.. \footnote{Parts of
    87     the current implementation are not fully finished, so the status
    88     of some interfaces here should be treated with skepticism if you
    89     run into problems.}
     86  behavior is specified via closures expressed in \textsc{Common
     87    Lisp}. \footnote{Parts of the current implementation are not fully
     88    finished, so the status of some interfaces here should be treated
     89    with skepticism if you run into problems.}
    9090
    9191\end{itemize}
     
    133133\subsection{Contemporary Common Lisp}
    134134In addition to \textsc{ANSI} conformance, \textsc{ABCL} strives to implement
    135 features expected of a contemporary Common Lisp, i.e. a Lisp of the
     135features expected of a contemporary \textsc{Common Lisp}, i.e. a Lisp of the
    136136post-2005 Renaissance.
    137137
     
    139139contemporary Common Lisp.
    140140\begin{itemize}
    141 \item An incomplete implementation of interactive debugging mechanisms,
    142   namely a no-op version of \code{STEP} \footnote{Somewhat surprisingly
    143     allowed by \textsc{ANSI}}, the inability to inspect local variables
    144   in a given call frame, and the inability to resume a halted
    145   computation at an arbitrarily selected call frame.
     141\item An incomplete implementation of interactive debugging
     142  mechanisms, namely a no-op version of \code{STEP}\footnote{Somewhat
     143    surprisingly allowed by \textsc{ANSI}}, the inability to inspect
     144  local variables in a given call frame, and the inability to resume a
     145  halted computation at an arbitrarily selected call frame.
    146146\item Incomplete streams abstraction, in that \textsc{ABCL} needs a
    147147  suitable abstraction between \textsc{ANSI} and \textsc{Gray streams}
    148148  with a runtime switch for the beyond conforming
    149   behavior\footnote{The streams could be optimized to the
     149  behavior\footnote{The streams could be optimized to the
    150150    \textsc{JVM} NIO \cite{nio} abstractions at great profit for
    151     binary byte-level manipulations.}
     151    binary byte-level manipulations.}.
    152152\item Incomplete documentation: source code is missing docstrings from
    153153  all exported symbols from the \code{EXTENSIONS}, \code{SYSTEM},
     
    161161
    162162\textsc{ABCL} is licensed under the terms of the \textsc{GPL} v2 of
    163 June 1991 with the ``classpath-exception'' (see the file
    164 \texttt{COPYING} in the source distribution \footnote{See
    165   \url{http://abcl.org/svn/trunk/tags/1.5.0/COPYING}} for
    166 the license, term 13 in the same file for the classpath exception).
    167 This license broadly means that you must distribute the sources to
    168 \textsc{ABCL}, including any changes you make, together with a program that
    169 includes \textsc{ABCL}, but that you are not required to distribute the sources
    170 of the whole program.  Submitting your changes upstream to the ABCL
     163June 1991 with an added ``classpath-exception'' clause (see the file
     164\texttt{COPYING} in the source distribution\footnote{See
     165  \url{http://abcl.org/svn/trunk/tags/1.5.0/COPYING}} for the license,
     166term 13 in the same file for the classpath exception).  This license
     167broadly means that you must distribute the sources to \textsc{ABCL},
     168including any changes you make, together with a program that includes
     169\textsc{ABCL}, but that you are not required to distribute the sources
     170of the whole program.  Submitting your changes upstream to the \textsc{ABCL}
    171171development team is actively encouraged and very much appreciated, of
    172172course.
     
    175175
    176176\begin{itemize}
    177 \item Philipp Marek \texttt{Thanks for the markup}
     177\item Philipp Marek \texttt{Thanks for the markup, and review of the Manual}
    178178\item Douglas Miles \texttt{Thanks for the whacky IKVM stuff and keeping the flame alive
    179179  in the dark years.}
     
    181181\item Olof-Joachim Frahm 
    182182\item piso
    183 \item and of course
    184 \emph{Peter Graves}
     183\item and of course \emph{Peter Graves}
    185184\end{itemize}
    186185
     
    276275When calling Java routines, some values will automatically be
    277276converted by the FFI\footnote{Foreign Function Interface, is the term
    278   of art for the part of a Lisp implementation which implements
     277  of art for the part of a \textsc{Lisp} implementation which implements
    279278  calling code written in other languages, typically normalized to the
    280   local C compiler calling conventions.}  from Lisp values to Java
     279  local C compiler calling conventions.}  from \textsc{Lisp} values to Java
    281280values. These conversions typically apply to strings, integers and
    282 floats. Other values need to be converted to their Java equivalents by
     281floats. Other values need to be converted to their \textsc{Java} equivalents by
    283282the programmer before calling the Java object method. Java values
    284 returned to Lisp are also generally converted back to their Lisp
     283returned to \textsc{Lisp} are also generally converted back to their Lisp
    285284counterparts. Some operators make an exception to this rule and do not
    286285perform any conversion; those are the ``raw'' counterparts of certain
     
    291290
    292291This subsection covers the low-level API available after evaluating
    293 \code{(require :java)}.  A higher level Java API, developed by Alan
     292\code{(require :java)}.  A higher level \textsc{Java} API, developed by Alan
    294293Ruttenberg, is available in the \code{contrib/} directory and described
    295294later in this document, see Section~\ref{section:jss} on page
     
    339338
    340339Dynamic dispatch is performed by using the Java reflection
    341 API \footnote{The Java reflection API is found in the
     340API\footnote{The Java reflection API is found in the
    342341  \code{java.lang.reflect} package}. Generally the dispatch works
    343342fine, but there are corner cases where the API does not correctly
     
    418417Like \code{JAVA:JCALL}, \code{JAVA:JSTATIC} supports dynamic dispatch by
    419418passing the name of the method as a string instead of passing a method reference.
    420 The parameter values should be values to pass in the function call instead of
     419The parameters should be values to pass in the function call instead of
    421420a specification of classes for each parameter.
    422421
     
    432431\subsubsection{Instantiating Java objects}
    433432
    434 Java objects can be instantiated (created) from Lisp by calling
     433\textsc{Java} objects can be instantiated (created) from \textsc{Lisp} by calling
    435434a constructor from the class of the object to be created. The
    436435\code{JAVA:JCONSTRUCTOR} primitive is used to acquire a constructor
    437 reference. It's arguments specify the types of arguments of the constructor
     436reference. Its arguments specify the types of arguments of the constructor
    438437method the same way as with \code{JAVA:JMETHOD}.
    439438
     
    455454\section{Java to Lisp}
    456455
    457 This section describes the various ways that one interacts with Lisp
    458 from Java code.  In order to access the Lisp world from Java, one needs
     456This section describes the various ways that one interacts with \textsc{Lisp}
     457from \textsc{Java} code.  In order to access the \textsc{Lisp} world from \textsc{Java}, one needs
    459458to be aware of a few things, the most important ones being listed below:
    460459
     
    474473\label{sec:calling-lisp-from-java}
    475474
    476 Note: the entire ABCL Lisp system resides in the
    477 \texttt{org.armedbear.lisp} package, but the following code snippets do
    478 not show the relevant import statements in the interest of brevity.  An
    479 example of the import statement would be
     475Note: the entire \textsc{ABCL} \textsc{Lisp} system implementation in
     476\textsc{Java} is resident in the \texttt{org.armedbear.lisp} package,
     477but the following code snippets do not show the relevant import
     478statements in the interest of brevity.  An example of the import
     479statement would be
    480480\begin{listing-java}
    481481  import org.armedbear.lisp.*;
    482482\end{listing-java}
    483 to potentially import all the JVM symbol from the `org.armedbear.lisp'
     483to potentially import all the JVM symbol from the \code{org.armedbear.lisp}
    484484namespace.
    485485
    486 There can only ever be a single Lisp interpreter per JVM instance.  A
     486There can only ever be a single Lisp interpreter per \textsc{JVM} instance.  A
    487487reference to this interpreter is obtained by calling the static method
    488488\code{Interpreter.createInstance()}.
     
    493493
    494494If this method has already been invoked in the lifetime of the current
    495 Java process it will return \texttt{null}, so if you are writing Java
    496 whose life-cycle is a bit out of your control (like in a Java servlet),
     495Java process it will return \texttt{null}, so if you are writing \textsc{Java}
     496whose life-cycle is a bit out of your control (like in a \textsc{Java} servlet),
    497497a safer invocation pattern might be:
    498498
     
    544544CL function \code{NULL} in the following way:
    545545
     546
    546547\begin{listing-java}
    547548  boolean nullp(LispObject object) {
    548549    LispObject result = Primitives.NULL.execute(object);
    549     if (result == NIL) { // the symbol 'NIL' is explicitly named in the Java
    550                          // namespace at ``Symbol.NIL''
    551                          // but is always present in the
    552                          // local namespace in its unadorned form for
    553                          // the convenience of the User.
     550    if (result == NIL) {
    554551      return false;
    555552    }
     
    557554 }
    558555\end{listing-java}
     556
     557Note, that the symbol \code{nil} is explicitly named in the
     558\textsc{Java} namespace as \code{Symbol.NIL} but is always present in
     559the local namespace in its unadorned form for the convenience of the
     560User.
    559561
    560562\subsubsection{Multiple Values}
     
    749751\subsection{Compilation}
    750752
    751 AbclScriptEngine implements the \code{javax.script.Compilable}
     753\code{AbclScriptEngine} implements the \code{javax.script.Compilable}
    752754interface. Currently it only supports compilation using temporary
    753755files. Compiled code, returned as an instance of
    754 \texttt{javax.script.CompiledScript}, is read, compiled and executed by
    755 default in the \texttt{ABCL-SCRIPT-USER} package, just like evaluated
    756 code.  In contrast to evaluated code, though, due to the way the ABCL
    757 compiler works, compiled code contains no reference to top-level
    758 self-evaluating objects (like numbers or strings). Thus, when evaluated,
    759 a piece of compiled code will return the value of the last
    760 non-self-evaluating form: for example the code ``\code{(do-something)
    761   42}'' will return 42 when interpreted, but will return the result of
    762 (do-something) when compiled and later evaluated. To ensure consistency
    763 of behavior between interpreted and compiled code, make sure the last
    764 form is always a compound form - at least \code{(identity
    765 some-literal-object)}. Note that this issue should not matter in real
    766 code, where it is unlikely a top-level self-evaluating form will appear
    767 as the last form in a file (in fact, the Common Lisp load function
    768 always returns \texttt{T} upon success; with JSR-223 this policy has been changed
    769 to make evaluation of small code snippets work as intended).
     756\texttt{javax.script.CompiledScript}, is read, compiled and executed
     757by default in the \code{abcl-script-user} package, just like evaluated
     758code.  In contrast to evaluated code, though, due to the way the
     759\textsc{ABCL} compiler works, compiled code contains no reference to
     760top-level self-evaluating objects (like numbers or strings). Thus,
     761when evaluated, a piece of compiled code will return the value of the
     762last non-self-evaluating form: for example the code
     763``\code{(do-something) 42}'' will return 42 when interpreted, but will
     764return the result of (do-something) when compiled and later
     765evaluated. To ensure consistency of behavior between interpreted and
     766compiled code, make sure the last form is always a compound form - at
     767least \code{(identity some-literal-object)}. Note that this issue
     768should not matter in real code, where it is unlikely that a top-level
     769self-evaluating form will appear as the last form in a file (in fact,
     770the Common Lisp load function always returns \code{t} upon success;
     771with \textsc{JSR-223} this policy has been changed to make evaluation
     772of small code snippets work as intended).
    770773
    771774\subsection{Invocation of functions and methods}
     
    805808
    806809\begin{itemize}
    807 \item a single Lisp function which upon invocation of any method in
    808   the interface will be passed the method name, the Lisp-this object,
     810\item a single Lisp function which, upon invocation of any method in
     811  the interface, will be passed the method name, the Lisp-this object,
    809812  and all the parameters. Useful for interfaces with a single method,
    810813  or to implement custom interface-implementation strategies.
     
    827830\subsection{Implementation of Java classes in Lisp}
    828831
    829 See \code{JAVA:JNEW-RUNTIME-CLASS} on \ref{JAVA:JNEW-RUNTIME-CLASS}.
     832See \code{JAVA:JNEW-RUNTIME-CLASS} in \ref{JAVA:JNEW-RUNTIME-CLASS}.
    830833
    831834
    832835\chapter{Implementation Dependent Extensions}
    833836
    834 As outlined by the CLHS ANSI conformance guidelines, we document the
    835 extensions to the Armed Bear Lisp implementation made accessible to
    836 the user by virtue of being an exported symbol in the JAVA, THREADS,
    837 or EXTENSIONS packages.
     837As outlined by the \textsc{CLHS} \textsc{ANSI} conformance guidelines,
     838we document the extensions to the Armed Bear Common Lisp implementation made
     839accessible to the user by virtue of being an exported symbol in the
     840\code{java}, \code{threads}, or \code{extensions} packages.
    838841
    839842\section{JAVA}
     
    843846The \code{JAVA:ADD-TO-CLASSPATH} generic functions allows one to add the
    844847specified pathname or list of pathnames to the current classpath
    845 used by ABCL, allowing the dynamic loading of \textsc{JVM} objects:
     848used by \textsc{ABCL}, allowing the dynamic loading of \textsc{JVM} objects:
    846849
    847850\begin{listing-lisp}
     
    872875\section{EXTENSIONS}
    873876
    874 The symbols in the EXTENSIONS package (nicknamed ``EXT'') constitutes
    875 extensions to the \textsc{ANSI} standard that are potentially useful to the
    876 user.  They include functions for manipulating network sockets,
    877 running external programs, registering object finalizers, constructing
    878 reference weakly held by the garbage collector and others.
     877The symbols in the \code{extensions} package (often referenced by its
     878shorter nickname \code{ext}) constitutes extensions to the
     879\textsc{ANSI} standard that are potentially useful to the user.  They
     880include functions for manipulating network sockets, running external
     881programs, registering object finalizers, constructing reference weakly
     882held by the garbage collector and others.
    879883
    880884See \cite{RHODES2007} for a generic function interface to the native
     
    886890\chapter{Beyond ANSI}
    887891
    888 Naturally, in striving to be a useful contemporary Common Lisp
    889 implementation, ABCL endeavors to include extensions beyond the ANSI
     892Naturally, in striving to be a useful contemporary \textsc{Common Lisp}
     893implementation, \textsc{ABCL} endeavors to include extensions beyond the ANSI
    890894specification which are either widely adopted or are especially useful
    891895in working with the hosting \textsc{JVM}.
     
    13111315        on the JVM.
    13121316      \item \code{jss} Introduces dynamic inspection of present
    1313         symbols via the \code{SHARPSIGN-DOUBLE-QUOTE} macros as Java Syntax
     1317        symbols via the \code{SHARPSIGN-QUOTATION\_MARK} macros as Java Syntax
    13141318        Sucks
    13151319      \item \code{abcl-introspect} Provides a framework for
  • trunk/abcl/doc/manual/grovel.lisp

    r14765 r15067  
    22
    33(defun grovel-docstrings-as-tex (&key
    4                                    (package (find-package :java))
    5                                    (directory (asdf:component-pathname (asdf:find-component :abcl/documentation 'grovel))))
     4                                   (package
     5                                    (find-package :java))
     6                                   (directory
     7                                    (asdf:component-pathname
     8                                     (asdf:find-component :abcl/documentation 'grovel))))
    69  "Transform exported symbols documentation in PACKAGE to DIRECTORY."
    7   (let ((output-file (merge-pathnames (format nil "~A.tex" (string-downcase (package-name package))) directory))
     10  (let ((output-file (merge-pathnames
     11                      (format nil "~A.tex" (string-downcase (package-name package)))
     12                      directory))
    813        (symbols (loop :for symbol :being :each :external-symbol :of package :collecting symbol)))
    914    (with-open-file (stream output-file :direction :output)
    1015      (format t "Writing output to '~A'.~%" output-file)
    11       (loop :for symbol :in (sort symbols (lambda (a b) (string-lessp (symbol-name a) (symbol-name b))))
     16      (loop :for symbol :in (sort symbols
     17                                  (lambda (a b)
     18                                    (string-lessp (symbol-name a) (symbol-name b))))
    1219         :doing (let ((documentation (symbol-as-tex symbol)))
    1320                  (when documentation
  • trunk/abcl/doc/manual/index.lisp

    r13615 r15067  
    1 ;;; bootstrap documentation rendering
     1(in-package abcl/documentation)
    22
    3 #+elisp
     3#+elisp ;; huh?
    44(slime-apropos-package "JAVA")
     5
     6(defun index ()
     7  "Regenerate TeX markup from symbol introspection."
     8  (dolist (package '(:extensions
     9                     :system
     10                     :threads
     11                     :mop
     12                     :java
     13                     :jss ))
     14    (grovel-docstrings-as-tex :package package)))
     15
  • trunk/abcl/doc/manual/package.lisp

    r14764 r15067  
    1 (defpackage #:abcl/documentation
     1(in-package :cl-user)
     2
     3(defpackage abcl/documentation
    24  (:use :cl)
    3   (:export #:grovel-docstrings-as-tex))
     5  (:export
     6   #:index
     7   #:grovel-docstrings-as-tex))
    48
  • trunk/abcl/src/org/armedbear/lisp/Java.java

    r14918 r15067  
    657657    private static final Primitive JARRAY_REF = new pf_jarray_ref();
    658658    @DocString(name="jarray-ref", args="java-array &rest indices",
    659     doc="Dereferences the Java array JAVA-ARRAY using the given INDICIES, " +
     659    doc="Dereferences the Java array JAVA-ARRAY using the given INDICES, " +
    660660        "coercing the result into a Lisp object, if possible.")
    661661    private static final class pf_jarray_ref extends Primitive
     
    675675    private static final Primitive JARRAY_REF_RAW = new pf_jarray_ref_raw();
    676676    @DocString(name="jarray-ref-raw", args="java-array &rest indices",
    677     doc="Dereference the Java array JAVA-ARRAY using the given INDICIES. " +
     677    doc="Dereference the Java array JAVA-ARRAY using the given INDICES. " +
    678678        "Does not attempt to coerce the result into a Lisp object.")
    679679    private static final class pf_jarray_ref_raw extends Primitive
     
    693693    private static final Primitive JARRAY_SET = new pf_jarray_set();
    694694    @DocString(name="jarray-set", args="java-array new-value &rest indices",
    695     doc="Stores NEW-VALUE at the given index in JAVA-ARRAY.")
     695    doc="Stores NEW-VALUE at the given INDICES in JAVA-ARRAY.")
    696696    private static final class pf_jarray_set extends Primitive
    697697    {
Note: See TracChangeset for help on using the changeset viewer.