Package COM.INFORMATIMAGO.COMMON-LISP.LISP-READER.READER

This package implements a standard Common Lisp reader.

We implement a Common Lisp Reader to be able to read lisp
sources.  This is a complete standard compliant lisp reader,
with additionnal hooks (token parser).

A READTABLE-PARSE-TOKEN function takes a TOKEN as argument, and
must return two values:
- A boolean indicating whether the it could parse the token,
- a parsed lisp object it could, or an error message (string) if not.

See also the TOKEN functions, CONSTITUENT-TRAIT, SYNTAX-TABLE and
CHARACTER-DESCRIPTION...


License:

    AGPL3

    Copyright Pascal J. Bourguignon 2006 - 2012

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU Affero General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU Affero General Public License for more details.

    You should have received a copy of the GNU Affero General Public License
    along with this program. If not, see <http://www.gnu.org/licenses/>

*read-base*
variable
Controls the interpretation of tokens by READ as being integers or
ratios.

The value of *READ-BASE*, called the current input base, is the radix
in which  integers and ratios are to be read by the Lisp reader. The
parsing of other numeric  types (e.g., floats) is not affected by this
option.

The effect of *READ-BASE* on the reading of any particular rational
number can be locally overridden by explicit use of the #O, #X, #B, or
#nR syntax or by a trailing decimal point.

URL: <http://www.lispworks.com/documentation/HyperSpec/Body/v_rd_bas.htm>
Initial value: 10
*read-default-float-format*
variable
Controls the floating-point format that is to be used when reading a
floating-point number that has no exponent marker or that has e or E
for an exponent marker. Other  exponent markers explicitly prescribe
the floating-point format to be used.

The printer uses *read-default-float-format* to guide the choice of
exponent markers when printing floating-point numbers.

URL: <http://www.lispworks.com/documentation/HyperSpec/Body/v_rd_def.htm>
Initial value: SINGLE-FLOAT
*read-eval*
variable
If it is true, the #. reader macro has its normal effect. Otherwise,
that reader macro signals an error of type reader-error.

URL: <http://www.lispworks.com/documentation/HyperSpec/Body/v_rd_eva.htm>
Initial value: T
*read-suppress*
variable
This variable is intended primarily to support the operation of the
read-time conditional notations #+ and #-. If it is false, the Lisp
reader operates normally.  If the value of *read-suppress* is true,
read, read-preserving-whitespace,  read-delimited-list, and
read-from-string all return a primary value of nil when they complete
successfully.

URL: <http://www.lispworks.com/documentation/HyperSpec/Body/v_rd_sup.htm>
Initial value: NIL
*readtable*
variable
The value of *READTABLE* is called the current readtable. It controls
the parsing behavior of the Lisp reader, and can also influence the
Lisp printer (e.g., see the  function READTABLE-CASE).

URL: <http://www.lispworks.com/documentation/HyperSpec/Body/v_rdtabl.htm>
Initial value: #<READTABLE #x302000A6EC1D>
(copy-readtable &optional from-readtable to-readtable)
function
DO:     Copy the readtable.
URL:    <http://www.lispworks.com/documentation/HyperSpec/Body/f_cp_rdt.htm>
(get-dispatch-macro-character disp-char sub-char &optional readtable)
function
RETURN: The dispatch macro character function.
URL:    <http://www.lispworks.com/documentation/HyperSpec/Body/f_set__1.htm>
(get-macro-character char &optional readtable)
function
RETURN: The macro character function.
URL:    <http://www.lispworks.com/documentation/HyperSpec/Body/f_set_ma.htm>
(internal-symbol package sname sym)
function
We tried to read PNAME:SNAME but the symbol is not exported.

PACKAGE:    the package specified for the symbol.

SNAME:      symbol name.

DO:         Handles the internal symbol error with restarts to export
            it or return it unexported.

NOTE:       We could also find symbols with the same name in other
            packages.

(invalid-symbol-component-list components)
function
COMPONENTS:  Parsed symbol components.
DO:          Handles invalid components lists.
(list-all-macro-characters &optional *readtable*)
function
RETURN: A list of all the macro and dispatch-macro characters in the readtable.
NOTE:   We have the same function in the com.informatimago.tools.reader-macro
        package, working on cl:readtable
        instead of com.informatimago.common-lisp.lisp-reader.reader:readtable.
