Changeset 13854


Ignore:
Timestamp:
02/05/12 09:21:58 (11 years ago)
Author:
Mark Evenson
Message:

manual: extend content in the Beyond ANSI section.

Describe CL:REQUIRE overloading.

Describe the values that the Pathname extensions stores in the
Pathname object.

Add references to ASDF and RDF3986.

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

Legend:

Unmodified
Added
Removed

  • trunk/abcl/doc/manual/abcl.bib

    r13853 r13854  
    11@Misc{maso2000,
    2   author =    {Brian Maso},
     2  author =    {Maso, Brian},
    33  title =     {A New Era for {Java} Protocol Handlers},
    44  howpublished = {\url{http://java.sun.com/developer/onlineTraining/protocolhandlers/}},
    … …  
    88
    99@Misc{quicklisp,
    10   author =       {Zach Beane},
     10  author =       {Beane, Zach},
    1111  title =        {Quicklisp},
    1212  howpublished = {\url{http://www.quicklisp.org/}},
    1313  note =         {Last accessed Jan 25, 2012}}
     14
     15
     16@Misc{asdf,
     17  author =       {Rideau, Fran\c{c}ois-Ren\'{e} and  Barlow, Daniel and Rhodes, Christopher and King, Garry},
     18  title =        {ASDF},
     19  howpublished = {\url{http://common-lisp.net/project/asdf/}},
     20  note =         {Last accessed Feb 5, 2012}}
     21
     22@Misc{rfc3986,
     23  author =       {Berners-Lee, Tim and Fielding, Roy and Masinter, Larry},
     24  title =        {RFC 3986:  URI Generic Syntax},
     25  year =         {2005},
     26  howpublished = {\url{http://www.ietf.org/rfc/rfc3986.txt}},
     27  note =         {Last accessed Feb 5, 2012}}
    1428
    1529@inproceedings{Rhodes2007,

  • trunk/abcl/doc/manual/abcl.tex

    r13853 r13854  
    1111\date{Version 1.1.0-dev\\
    1212\smallskip
    13 January 25, 2012}
     13Feburary 5, 2012}
    1414\author{Mark Evenson \and Erik H\"{u}lsmann \and Rudolf Schlatte \and
    1515  Alessio Stalla \and Ville Voutilainen}
    … …  
    115115
    116116\textsc{ABCL} is packaged as a single jar file usually named either
    117 \texttt{abcl.jar} or possibly something like \texttt{abcl-1.0.1.jar} if
     117\texttt{abcl.jar} or possibly something like \texttt{abcl-1.1.0.jar} if
    118118using a versioned package on the local filesystem from your system
    119119vendor.  This jar file can be executed from the command line to obtain a
    … …  
    759759
    760760The symbols in the EXTENSIONS package (nicknamed ``EXT'') constitutes
    761 extensions to the ANSI standard that are potentially useful to the
     761extensions to the \textsc{ANSI} standard that are potentially useful to the
    762762user.  They include functions for manipulating network sockets,
    763763running external programs, registering object finalizers, constructing
    … …  
    765765
    766766See \cite{RHODES2007} for a generic function interface to the native
    767 JVM contract for \code{java.util.List}.
     767\textsc{JVM} contract for \code{java.util.List}.
    768768
    769769% include autogen docs for the EXTENSIONS package.
    … …  
    775775implementation, ABCL endeavors to include extensions beyond the ANSI
    776776specification which are either widely adopted or are especially useful
    777 in working with the hosting JVM.
    778 
    779 \section{Implementation Dependent}
    780 \begin{enumerate}
    781   \item Compiler to JVM 5 bytecode
    782   \item Pathname extensions
    783 \end{enumerate}
     777in working with the hosting \textsc{JVM}.
     778
     779\section{Compiler to Java 5 Bytecode}
     780
     781The \code{CL:COMPILE-FILE} interface emits a packed fasl format whose
     782Pathname has the type  ``abcl''.  These fasls are operating system neutral
     783byte archives packaged by the zip compression format which contain
     784artifacts whose loading \code{CL:LOAD} understands.
    784785
    785786\section{Pathname}
    786787
    787788We implement an extension to the Pathname that allows for the
    788 description and retrieval of resources named in a URI scheme that the
    789 JVM ``understands''.  Support is built-in to the ``http'' and
     789description and retrieval of resources named in a
     790\textsc{URI} \footnote{A \textsc{URI} is essentially a superset of
     791  what is commonly understood as a \textsc{URL} We sometimesuse the
     792  term URL as shorthand in describing the URL Pathnames, even though
     793  the corresponding encoding is more akin to a URI as described in
     794  RFC3986 \cite{rfc3986}.}  scheme that the \textsc{JVM}
     795``understands''.  Support is built-in to comprehend the ``http'' and
    790796``https'' implementations but additional protocol handlers may be
    791 installed at runtime by having JVM symbols present in the
     797installed at runtime by having \textsc{JVM} symbols present in the
    792798sun.net.protocol.dynamic pacakge. See \cite{maso2000} for more
    793799details.
    794800
    795 ABCL has created specializations of the ANSI Pathname object to
    796 enable to use of URIs to address dynamically loaded resources for the
    797 JVM.  A URL-PATHNAME has a corresponding URL whose canonical
    798 representation is defined to be the NAMESTRING of the Pathname.
     801\textsc{ABCL} has created specializations of the ANSI Pathname object to
     802enable to use of \textsc{URI}s to address dynamically loaded resources for the
     803JVM.  A \code{URL-PATHNAME} has a corresponding \textsc{URI} whose canonical
     804representation is defined to be the \code{NAMESTRING} of the Pathname.
    799805
    800806%
    … …  
    805811
    806812  <jar-pathname> a <url-pathname>.
    807   <url-pathname> a <pathname>.
    808   <logical-pathname> a <pathname> .
     813  <url-pathname> a <cl:pathname>.
     814  <cl:logical-pathname> a <cl:pathname> .
    809815\end{verbatim}
    810816
    811 Both URL-PATHNAME and JAR-PATHNAME may be used anywhere a PATHNAME is
    812 accepted with the following caveats:
     817\label{EXTENSIONS:URL-PATHNAME}
     818\index{URL-PATHNAME}
     819
     820\label{EXTENSIONS:JAR-PATHNAME}
     821\index{JAR-PATHNAME}
     822
     823Both \code{URL-PATHNAME} and \code{JAR-PATHNAME} may be used anywhere
     824a \code{CL:PATHNAME} is accepted with the following caveats:
    813825
    814826\begin{itemize}
    … …  
    817829  target of write operations.
    818830
    819 \item No canonicalization is performed on the underlying URI (i.e. the
     831\item No canonicalization is performed on the underlying \textsc{URI} (i.e. the
    820832implementation does not attempt to compute the current name of the
    821833representing resource unless it is requested to be resolved.)  Upon
    … …  
    825837\end{itemize}
    826838
    827 The implementation of URL-PATHNAME allows the ABCL user to laod dynamically
    828 code from the network.  For example, for Quicklisp (\cite{quicklisp}):
     839The implementation of \code{URL-PATHNAME} allows the \textsc{ABCL}
     840user to dynamically load code from the network.  For example,
     841Quicklisp (\cite{quicklisp}) may be completely installed from the REPL
     842as the single form:
    829843
    830844\begin{listing-lisp}
    … …  
    838852\subsubsection{Implementation}
    839853
    840 \code{DEVICE} either a string denoting a drive letter under DOS or a cons
    841 specifying a \code{URL-PATHNAME}.
     854The implementation of these extensions stores all the additional
     855information in the PATHNAME object itself in ways that while strictly
     856speaking are conformant, nonetheless may trip up libraries that don't
     857expect the following:
     858
     859\begin{itemize}
     860\item \code{DEVICE} can be either a string denoting a drive letter
     861  under DOS or a list of exactly one or two elements.  If
     862  \code{DEVICE} is a list, it denotes a \code{JAR-PATHNAME}, with the entries
     863  containing \code{PATHNAME} objects which describe the outer and (possibley)
     864  locations of the jar archive.
     865
     866\item A \code{URL-PATHNAME} always has a \code{HOST} component that is a
     867  property list.  The values of the \code{HOST} property list are
     868  always character strings.  The allowed keys have the following meanings:
     869  \begin{description}
     870  \item[:SCHEME] Scheme of URI ("http", "ftp", "bundle", etc.)
     871  \item[:AUTHORITY] Valid authority according to the URI scheme.  For
     872    "http" this could be "example.org:8080".
     873  \item[:QUERY] The query of the \textsc{URI}
     874  \item[:FRAGMENT] The fragment portion of the \textsc{URI}
     875  \end{description}
     876
     877
     878\item In order to encapsulate the implementation decisions for these
     879  meanings, the following functions provide a setf-able API for
     880  reading and writing such values: \code{URL-PATHNAME-QUERY},
     881  \code{URL-PATHNAME-FRAGMENT}, \code{URL-PATHNAME-AUTHORITY}, and
     882  \code{URL-PATHNAME-SCHEME}.  The specific subtype of a Pathname may
     883  be determined with the predicates \code{PATHNAME-URL-P} and
     884  \code{PATHNAME-JAR-P}.
     885
     886\label{EXTENSIONS:URL-PATHNAME-SCHEME}
     887\index{URL-PATHNAME-SCHEME}
     888
     889\label{EXTENSIONS:URL-PATHNAME-FRAGMENT}
     890\index{URL-PATHNAME-FRAGMENT}
     891
     892\label{EXTENSIONS:URL-PATHNAME-AUTHORITY}
     893\index{URL-PATHNAME-AUTHORITY}
     894
     895\label{EXTENSIONS:PATHNAME-URL-P}
     896\index{PATHNAME-URL-P}
     897
     898\label{EXTENSIONS:URL-PATHNAME-QUERY}
     899\index{URL-PATHNAME-QUERY}
     900
     901\end{itemize}
     902
    842903         
    843904\section{Extensible Sequences}
    … …  
    922983code is greater than 0x00ff.
    923984
     985\section{Overloading of the CL:REQUIRE mechanism}
     986
     987The CL:REQUIRE mechanism is overloaded in the following ways:
     988
     989\begin{description}
     990
     991  \item{ASDF} Loads the ASDF implementation shipped with the
     992    implementation.  After ASDF has been loaded in this manner,
     993    symbols passed to CL:REQUIRE which are otherwise unresolved, are
     994    passed to ASDF for a chance for resolution.  This means, for
     995    instance that if CL-PPCRE can be located as a loadable ASDF system
     996    \code{(require 'cl-ppcre)} is equivalent to
     997    \code{(asdf:load-system 'cl-ppcre)}.
     998
     999  \item{ABCL-CONTRIB} Locates and pushes the toplevel contents of
     1000    ``abcl-contrib.jar'' into the ASDF central registry. 
     1001
     1002\end{description}
     1003
     1004The user may extend the CL:REQUIRE mechanism by pushing function hooks
     1005into SYSTEM:*MODULE-PROVIDER-FUNCTIONS*.  Each such hook function
     1006takes a single argument containing the symbol passed to CL:REQUIRE and
     1007returns a non-nil value if it can successful resolve the symbol.
     1008
    9241009\subsection{JSS optionally extends the Reader}
    9251010
    9261011The JSS contrib consitutes an additional, optional extension to the
    927 reader in the definition of the \#\" reader macro.  See
     1012reader in the definition of the \#\" reader macro.  See section
    9281013\ref{section:jss} on page \pageref{section:jss} for more information.
    9291014
    9301015\section{ASDF}
    9311016
    932 asdf-2.017.22 is packaged as core component of ABCL, but not
    933 initialized by default, as it relies on the CLOS subsystem which can
    934 take a bit of time to start \footnote{While this time is ``merely'' on
    935   the order of seconds for contemporary 2011 machines, for
    936   applications that need to initialize quickly, for example a web
    937   server, this time might be unnecessarily long}.  ASDF may be loaded
    938 by the \textsc{ANSI} \code{REQUIRE} mechanism as follows:
     1017asdf-2.019 (see \cite{asdf}) is packaged as core component of ABCL,
     1018but not initialized by default, as it relies on the CLOS subsystem
     1019which can take a bit of time to start \footnote{While this time is
     1020  ``merely'' on the order of seconds for contemporary 2011 machines,
     1021  for applications that need to initialize quickly, for example a web
     1022  server, this time might be unnecessarily long}.  The packaged ASDF
     1023may be loaded by the \textsc{ANSI} \code{REQUIRE} mechanism as
     1024follows:
    9391025
    9401026\begin{listing-lisp}
    … …  
    9461032The ABCL contrib is packaged as a separate jar archive usually named
    9471033\code{abcl-contrib.jar} or possibly something like
    948 \code{abcl-contrib-1.0.0.jar}.  The contrib jar is not loaded by the
     1034\code{abcl-contrib-1.1.0.jar}.  The contrib jar is not loaded by the
    9491035implementation by default, and must be first intialized by the
    9501036\code{REQUIRE} mechanism before using any specific contrib:
    … …  
    10491135definition of read and compile time macros is quite natural, the Java
    10501136syntax available to the Java programmer may be said to suck.  To
    1051 alleviate this situation, we introduce the
    1052 \code{SHARPSIGN-DOUBLE-QUOTE} (\code{\#"}) reader macro, the first of perhaps
    1053   many exper
     1137alleviate this situation, the JSS contrib introduces the
     1138\code{SHARPSIGN-DOUBLE-QUOTE} (\code{\#"}) reader macro, which allows the
     1139the specification of the name of invoking function as the first
     1140element of the relevant s-expr which tends to be more congruent to
     1141how Lisp programmers seem to be wired to think.
     1142
     1143While quite useful, we don't expect that the JSS contrib will be the
     1144last experiment in wrangling Java from Common Lisp.
    10541145
    10551146\subsection{JSS usage}
    … …  
    10891180code that had previously not been released publically was suddenly
    10901181committed that enabled ABCL to be plausibly termed an emergent ANSI
    1091 Common Lisp implementation canidate.
     1182Common Lisp implementation candidate.
    10921183
    10931184From 2006 to 2008, Peter manned the development lists, incorporating
    … …  
    11101201
    11111202\end{document}
    1112 
    1113 % TODO
    1114 %   1.  Create mechanism for swigging DocString and Lisp docs into
    1115 %       sections ('grovel.lisp')
    1116 
Note: See TracChangeset for help on using the changeset viewer.