Changeset 13438


Ignore:
Timestamp:
08/05/11 09:30:50 (10 years ago)
Author:
Mark Evenson
Message:

Manual renders to pdf via pdflatex.

Location:
trunk/abcl/doc/manual
Files:
2 edited
1 moved

Legend:

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

    r13437 r13438  
    44% leaving the manual itself as much as a pure content to be
    55% comfortably read and modified with a text editor.
    6 
    7 \documentclass[10pt]{article}
    86
    97\usepackage{color,hyperref}
     
    2220
    2321
    24 \newenvironment{xx}[1]%
    25                {\begin{lstlisting} }%
    26                {\end{lstlisting}}
     22\lstnewenvironment{listing-java}
     23 {\lstset{language=Java}}
     24 {}
     25
     26
     27\lstnewenvironment{listing-lisp}
     28 {\lstset{language=Lisp}}
     29 {}
    2730
    2831\usepackage{verbatim}
    2932
     33\ProvidesPackage{abcl}
  • trunk/abcl/doc/manual/abcl.tex

    r13437 r13438  
     1% -*- mode: latex; -*-
    12% http://en.wikibooks.org/wiki/LaTeX/
    2 \include{index}
     3\documentclass[10pt]{book}
     4\usepackage{abcl}
    35
    46\begin{document}
    57\title{A Manual for Armed Bear Common Lisp}
    68\date{August 4, 2011}
    7 \author{Mark Evenson, Erik Huelsmann, Alessio Stallo, Ville Voutilainen}
    8 
    9 \section{Introduction}
     9\author{Mark~Evenson, Erik~Huelsmann, Alessio~Stallo, Ville~Voutilainen}
     10
     11\maketitle
     12
     13\chapter{Introduction}
    1014
    1115Armed Bear is a mostly conforming implementation of the ANSI Common
     
    1620This manual corresponds to abcl-0.27.0, as yet unreleased.
    1721
    18 
    19 \section{Interaction with host JVM}
     22\chapter{Conformance}
     23
     24
     25\section{ANSI Common Lisp}
     26ABCL is currently a non-conforming ANSI Common Lisp implementation due
     27to the following (known) issues:
     28
     29\begin{itemize}
     30  \item Lack of long form of DEFINE-METHOD-COMBINATION
     31  \item Missing statement of conformance in accompanying documentation
     32\end{itemize}
     33
     34ABCL aims to be be a fully conforming ANSI Common Lisp
     35implementation.  Any other behavior should be reported as a bug.
     36
     37\section{Contemporary Common Lisp}
     38In addition to ANSI conformance, ABCL strives to implement features
     39expected of a contemporary Common Lisp.
     40\begin{itemize}
     41  \item Incomplete MOP
     42    % N.B.
     43    % TODO go through AMOP with symbols, starting by looking for
     44    % matching function signature.
     45    % XXX is this really blocking ANSI conformance?  Answer: we have
     46    % to start with such a ``census'' to determine what we have.
     47  \item Incomplete Gray Streams
     48\end{itemize}
     49
     50\chapter{Interaction with host JVM}
    2051
    2152% describe calling Java from Lisp, and calling Lisp from Java,
     
    2455% that are more comforable with Lisp
    2556
    26 \subsection{Lisp to Java}
     57\section{Lisp to Java}
    2758
    2859ABCL offers a number of mechanisms to manipulate Java libraries from
     
    4374\end{itemize}
    4475
    45 \subsection{Lisp from Java}
     76\section{Lisp from Java}
    4677
    4778Manipulation of the Lisp API is currently lacking a stable interface,
     
    6091\end{itemize}
    6192
    62 \subsubsection{Lisp FFI}
     93\subsection{Lisp FFI}
    6394
    6495FFI stands for "Foreign Function Interface" which is the phase which
     
    69100needs to be "Interfaced".
    70101
    71 \subsubsection{Calling Lisp from Java}
     102\subsection{Calling Lisp from Java}
    72103
    73104Note: As the entire ABCL Lisp system resides in the org.armedbear.lisp
     
    76107statement would be
    77108
    78 \lstset{language=Java}
    79 \begin{lstlisting}
     109\begin{listing-java}
    80110  import org.armedbear.lisp.*;
    81 \end{lstliting}
     111\end{listing-java}
    82112
    83113to potentially import all the JVM symbol from the `org.armedbear.lisp'
     
    87117started by calling the static method `Interpreter.createInstance()`.
    88118
    89 \begin{code}[java]
     119\begin{listing-java}
    90120  Interpreter interpreter = Interpreter.createInstance();
    91 \end{code}
     121\end{listing-java}
    92122
    93123If this method has already been invoked in the lifetime of the current
     
    103133\end{code}
    104134
    105 
    106135The Lisp \code{eval} primitive may be simply passed strings for evaluation,
    107136as follows
    108137
    109 \begin{code}[java]
     138\begin{listing-java}
    110139  String line = "(load \"file.lisp\")";
    111140  LispObject result = interpreter.eval(line);
    112 \end{code}
     141\end{listing-java}
    113142
    114143Notice that all possible return values from an arbitrary Lisp
     
    119148(c.f. [Introspecting a LispObject])
    120149
    121 Using ``EVAL'' involves the Lisp interpreter.  Lisp functions may be
    122 directly invoked by Java method calls as follows.  One simply locates
    123 the package containing the symbol, then obtains a reference to the
    124 symbol, and then invokes the `execute()` method with the desired
    125 parameters.
    126 
    127 \begin{code}[java]
     150Using \code{eval} involves the Lisp interpreter.  Lisp functions may
     151be directly invoked by Java method calls as follows.  One simply
     152locates the package containing the symbol, then obtains a reference to
     153the symbol, and then invokes the \code{execute()} method with the
     154desired parameters.
     155
     156\begin{listing-java}
    128157    interpreter.eval("(defun foo (msg) (format nil \"You told me '~A'~%\" msg))");
    129158    Package pkg = Packages.findPackage("CL-USER");
     
    134163    // How to get the "naked string value"?
    135164    System.out.println("The result was " + result.writeToString());
    136 \end{code}
     165\end{listing-java}
    137166
    138167If one is calling an primitive function in the CL package the syntax
     
    141170tell if a `LispObject` contains a reference to a symbol.
    142171
    143 \begin{code}[java]
     172\begin{listing-java}
    144173    boolean nullp(LispObject object) {
    145174      LispObject result = Primitives.NULL.execute(object);
     
    149178      return true;
    150179   }
    151 \end{code}
    152 
    153 \paragraph{Introspecting a LispObject}
     180\end{listing-java}
     181
     182\subsubsection{Introspecting a LispObject}
    154183\label{topic:Introspecting a LispObject}
    155184
     
    158187into semantics that Java can meaniningfully deal with.
    159188
    160 \paragraph{LispObject as \code{boolean}}
     189\subsubsection{LispObject as \code{boolean}}
    161190
    162191If the LispObject a generalized boolean values, one can use
    163192\code{getBooleanValue()} to convert to Java:
    164193
    165 \begin{code}[java]
     194\begin{listing-java}
    166195     LispObject object = Symbol.NIL;
    167196     boolean javaValue = object.getBooleanValue();
    168 \end{code}
     197\end{listing-java}
    169198
    170199Although since in Lisp, any value other than NIL means "true", the
    171200use of Java equality it quite a bit easier and more optimal:
    172201
    173 \begin{code}[java]
     202\begin{listing-java}
    174203    boolean javaValue = (object != Symbol.NIL);
    175 \end{code}
     204\end{listing-java}
    176205
    177206\paragraph{LispObject is a list}
     
    181210iteration.
    182211
    183 \begin{code}[java]
     212\begin{listing-java}
    184213    LispObject result = interpreter.eval("'(1 2 4 5)");
    185214    if (result instanceof Cons) {
     
    187216      ...
    188217    }
    189 \end{code}
     218\end{listing-java}
    190219   
    191220A more Lispy way to iterated down a list is to use the `cdr()` access
    192221function just as like one would traverse a list in Lisp:;
    193222
    194 \begin{code}[java]
     223\begin{listing-java}
    195224    LispObject result = interpreter.eval("'(1 2 4 5)");
    196225    while (result != Symbol.NIL) {
     
    198227      result = result.cdr();
    199228    }
    200 \end{code}
    201 
    202 
    203 \subsection{JAVA}
     229\end{listing-java}
     230
     231
     232\section{Java}
    204233
    205234% include autogen docs for the JAVA package.
    206 
    207 \section{ANSI Common Lisp Conformance}
    208 
    209 ABCL is currently a non-conforming ANSI Common Lisp implementation due
    210 to the following (known) issues:
    211 
    212 \begin{itemize}
    213   \item Lack of long form of DEFINE-METHOD-COMBINATION
    214   \item Missing statement of conformance in accompanying documentation
    215   \item Incomplete MOP
    216     % TODO go through AMOP with symbols, starting by looking for
    217     % matching function signature.
    218     % XXX is this really blocking ANSI conformance?  Answer: we have
    219     % to start with such a ``census'' to determine what we have.
    220 \end{itemize}
    221 
    222 ABCL aims to be be a fully conforming ANSI Common Lisp
    223 implementation.  Any other behavior should be reported as a bug.
     235\include{java}
     236
     237\section{Multithreading}
     238
     239% TODO document the THREADS package.
     240\include{threads}
    224241
    225242\section{Extensions}
     
    233250\include{extensions}
    234251
    235 \subsection{Beyond ANSI}
     252\chapter{Beyond ANSI}
    236253
    237254Naturally, in striving to be a useful contemporary Common Lisp
     
    240257in working with the hosting JVM.
    241258
    242 \subsubsection{Extensions to CLOS}
     259\section{Extensions to CLOS}
    243260
    244261There is an additional syntax for specializing the parameter of a
     
    251268object
    252269
    253 \begin{code}[lisp]
    254 (defmethod print-object ((coll (java:jclass "java.util.Collection")) stream)
    255 \ldots
    256 \end{code}
     270\begin{listing-lisp}
     271(defmethod print-object ((coll (java:jclass "java.util.Collection"))
     272                         stream)
     273  ;;; ...
     274)
     275\end{listing-lisp}
    257276
    258277If the class had been loaded via a classloader other than the original
     
    260279classloader as an optional third argument.
    261280
    262 \begin{code}[lisp]
    263 (defmethod print-object ((device-id (java:jclass "dto.nbi.service.hdm.alcatel.com.nNBIDeviceID"
    264                                     (\#"getBaseLoader" cl-user::*classpath-manager*)))
    265 \ldots
    266 \end{code}
    267 
    268 \subsubsection{Extensions to the Reader}
     281\begin{listing-lisp}
     282
     283(defparameter *other-classloader*
     284  (jcall "getBaseLoader" cl-user::*classpath-manager*))
     285 
     286(defmethod print-object ((device-id (java:jclass "dto.nbi.service.hdm.alcatel.com.NBIDeviceID" *other-classloader*))
     287                         stream)
     288  ;;; ...
     289)
     290\end{listing-lisp}
     291
     292\section{Extensions to the Reader}
    269293
    270294We implement a special hexadecimal escape sequence for specifying
     
    279303code is greater than 0x00ff.
    280304
    281 \section{Multithreading}
    282 
    283 % TODO document the THREADS package.
    284 \include{threads}
    285 
    286 \section{History}
     305\chapter{History}
    287306
    288307ABCL was originally the extension language for the J editor, which was
  • trunk/abcl/doc/manual/java.tex

    r13437 r13438  
    11\begin{verbatim}
     2
    23%JGET-PROPERTY-VALUE
    34  Function: Gets a JavaBeans property on JAVA-OBJECT.
     5
    46%JSET-PROPERTY-VALUE
    57  Function: Sets a JavaBean property on JAVA-OBJECT.
    6 *JAVA-OBJECT-TO-STRING-LENGTH*
    7   Variable: Length to truncate toString() PRINT-OBJECT output for an otherwise unspecialized JAVA-OBJECT.  Can be set to NIL to indicate no limit.
     8
     9*JAVA-OBJECT-TO-STRING-LENGTH*
     10 Variable: Length to truncate toString()
     11 PRINT-OBJECT output for an otherwise unspecialized JAVA-OBJECT.  Can
     12 be set to NIL to indicate no limit.
     13
    814ADD-TO-CLASSPATH
    915  Function: (not documented)
     16
    1017CHAIN
    1118  Function: (not documented)
     19
    1220DESCRIBE-JAVA-OBJECT
    1321  Function: (not documented)
     22
    1423DUMP-CLASSPATH
    1524  Function: (not documented)
     25
    1626ENSURE-JAVA-CLASS
    1727  Function: (not documented)
     28
    1829ENSURE-JAVA-OBJECT
    1930  Function: Ensures OBJ is wrapped in a JAVA-OBJECT, wrapping it if necessary.
     31
    2032GET-DEFAULT-CLASSLOADER
    2133  Function: (not documented)
     34
    2235JARRAY-COMPONENT-TYPE
    2336  Function: Returns the component type of the array type ATYPE
     37
    2438JARRAY-LENGTH
    2539  Function: (not documented)
     40
    2641JARRAY-REF
    27   Function: Dereferences the Java array JAVA-ARRAY using the given INDICIES, coercing the result into a Lisp object, if possible.
     42 Function: Dereferences the Java array JAVA-ARRAY using the given
     43 INDICIES, coercing the result into a Lisp object, if possible.
     44
    2845JARRAY-REF-RAW
    29   Function: Dereference the Java array JAVA-ARRAY using the given INDICIES. Does not attempt to coerce the result into a Lisp object.
     46 Function: Dereference the Java array JAVA-ARRAY using the given
     47 INDICIES. Does not attempt to coerce the result into a Lisp object.
     48
    3049JARRAY-SET
    3150  Function: Stores NEW-VALUE at the given index in JAVA-ARRAY.
     51
    3252JAVA-CLASS
    3353  Class: (not documented)
     54
    3455JAVA-EXCEPTION
    3556  Class: (not documented)
     57
    3658JAVA-EXCEPTION-CAUSE
    3759  Function: Returns the cause of JAVA-EXCEPTION. (The cause is the Java Throwable
     60
    3861JAVA-OBJECT
    3962  Class: (not documented)
     63
    4064JAVA-OBJECT-P
    4165  Function: Returns T if OBJECT is a JAVA-OBJECT.
     66
    4267JCALL
    43   Function: Invokes the Java method METHOD-REF on INSTANCE with arguments ARGS, coercing the result into a Lisp object, if possible.
     68 Function: Invokes the Java method METHOD-REF on INSTANCE with
     69 arguments ARGS, coercing the result into a Lisp object, if possible.
     70
    4471JCALL-RAW
    45   Function: Invokes the Java method METHOD-REF on INSTANCE with arguments ARGS. Does not attempt to coerce the result into a Lisp object.
     72 Function: Invokes the Java method METHOD-REF on INSTANCE with
     73 arguments ARGS. Does not attempt to coerce the result into a Lisp
     74 object.
     75
    4676JCLASS
    47   Function: Returns a reference to the Java class designated by NAME-OR-CLASS-REF. If the CLASS-LOADER parameter is passed, the class is resolved with respect to the given ClassLoader.
     77 Function: Returns a reference to the Java class designated by
     78 NAME-OR-CLASS-REF. If the CLASS-LOADER parameter is passed, the class
     79 is resolved with respect to the given ClassLoader.
     80
    4881JCLASS-ARRAY-P
    4982  Function: Returns T if CLASS is an array class
     83
    5084JCLASS-CONSTRUCTORS
    5185  Function: Returns a vector of constructors for CLASS
     86
    5287JCLASS-FIELD
    5388  Function: Returns the field named FIELD-NAME of CLASS
     89
    5490JCLASS-FIELDS
    55   Function: Returns a vector of all (or just the declared/public, if DECLARED/PUBLIC is true) fields of CLASS
     91  Function: Returns a vector of all (or just the declared/public, if
     92  DECLARED/PUBLIC is true) fields of CLASS
     93
    5694JCLASS-INTERFACE-P
    5795  Function: Returns T if CLASS is an interface
     96
    5897JCLASS-INTERFACES
    5998  Function: Returns the vector of interfaces of CLASS
     99
    60100JCLASS-METHODS
    61   Function: Return a vector of all (or just the declared/public, if DECLARED/PUBLIC is true) methods of CLASS
     101  Function: Return a vector of all (or just the declared/public, if
     102 DECLARED/PUBLIC is true) methods of CLASS
     103
    62104JCLASS-NAME
    63105  Function: When called with one argument, returns the name of the Java class
     106
    64107JCLASS-OF
    65108  Function: (not documented)
     109
    66110JCLASS-SUPERCLASS
    67111  Function: Returns the superclass of CLASS, or NIL if it hasn't got one
     112
    68113JCLASS-SUPERCLASS-P
    69114  Function: Returns T if CLASS-1 is a superclass or interface of CLASS-2
     115
    70116JCOERCE
    71   Function: Attempts to coerce OBJECT into a JavaObject of class INTENDED-CLASS.  Raises a TYPE-ERROR if no conversion is possible.
     117  Function: Attempts to coerce OBJECT into a JavaObject of class
     118 INTENDED-CLASS.  Raises a TYPE-ERROR if no conversion is possible.
     119
    72120JCONSTRUCTOR
    73   Function: Returns a reference to the Java constructor of CLASS-REF with the given PARAMETER-CLASS-REFS.
     121  Function: Returns a reference to the Java constructor of CLASS-REF
     122  with the given PARAMETER-CLASS-REFS.
     123
    74124JCONSTRUCTOR-PARAMS
    75125  Function: Returns a vector of parameter types (Java classes) for CONSTRUCTOR
     126
    76127JEQUAL
    77128  Function: Compares obj1 with obj2 using java.lang.Object.equals()
     129
    78130JFIELD
    79131  Function: Retrieves or modifies a field in a Java class or instance.
     132
    80133JFIELD-NAME
    81134  Function: Returns the name of FIELD as a Lisp string
     135
    82136JFIELD-RAW
    83137  Function: Retrieves or modifies a field in a Java class or instance. Does not
     138
    84139JFIELD-TYPE
    85140  Function: Returns the type (Java class) of FIELD
     141
    86142JINSTANCE-OF-P
    87143  Function: OBJ is an instance of CLASS (or one of its subclasses)
     144
    88145JINTERFACE-IMPLEMENTATION
    89146  Function: Creates and returns an implementation of a Java interface with
     147
    90148JMAKE-INVOCATION-HANDLER
    91149  Function: (not documented)
     150
    92151JMAKE-PROXY
    93152  Function: (not documented)
     153
    94154JMEMBER-PROTECTED-P
    95155  Function: MEMBER is a protected member of its declaring class
     156
    96157JMEMBER-PUBLIC-P
    97158  Function: MEMBER is a public member of its declaring class
     159
    98160JMEMBER-STATIC-P
    99161  Function: MEMBER is a static member of its declaring class
     162
    100163JMETHOD
    101   Function: Returns a reference to the Java method METHOD-NAME of CLASS-REF with the given PARAMETER-CLASS-REFS.
     164  Function: Returns a reference to the Java method METHOD-NAME of
     165  CLASS-REF with the given PARAMETER-CLASS-REFS.
     166
    102167JMETHOD-LET
    103168  Function: (not documented)
     169
    104170JMETHOD-NAME
    105171  Function: Returns the name of METHOD as a Lisp string
     172
    106173JMETHOD-PARAMS
    107174  Function: Returns a vector of parameter types (Java classes) for METHOD
     175
    108176JMETHOD-RETURN-TYPE
    109177  Function: Returns the result type (Java class) of the METHOD
     178
    110179JNEW
    111180  Function: Invokes the Java constructor CONSTRUCTOR with the arguments ARGS.
     181
    112182JNEW-ARRAY
    113183  Function: Creates a new Java array of type ELEMENT-TYPE, with the given DIMENSIONS.
     184
    114185JNEW-ARRAY-FROM-ARRAY
    115186  Function: Returns a new Java array with base type ELEMENT-TYPE (a string or a class-ref)
     187
    116188JNEW-ARRAY-FROM-LIST
    117189  Function: (not documented)
     190
    118191JNEW-RUNTIME-CLASS
    119192  Function: (not documented)
     193
    120194JNULL-REF-P
    121195  Function: Returns a non-NIL value when the JAVA-OBJECT `object` is `null`,
     196
    122197JOBJECT-CLASS
    123198  Function: Returns the Java class that OBJ belongs to
     199
    124200JOBJECT-LISP-VALUE
    125201  Function: Attempts to coerce JAVA-OBJECT into a Lisp object.
     202
    126203JPROPERTY-VALUE
    127204  Function: (not documented)
     205
    128206JREDEFINE-METHOD
    129207  Function: (not documented)
     208
    130209JREGISTER-HANDLER
    131210  Function: (not documented)
     211
    132212JRESOLVE-METHOD
    133   Function: Finds the most specific Java method METHOD-NAME on INSTANCE applicable to arguments ARGS. Returns NIL if no suitable method is found. The algorithm used for resolution is the same used by JCALL when it is called with a string as the first parameter (METHOD-REF).
     213  Function: Finds the most specific Java method METHOD-NAME on
     214  INSTANCE applicable to arguments ARGS. Returns NIL if no suitable
     215  method is found. The algorithm used for resolution is the same used
     216  by JCALL when it is called with a string as the first parameter
     217 (METHOD-REF).
     218
    134219JRUN-EXCEPTION-PROTECTED
    135   Function: Invokes the function CLOSURE and returns the result.  Signals an error if stack or heap exhaustion occurs.
     220  Function: Invokes the function CLOSURE and returns the result.
     221  Signals an error if stack or heap exhaustion occurs.
     222
    136223JRUNTIME-CLASS-EXISTS-P
    137224  Function: (not documented)
     225
    138226JSTATIC
    139227  Function: Invokes the static method METHOD on class CLASS with ARGS.
     228
    140229JSTATIC-RAW
    141   Function: Invokes the static method METHOD on class CLASS with ARGS. Does not attempt to coerce the arguments or result into a Lisp object.
     230  Function: Invokes the static method METHOD on class CLASS with
     231  ARGS. Does not attempt to coerce the arguments or result into a Lisp
     232  object.
     233
    142234MAKE-CLASSLOADER
    143235  Function: (not documented)
     236
    144237MAKE-IMMEDIATE-OBJECT
    145238  Function: Attempts to coerce a given Lisp object into a java-object of the
     239
    146240REGISTER-JAVA-EXCEPTION
    147   Function: Registers the Java Throwable named by the symbol EXCEPTION-NAME as the condition designated by CONDITION-SYMBOL.  Returns T if successful, NIL if not.
     241  Function: Registers the Java Throwable named by the symbol
     242  EXCEPTION-NAME as the condition designated by CONDITION-SYMBOL.
     243  Returns T if successful, NIL if not.
     244
    148245UNREGISTER-JAVA-EXCEPTION
    149246  Function: Unregisters the Java Throwable EXCEPTION-NAME previously registered by REGISTER-JAVA-EXCEPTION.
     247
    150248\end{verbatim}
Note: See TracChangeset for help on using the changeset viewer.