(make-dispatch-macro-character char &optional non-terminating-p readtable)
function
DO:     Make the character a dispatch macro character in the readtable.
URL:    <http://www.lispworks.com/documentation/HyperSpec/Body/f_mk_dis.htm>

MAKE-SYMBOL-PARSER-FUNCTION

MAKE-TOKEN-PARSER

(missing-package pname sname)
function
We tried to read PNAME:SNAME, but there's no package named PNAME.

PNAME:  package name

SNAME:  symbol name

DO:     Handles the missing package error with restarts to intern in
        the current package or return an uninterned symbol.

NOTE:   We could also find other packages with a similar name to
        correct typoes.

missing-package-error
condition
The error condition signaled when trying use an inexistant package.
Class precedence list: MISSING-PACKAGE-ERROR READER-ERROR PARSE-ERROR STREAM-ERROR ERROR SERIOUS-CONDITION CONDITION STANDARD-OBJECT T
Class init args: STREAM PACKAGE-NAME
(missing-symbol package sname)
function
We tried to read PNAME:SNAME but no symbol found with this name.

PACKAGE:    the package specified for the symbol.

SNAME:      symbol name.

DO:         Handles the symbol missing error with restarts to intern
            in the package (and possibly export it)
            or return an uninterned symbol.

NOTE:       We could also find symbols with the same name in other
            packages.

missing-symbol-error
condition
The error condition signaled when trying to read a symbol not exported from a package.
Class precedence list: MISSING-SYMBOL-ERROR READER-ERROR PARSE-ERROR STREAM-ERROR ERROR SERIOUS-CONDITION CONDITION STANDARD-OBJECT T
Class init args: STREAM SYMBOL-NAME
(potential-number-p token &optional *read-base* ratio-markers)
function
TOKEN:         A string containing the token to be tested.
*READ-BASE*:   The current radix.
RATIO-MARKER:  / in the standard readtable, but it could be something else...
RETURN:        Whether the TOKEN is a potential number.
(read &optional input-stream eof-error-p eof-value recursive-p)
function
RETURN: An object read.
URL:    <http://www.lispworks.com/documentation/HyperSpec/Body/f_rd_rd.htm>
(read-delimited-list char &optional input-stream recursive-p)
function
RETURN: A list of objects read.
URL:    <http://www.lispworks.com/documentation/HyperSpec/Body/f_rd_del.htm>
(read-from-string string &optional eof-error-p eof-value &key start end preserve-whitespace)
function
RETURN: An object read from the string.
URL:    <http://www.lispworks.com/documentation/HyperSpec/Body/f_rd_fro.htm>
(read-preserving-whitespace &optional input-stream eof-error-p eof-value recursive-p)
function
RETURN: An object read.
URL:    <http://www.lispworks.com/documentation/HyperSpec/Body/f_rd_rd.htm>
readtable
class
A READTABLE maps characters into syntax types for the Lisp reader; see
Section 2 (Syntax). A readtable also contains associations between
macro characters and their  reader macro functions, and records
information about the case conversion rules to be used by the Lisp
reader when parsing symbols.

Each simple character must be representable in the readtable. It is
implementation-defined whether non-simple characters can have syntax
descriptions in the readtable.

URL: <http://www.lispworks.com/documentation/HyperSpec/Body/t_rdtabl.htm>
Class precedence list: READTABLE STANDARD-OBJECT T
Class init args: CASE SYNTAX-TABLE PARSE-TOKEN
(readtable-case readtable)
function
RETURN: The case of the readtable.
URL:    <http://www.lispworks.com/documentation/HyperSpec/Body/f_rdtabl.htm>
(setf (readtable-case readtable) value)
function
DO:     Set the case of the readtable.
URL:    <http://www.lispworks.com/documentation/HyperSpec/Body/f_rdtabl.htm>
(readtable-parse-token readtable)
generic-function
RETURN: The function used to parse a token that has been read.
(setf (readtable-parse-token readtable) new-function)
generic-function
DO:     Set the function used to parse a token that has been read.
(readtable-syntax-table readtable)
generic-function
RETURN: The syntax-table of the readtable.
(readtablep object)
function
RETURN: Whether the object is a readtable.
URL:    <http://www.lispworks.com/documentation/HyperSpec/Body/f_rdta_1.htm>
(set-dispatch-macro-character disp-char sub-char new-function &optional readtable)
function
DO:     Set the dispatch macro character function.
URL:    <http://www.lispworks.com/documentation/HyperSpec/Body/f_set__1.htm>
(set-indirect-dispatch-macro-character disp-char sub-char function-name &optional readtable)
function
Like set-dispatch-macro-character, but with an indirect function,
to enable TRACE and redefinitions of the dispatch macro character function.
(set-indirect-macro-character char function-name &optional readtable)
function
Like set-macro-character, but with an indirect function,
to enable TRACE and redefinitions of the macro character function.
(set-macro-character char new-function &optional non-terminating-p readtable)
function
DO:     Set then macro character function.
URL:    <http://www.lispworks.com/documentation/HyperSpec/Body/f_set_ma.htm>
(set-syntax-from-char to-char from-char &optional to-readtable from-readtable)
function
DO:     Copy the syntax between characters in the readtable.
URL:    <http://www.lispworks.com/documentation/HyperSpec/Body/f_set_sy.htm>
simple-end-of-file
condition
A simple end-of-file condition.
Class precedence list: SIMPLE-END-OF-FILE SIMPLE-ERROR SIMPLE-CONDITION END-OF-FILE STREAM-ERROR ERROR SERIOUS-CONDITION CONDITION STANDARD-OBJECT T
Class init args: STREAM FORMAT-CONTROL FORMAT-ARGUMENTS
simple-reader-error
condition
A simple reader error condition.
Class precedence list: SIMPLE-READER-ERROR SIMPLE-ERROR SIMPLE-CONDITION READER-ERROR PARSE-ERROR STREAM-ERROR ERROR SERIOUS-CONDITION CONDITION STANDARD-OBJECT T
Class init args: STREAM FORMAT-CONTROL FORMAT-ARGUMENTS
(symbol-from-split-token components)
function

COMPONENTS:  a list of strings separated by integers specifying the
             number of colons.

EXAMPLES:    X         ("X")
             :Y        (1 "Y")
             X:Y       ("X" 1 "Y")
             X::Y      ("X" 2 "Y")
             X:::Y     ("X" 3 "Y")
             X::       ("X" 2)
             X:Y:Z     ("X" 1 "Y" 1 "Z")

RETURN:      A symbol designated by the components,
             or signal an error.

NOTE:        This function implements the standard semantics,
             where only one occurence of : or :: is allowed,
             and depending on : or ::, an exported symbol is expected
             or not.

symbol-in-missing-package-error
condition
The error condition signaled when trying to read a symbol in an inexistant package.
Class precedence list: SYMBOL-IN-MISSING-PACKAGE-ERROR MISSING-PACKAGE-ERROR READER-ERROR PARSE-ERROR STREAM-ERROR ERROR SERIOUS-CONDITION CONDITION STANDARD-OBJECT T
Class init args: STREAM PACKAGE-NAME SYMBOL-NAME
symbol-missing-in-package-error
condition
The error condition signaled when trying to read a symbol not exported from a package.
Class precedence list: SYMBOL-MISSING-IN-PACKAGE-ERROR MISSING-SYMBOL-ERROR READER-ERROR PARSE-ERROR STREAM-ERROR ERROR SERIOUS-CONDITION CONDITION STANDARD-OBJECT T
Class init args: STREAM SYMBOL-NAME PACKAGE-NAME
unexported-symbol-error
condition
The error condition signaled when trying to read a symbol not exported from a package.
Class precedence list: UNEXPORTED-SYMBOL-ERROR MISSING-SYMBOL-ERROR READER-ERROR PARSE-ERROR STREAM-ERROR ERROR SERIOUS-CONDITION CONDITION STANDARD-OBJECT T
Class init args: STREAM SYMBOL-NAME PACKAGE-NAME

WITH-STANDARD-IO-SYNTAX