dotfiles/gcl-info/chap-23.texi

@node Reader, System Construction, Printer, Top
@chapter Reader

@menu
* Reader Concepts::		
* Reader Dictionary::		
@end menu

@node Reader Concepts, Reader Dictionary, Reader, Reader
@section Reader Concepts

@c including concept-reader

@menu
* Dynamic Control of the Lisp Reader::	
* Effect of Readtable Case on the Lisp Reader::	 
* Argument Conventions of Some Reader Functions::  
@end menu

@node Dynamic Control of the Lisp Reader, Effect of Readtable Case on the Lisp Reader, Reader Concepts, Reader Concepts
@subsection Dynamic Control of the Lisp Reader

Various aspects of the @i{Lisp reader} can be controlled dynamically.
See @ref{Readtables} and @ref{Variables that affect the Lisp Reader}.

@node Effect of Readtable Case on the Lisp Reader, Argument Conventions of Some Reader Functions, Dynamic Control of the Lisp Reader, Reader Concepts
@subsection Effect of Readtable Case on the Lisp Reader

The @i{readtable case} of the @i{current readtable} affects the @i{Lisp reader}
in the following ways:

@table @asis

@item @t{:upcase}  
When the @i{readtable case} is @t{:upcase},
 unescaped constituent @i{characters} are converted to @i{uppercase},
 as specified in @ref{Reader Algorithm}.

@item @t{:downcase}  
When the @i{readtable case} is @t{:downcase},
 unescaped constituent @i{characters} are converted to @i{lowercase}.

@item @t{:preserve}  
When the @i{readtable case} is @t{:preserve},
 the case of all @i{characters} remains unchanged.

@item @t{:invert}  
When the @i{readtable case} is @t{:invert},
 then if all of the unescaped letters in the extended token are of the same @i{case}, 
 those (unescaped) letters are converted to the opposite @i{case}.

@end table

@menu
* Examples of Effect of Readtable Case on the Lisp Reader::  
@end menu

@node Examples of Effect of Readtable Case on the Lisp Reader,  , Effect of Readtable Case on the Lisp Reader, Effect of Readtable Case on the Lisp Reader
@subsubsection Examples of Effect of Readtable Case on the Lisp Reader

@example
 (defun test-readtable-case-reading ()
   (let ((*readtable* (copy-readtable nil)))
     (format t "READTABLE-CASE  Input   Symbol-name~
              ~
              ~
     (dolist (readtable-case '(:upcase :downcase :preserve :invert))
       (setf (readtable-case *readtable*) readtable-case)
       (dolist (input '("ZEBRA" "Zebra" "zebra"))
         (format t "~&:~A~16T~A~24T~A"
                 (string-upcase readtable-case)
                 input
                 (symbol-name (read-from-string input)))))))
@end example

The output from @t{(test-readtable-case-reading)} should be as follows:

@example
 READTABLE-CASE     Input Symbol-name
 -------------------------------------
    :UPCASE         ZEBRA   ZEBRA
    :UPCASE         Zebra   ZEBRA
    :UPCASE         zebra   ZEBRA
    :DOWNCASE       ZEBRA   zebra
    :DOWNCASE       Zebra   zebra
    :DOWNCASE       zebra   zebra
    :PRESERVE       ZEBRA   ZEBRA
    :PRESERVE       Zebra   Zebra
    :PRESERVE       zebra   zebra
    :INVERT         ZEBRA   zebra
    :INVERT         Zebra   Zebra
    :INVERT         zebra   ZEBRA
@end example

@node Argument Conventions of Some Reader Functions,  , Effect of Readtable Case on the Lisp Reader, Reader Concepts
@subsection Argument Conventions of Some Reader Functions

@menu
* The EOF-ERROR-P argument::	
* The RECURSIVE-P argument::	
@end menu

@node The EOF-ERROR-P argument, The RECURSIVE-P argument, Argument Conventions of Some Reader Functions, Argument Conventions of Some Reader Functions
@subsubsection The EOF-ERROR-P argument

@i{Eof-error-p} in input function calls
controls what happens if input is from a file (or any other
input source that has a definite end) and the end of the file is reached.
If @i{eof-error-p} is @i{true} (the default), 
an error of @i{type} @b{end-of-file} is signaled
at end of file.  If it is @i{false}, then no error is signaled, and instead
the function returns @i{eof-value}.

Functions such as @b{read} that read the representation
of an @i{object} rather than a single
character always signals an error, regardless of @i{eof-error-p}, if
the file ends in the middle of an object representation.
For example, if a file does
not contain enough right parentheses to balance the left parentheses in
it, @b{read} signals an error.  If a file ends in a 
@i{symbol} or a @i{number}
immediately followed by end-of-file, @b{read} reads the 
@i{symbol} or
@i{number} 
successfully and when called again will
act according to @i{eof-error-p}.
Similarly, the @i{function} @b{read-line}
successfully reads the last line of a file even if that line
is terminated by end-of-file rather than the newline character.
Ignorable text, such as lines containing only @i{whitespace}_2 or comments,
are not considered to begin an @i{object}; 
if @b{read} begins to read an @i{expression} but sees only such
ignorable text, it does not consider the file to end in the middle of an @i{object}.
Thus an @i{eof-error-p} argument controls what happens
when the file ends between @i{objects}.

@node The RECURSIVE-P argument,  , The EOF-ERROR-P argument, Argument Conventions of Some Reader Functions
@subsubsection The RECURSIVE-P argument

If @i{recursive-p} is supplied and not @b{nil}, it specifies that
this function call is not an outermost call to @b{read} but an 
embedded call, typically from a @i{reader macro function}.
It is important to distinguish such recursive calls for three reasons.

@table @asis

@item 1.  
An outermost call establishes the context within which the
@t{#@i{n}=} and @t{#@i{n}#} syntax is scoped.  Consider, for example,
the expression

@example
 (cons '#3=(p q r) '(x y . #3#))
@end example

If the @i{single-quote} @i{reader macro} were defined in this way:

@example
 (set-macro-character #\'       ;incorrect
    #'(lambda (stream char)
         (declare (ignore char))
         (list 'quote (read stream))))
@end example

then each call to the @i{single-quote} @i{reader macro function} would establish
independent contexts for the scope of @b{read} information, including the scope of
identifications between markers like ``@t{#3=}'' and ``@t{#3#}''.  However, for
this expression, the scope was clearly intended to be determined by the outer set 
of parentheses, so such a definition would be incorrect.
The correct way to define the @i{single-quote}
@i{reader macro} uses @i{recursive-p}: 

@example
 (set-macro-character #\'       ;correct
    #'(lambda (stream char)
         (declare (ignore char))
         (list 'quote (read stream t nil t))))
@end example

@item 2.  
A recursive call does not alter whether the reading process
is to preserve @i{whitespace}_2 or not (as determined by whether the
outermost call was to @b{read} or @b{read-preserving-whitespace}).
Suppose again that @i{single-quote} 
were to be defined as shown above in the incorrect definition.
Then a call to @b{read-preserving-whitespace}
that read the expression @t{'foo<@i{Space}>} would fail to preserve the space
character following the symbol @t{foo} because the @i{single-quote}
@i{reader macro function} calls @b{read}, 
not @b{read-preserving-whitespace},
to read the following expression (in this case @t{foo}).
The correct definition, which passes the value @i{true} for @i{recursive-p}
to @b{read}, allows the outermost call to determine
whether @i{whitespace}_2 is preserved.

@item 3.  
When end-of-file is encountered and the @i{eof-error-p} argument
is not @b{nil}, the kind of error that is signaled may depend on the value
of @i{recursive-p}.  If @i{recursive-p} 
is @i{true}, then the end-of-file
is deemed to have occurred within the middle of a printed representation;
if @i{recursive-p} is @i{false}, then the end-of-file may be deemed to have
occurred between @i{objects} rather than within the middle of one.

@end table

@c end of including concept-reader

@node Reader Dictionary,  , Reader Concepts, Reader
@section Reader Dictionary

@c including dict-reader

@menu
* readtable::			
* copy-readtable::		
* make-dispatch-macro-character::  
* read::			
* read-delimited-list::		
* read-from-string::		
* readtable-case::		
* readtablep::			
* set-dispatch-macro-character::  
* set-macro-character::		
* set-syntax-from-char::	
* with-standard-io-syntax::	
* *read-base*::			
* *read-default-float-format*::	 
* *read-eval*::			
* *read-suppress*::		
* *readtable*::			
* reader-error::		
@end menu

@node readtable, copy-readtable, Reader Dictionary, Reader Dictionary
@subsection readtable                                                    [System Class]

@subsubheading  Class Precedence List::
@b{readtable},
@b{t}

@subsubheading  Description::

A @i{readtable} maps @i{characters} into @i{syntax types} for 
the @i{Lisp reader}; see @ref{Syntax}.
A @i{readtable} also 
     contains associations between @i{macro characters} 
		               and their @i{reader macro functions},
 and records information about the case conversion rules 
     to be used by the @i{Lisp reader} when parsing @i{symbols}.

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

@subsubheading  See Also::

@ref{Readtables},
@ref{Printing Other Objects}

@node copy-readtable, make-dispatch-macro-character, readtable, Reader Dictionary
@subsection copy-readtable                                                   [Function]

@code{copy-readtable}  @i{{&optional} from-readtable to-readtable} @result{}  @i{readtable}

@subsubheading  Arguments and Values::

@i{from-readtable}---a @i{readtable designator}.
 The default is the @i{current readtable}.

@i{to-readtable}---a @i{readtable} or @b{nil}.
 The default is @b{nil}.

@i{readtable}---the @i{to-readtable} if it is @i{non-nil},
  or else a @i{fresh} @i{readtable}.

@subsubheading  Description::

@b{copy-readtable} copies @i{from-readtable}.

If @i{to-readtable} is @b{nil}, a new @i{readtable} is created and returned.  
Otherwise the @i{readtable} specified by @i{to-readtable} is modified and returned.

@b{copy-readtable} copies the setting of @b{readtable-case}.

@subsubheading  Examples::

@example
 (setq zvar 123) @result{}  123
 (set-syntax-from-char #\z #\' (setq table2 (copy-readtable))) @result{}  T
 zvar @result{}  123
 (copy-readtable table2 *readtable*) @result{}  #<READTABLE 614000277>
 zvar @result{}  VAR
 (setq *readtable* (copy-readtable)) @result{}  #<READTABLE 46210223>
 zvar @result{}  VAR
 (setq *readtable* (copy-readtable nil)) @result{}  #<READTABLE 46302670>
 zvar @result{}  123
@end example

@subsubheading  See Also::

@b{readtable},
@ref{readtable}

@subsubheading  Notes::

@example
(setq *readtable* (copy-readtable nil))
@end example

restores the input syntax to standard @r{Common Lisp} syntax, even if
the @i{initial readtable} has been clobbered 
(assuming it is not so badly clobbered that you cannot type in the above expression).

On the other hand,

@example
(setq *readtable* (copy-readtable))
@end example

replaces the current @i{readtable} with a copy of itself.
This is useful if you want to save a copy of a readtable for later use,
protected from alteration in the meantime.  It is also useful if you want to
locally bind the readtable to a copy of itself, as in:

@example
(let ((*readtable* (copy-readtable))) ...)
@end example

@node make-dispatch-macro-character, read, copy-readtable, Reader Dictionary
@subsection make-dispatch-macro-character                                    [Function]

@code{make-dispatch-macro-character}  @i{char {&optional} non-terminating-p readtable} @result{}  @i{@b{t}}

@subsubheading  Arguments and Values::

@i{char}---a @i{character}.

@i{non-terminating-p}---a @i{generalized boolean}.
 The default is @i{false}.

@i{readtable}---a @i{readtable}.
 The default is the @i{current readtable}.

@subsubheading  Description::

@b{make-dispatch-macro-character} makes @i{char} 
be a @i{dispatching macro character} in @i{readtable}.

Initially, every @i{character} in the dispatch table
associated with the @i{char} has an associated function 
that signals an error of @i{type} @b{reader-error}.

If @i{non-terminating-p} is @i{true}, 
the @i{dispatching macro character} 
is made a @i{non-terminating} @i{macro character};
if @i{non-terminating-p} is @i{false},
the @i{dispatching macro character} 
is made a @i{terminating} @i{macro character}.

@subsubheading  Examples::

@example
 (get-macro-character #\@{) @result{}  NIL, @i{false}
 (make-dispatch-macro-character #\@{) @result{}  T
 (not (get-macro-character #\@{)) @result{}  @i{false}
@end example

The @i{readtable} is altered.

@subsubheading  See Also::

@ref{readtable}
, 
@ref{set-dispatch-macro-character; get-dispatch-macro-character}

@node read, read-delimited-list, make-dispatch-macro-character, Reader Dictionary
@subsection read, read-preserving-whitespace                                 [Function]

@code{read}  @i{{&optional} input-stream eof-error-p eof-value recursive-p} @result{}  @i{object}

@code{read-preserving-whitespace}  @i{{&optional} input-stream eof-error-p
		               eof-value recursive-p}@*
   @result{}  @i{object}

@subsubheading  Arguments and Values::

@i{input-stream}---an @i{input} @i{stream designator}.

@i{eof-error-p}---a @i{generalized boolean}.
 The default is @i{true}.

@i{eof-value}---an @i{object}.

 The default is @b{nil}.

@i{recursive-p}---a @i{generalized boolean}.
 The default is @i{false}.

@i{object}---an @i{object} (parsed by the @i{Lisp reader})
		 or the @i{eof-value}.

@subsubheading  Description::

@b{read} parses the printed representation of an @i{object}
from @i{input-stream} and builds such an @i{object}.

@b{read-preserving-whitespace} is like @b{read} but preserves
any @i{whitespace}_2 @i{character}
that delimits the printed representation of the @i{object}.
@b{read-preserving-whitespace} is exactly like @b{read}
when the @i{recursive-p} @i{argument} to @b{read-preserving-whitespace}
is @i{true}.

When @b{*read-suppress*} is @i{false},
@b{read} throws away the delimiting @i{character} required by
certain printed representations if it is a
@i{whitespace}_2 @i{character};
but @b{read} preserves the character 
(using @b{unread-char}) if it is
syntactically meaningful, because it could be the start of the next expression.

If a file ends in a @i{symbol} or a @i{number}
immediately followed by an @i{end of file}_1,
@b{read} reads the @i{symbol} or @i{number} successfully;
when called again, it sees the @i{end of file}_1 and
only then acts according to @i{eof-error-p}.
If a file contains ignorable text at the end, such
as blank lines and comments, @b{read} 
does not consider it to end in the
middle of an @i{object}.

If @i{recursive-p} is @i{true}, the call to @b{read} is 
expected to be made
from within some function that itself
has been called from @b{read} or from a similar input function, rather
than from the top level.  

Both functions return the @i{object} read from @i{input-stream}.
@i{Eof-value} is returned if @i{eof-error-p} is @i{false} and end of file
is reached before the beginning of an @i{object}.

@subsubheading  Examples::

@example
 (read)
@t{ |> } @b{|>>}@t{'a}@b{<<|}
@result{}  (QUOTE A)
 (with-input-from-string (is " ") (read is nil 'the-end)) @result{}  THE-END
 (defun skip-then-read-char (s c n)
    (if (char= c #\@{) (read s t nil t) (read-preserving-whitespace s))
    (read-char-no-hang s)) @result{}  SKIP-THEN-READ-CHAR
 (let ((*readtable* (copy-readtable nil)))
    (set-dispatch-macro-character #\# #\@{ #'skip-then-read-char)
    (set-dispatch-macro-character #\# #\@} #'skip-then-read-char)
    (with-input-from-string (is "#@{123 x #@}123 y")
      (format t "~S ~S" (read is) (read is)))) @result{}  #\x, #\Space, NIL
@end example

As an example, consider this @i{reader macro} definition:

@example
 (defun slash-reader (stream char)
   (declare (ignore char))
   `(path . ,(loop for dir = (read-preserving-whitespace stream t nil t)
                   then (progn (read-char stream t nil t)
                               (read-preserving-whitespace stream t nil t))
                   collect dir
                   while (eql (peek-char nil stream nil nil t) #\/))))
 (set-macro-character #\/ #'slash-reader)
@end example

Consider now calling @b{read} on this expression:

@example
 (zyedh /usr/games/zork /usr/games/boggle)
@end example

The @t{/} macro reads objects separated by more @t{/} characters;
thus @t{/usr/games/zork} is intended to read as @t{(path usr games zork)}.
The entire example expression should therefore be read as

@example
 (zyedh (path usr games zork) (path usr games boggle))
@end example

However, if @b{read} had been used instead of
@b{read-preserving-whitespace}, then after the reading of the symbol
@t{zork}, the following space would be discarded; the next call
to @b{peek-char} would see the following @t{/}, and the loop would
continue, producing this interpretation:

@example
 (zyedh (path usr games zork usr games boggle))
@end example

There are times when @i{whitespace}_2 should be discarded.
If a command interpreter takes single-character commands,
but occasionally reads an @i{object} then if the @i{whitespace}_2
after a @i{symbol} 
is not discarded it might be interpreted as a command
some time later after the @i{symbol} had been read.

@subsubheading  Affected By::

@b{*standard-input*},
@b{*terminal-io*},
@b{*readtable*},
@b{*read-default-float-format*},
@b{*read-base*},
@b{*read-suppress*},
@b{*package*},
@b{*read-eval*}.

@subsubheading  Exceptional Situations::

@b{read} signals an error of @i{type} @b{end-of-file}, 
regardless of @i{eof-error-p}, if
the file ends in the middle of an @i{object} representation.
For example, if a file does
not contain enough right parentheses to balance the left parentheses in
it, @b{read} signals an error.
This is detected when @b{read} or @b{read-preserving-whitespace}
is called with @i{recursive-p} and @i{eof-error-p} @i{non-nil}, 
and end-of-file is reached before the beginning of an @i{object}.

If @i{eof-error-p} is @i{true}, an error of @i{type} @b{end-of-file}
is signaled at the end of file.

@subsubheading  See Also::

@ref{peek-char}
,
@ref{read-char}
,
@ref{unread-char}
,
@ref{read-from-string}
,
@ref{read-delimited-list}
, 
@ref{parse-integer}
, 
{@ref{Syntax}},
{@ref{Reader Concepts}}

@node read-delimited-list, read-from-string, read, Reader Dictionary
@subsection read-delimited-list                                              [Function]

@code{read-delimited-list}  @i{char {&optional} input-stream recursive-p} @result{}  @i{list}

@subsubheading  Arguments and Values::

@i{char}---a @i{character}.

@i{input-stream}---an @i{input} @i{stream designator}.
 The default is @i{standard input}.

@i{recursive-p}---a @i{generalized boolean}.
 The default is @i{false}.

@i{list}---a @i{list} of the @i{objects} read.

@subsubheading  Description::

@b{read-delimited-list} reads @i{objects} from @i{input-stream} 
until the next character after an @i{object}'s
representation (ignoring @i{whitespace}_2 characters and comments) is @i{char}.

@b{read-delimited-list} looks ahead at each step
for the next non-@i{whitespace}_2 @i{character}
and peeks at it as if with @b{peek-char}.
If it is @i{char}, 
then the @i{character} is consumed and the @i{list} of @i{objects} is returned.
If it is a @i{constituent} or @i{escape} @i{character},
then @b{read} is used to read an @i{object},
which is added to the end of the @i{list}.
If it is a @i{macro character},
its @i{reader macro function} is called;
if the function returns a @i{value},
that @i{value} is added to the @i{list}.
The peek-ahead process is then repeated.

If @i{recursive-p} is @i{true},
this call is expected to be embedded in a higher-level call to @b{read} 
or a similar function.

It is an error to reach end-of-file during the operation of
@b{read-delimited-list}.

The consequences are undefined
if @i{char} has a @i{syntax type} of @i{whitespace}_2
in the @i{current readtable}.

@subsubheading  Examples::
@example
 (read-delimited-list #\{]}) 1 2 3 4 5 6 {]}
@result{}  (1 2 3 4 5 6)
@end example

Suppose you wanted @t{#@{{@i{a}} @i{b} @i{c} ... @i{z}@}}
to read as a list of all pairs of the elements @i{a}, @i{b}, @i{c}, 
..., @i{z}, for example.

@example
 #@{p q z a@}  reads as  ((p q) (p z) (p a) (q z) (q a) (z a))
@end example

This can be done by specifying a macro-character definition for @t{#@{}
that does two things: reads in all the items up to the @t{@}},
and constructs the pairs.  @b{read-delimited-list} performs
the first task.

@example
 (defun |#@{-reader| (stream char arg)
   (declare (ignore char arg))
   (mapcon #'(lambda (x)
              (mapcar #'(lambda (y) (list (car x) y)) (cdr x)))
          (read-delimited-list #\@} stream t))) @result{}  |#@{-reader|

 (set-dispatch-macro-character #\# #\@{ #'|#@{-reader|) @result{}  T 
 (set-macro-character #\@} (get-macro-character #\) @b{nil}))
@end example

Note that @i{true} is supplied for the @i{recursive-p} argument.

It is necessary here to give a definition to the character @t{@}} as
well to prevent it from being a constituent.
If the line

@example
 (set-macro-character #\@} (get-macro-character #\) @b{nil}))
@end example

shown above were not included, then the @t{@}} in

@example
 #@{ p q z a@}
@end example

would be considered a constituent character, part of the symbol named
@t{a@}}.  This could be corrected by putting a space before
the @t{@}}, but it is better to call
@b{set-macro-character}.

Giving @t{@}} the same	      
definition as the standard definition of the character @t{)} has the
twin benefit of making it terminate tokens for use with 
@b{read-delimited-list} and also making it invalid for use in any
other context. Attempting to read a stray @t{@}} will signal an error.

@subsubheading  Affected By::

@b{*standard-input*},
@b{*readtable*},
@b{*terminal-io*}.

@subsubheading  See Also::

@ref{read; read-preserving-whitespace}
,
@ref{peek-char}
,
@ref{read-char}
,
@ref{unread-char}
.

@subsubheading  Notes::

@b{read-delimited-list} is intended for use in implementing @i{reader macros}.
Usually it is desirable for @i{char} to be a @i{terminating} @i{macro character}
so that it can be used to delimit tokens; however, @b{read-delimited-list}
makes no attempt to alter the syntax specified for @i{char} by the current
readtable.  The caller must make any necessary changes to the readtable syntax 
explicitly.

@node read-from-string, readtable-case, read-delimited-list, Reader Dictionary
@subsection read-from-string                                                 [Function]

@code{read-from-string}  @i{string {&optional} eof-error-p eof-value
                               {&key} start end preserve-whitespace}@*
   @result{}  @i{object, position}

@subsubheading  Arguments and Values::

@i{string}---a @i{string}.

@i{eof-error-p}---a @i{generalized boolean}.
 The default is @i{true}.

@i{eof-value}---an @i{object}.

 The default is @b{nil}.

@i{start}, @i{end}---@i{bounding index designators} of @i{string}.
 The defaults for @i{start} and @i{end} are @t{0} and @b{nil}, respectively.

@i{preserve-whitespace}---a @i{generalized boolean}.
 The default is @i{false}.

@i{object}---an @i{object} (parsed by the @i{Lisp reader})
		 or the @i{eof-value}.

@i{position}---an @i{integer} greater than or equal to zero,
		   and less than or equal to 
		   one more than the @i{length} of the @i{string}. 

@subsubheading  Description::

Parses the printed representation of an @i{object}
from the subsequence of @i{string} @i{bounded} by @i{start} and @i{end},
as if @b{read} had been called on an @i{input} @i{stream} 
containing those same @i{characters}.

If @i{preserve-whitespace} is @i{true},
the operation will preserve @i{whitespace}_2
as @b{read-preserving-whitespace} would do.

If an @i{object} is successfully parsed, the @i{primary value}, @i{object},
is the @i{object} that was parsed.
If @i{eof-error-p} is @i{false} and if the end of the @i{substring} is reached,
@i{eof-value} is returned.

The @i{secondary value}, @i{position}, is the index of the first @i{character}
in the @i{bounded} @i{string} that was not read.
The @i{position} may depend upon the value of @i{preserve-whitespace}.
If the entire @i{string} was read, 
the @i{position} returned is either the @i{length} of the @i{string} 
or one greater than the @i{length} of the @i{string}.

@subsubheading  Examples::

@example
 (read-from-string " 1 3 5" t nil :start 2) @result{}  3, 5
 (read-from-string "(a b c)") @result{}  (A B C), 7
@end example

@subsubheading  Exceptional Situations::

If the end of the supplied substring
occurs before an @i{object} can be read, an
error is signaled if @i{eof-error-p} is @i{true}.
An error is signaled if the end of the @i{substring} occurs
in the middle of an incomplete @i{object}.

@subsubheading  See Also::

@ref{read; read-preserving-whitespace}
,
@b{read-preserving-whitespace}

@subsubheading  Notes::

The reason that @i{position} is allowed to be beyond the
@i{length} of the @i{string} is to permit (but not require)
the @i{implementation} to work by simulating the effect of a 
trailing delimiter at the end of the @i{bounded} @i{string}.
When @i{preserve-whitespace} is @i{true},
the @i{position} might count the simulated delimiter.

@node readtable-case, readtablep, read-from-string, Reader Dictionary
@subsection readtable-case                                                   [Accessor]

@code{readtable-case}  @i{readtable} @result{}  @i{mode}

(setf (@code{ readtable-case} @i{readtable}) mode)@*

@subsubheading  Arguments and Values::

@i{readtable}---a @i{readtable}.

@i{mode}---a @i{case sensitivity mode}.

@subsubheading  Description::

@i{Accesses} the @i{readtable case} of @i{readtable},
which affects the way in which the @i{Lisp Reader}  reads  @i{symbols}
          and the way in which the @i{Lisp Printer} writes @i{symbols}.

@subsubheading  Examples::

See @ref{Examples of Effect of Readtable Case on the Lisp Reader} and @ref{Examples of Effect of Readtable Case on the Lisp Printer}.

@subsubheading  Exceptional Situations::

Should signal an error of @i{type} @b{type-error}
			      if @i{readtable} is not a @i{readtable}.
Should signal an error of @i{type} @b{type-error}
			      if @i{mode} is not a @i{case sensitivity mode}.

@subsubheading  See Also::

@ref{readtable}
,
@b{*print-escape*},
@ref{Reader Algorithm},
@ref{Effect of Readtable Case on the Lisp Reader},
@ref{Effect of Readtable Case on the Lisp Printer}

@subsubheading  Notes::

@b{copy-readtable} copies the @i{readtable case} of the @i{readtable}.

@node readtablep, set-dispatch-macro-character, readtable-case, Reader Dictionary
@subsection readtablep                                                       [Function]

@code{readtablep}  @i{object} @result{}  @i{generalized-boolean}

@subsubheading  Arguments and Values:: 

@i{object}---an @i{object}.

@i{generalized-boolean}---a @i{generalized boolean}.

@subsubheading  Description::

Returns @i{true} if @i{object} is of @i{type} @b{readtable};
otherwise, returns @i{false}.

@subsubheading  Examples::

@example
 (readtablep *readtable*) @result{}  @i{true}
 (readtablep (copy-readtable)) @result{}  @i{true}
 (readtablep '*readtable*) @result{}  @i{false}
@end example

@subsubheading  Notes::

@example
 (readtablep @i{object}) @equiv{} (typep @i{object} 'readtable) 
@end example

@node set-dispatch-macro-character, set-macro-character, readtablep, Reader Dictionary
@subsection set-dispatch-macro-character, get-dispatch-macro-character
@flushright
@i{[Function]}
@end flushright

@code{get-dispatch-macro-character}  @i{disp-char sub-char {&optional} readtable} @result{}  @i{function}

@code{set-dispatch-macro-character}  @i{disp-char sub-char new-function {&optional} readtable} @result{}  @i{@b{t}}

@subsubheading  Arguments and Values::

@i{disp-char}---a @i{character}.

@i{sub-char}---a @i{character}.

@i{readtable}---a @i{readtable designator}.

 The default is the @i{current readtable}.

@i{function}---a @i{function designator} or @b{nil}.

@i{new-function}---a @i{function designator}.

@subsubheading  Description::

@b{set-dispatch-macro-character} causes @i{new-function} to be called
when @i{disp-char} followed by @i{sub-char} is read.  
If @i{sub-char} is a lowercase letter, 
it is converted to its uppercase equivalent.
It is an error if @i{sub-char} is one of the ten decimal digits.

@b{set-dispatch-macro-character} installs a @i{new-function} to be called
when a particular @i{dispatching macro character} pair is read.
@i{New-function} is installed as the dispatch function to be
called  when @i{readtable} is in use and when @i{disp-char} is followed by 
@i{sub-char}.

For more information about how the @i{new-function} is invoked,
see @ref{Macro Characters}.

@b{get-dispatch-macro-character} retrieves
the dispatch function associated with @i{disp-char} and @i{sub-char}
in @i{readtable}.

@b{get-dispatch-macro-character} returns the macro-character function
for @i{sub-char} under @i{disp-char}, or @b{nil} if there is no
function associated with @i{sub-char}.
If @i{sub-char} is a decimal digit, @b{get-dispatch-macro-character}
returns @b{nil}.

@subsubheading  Examples::                                        

@example
 (get-dispatch-macro-character #\# #\@{) @result{}  NIL
 (set-dispatch-macro-character #\# #\@{        ;dispatch on #@{
    #'(lambda(s c n)
        (let ((list (read s nil (values) t)))  ;list is object after #n@{
          (when (consp list)                   ;return nth element of list
            (unless (and n (< 0 n (length list))) (setq n 0))
            (setq list (nth n list)))
         list))) @result{}  T
 #@{(1 2 3 4) @result{}  1
 #3@{(0 1 2 3) @result{}  3
 #@{123 @result{}  123
@end example

If it is desired that @t{#$@i{foo}} :
as if it were @t{(dollars @i{foo})}.

@example
(defun |#$-reader| (stream subchar arg)
   (declare (ignore subchar arg))
   (list 'dollars (read stream t nil t))) @result{}  |#$-reader|
 (set-dispatch-macro-character #\# #\$ #'|#$-reader|) @result{}  T
@end example

@subsubheading  See Also::

@ref{Macro Characters}

@subsubheading  Side Effects::

The @i{readtable} is modified.

@subsubheading  Affected By::

@b{*readtable*}.

@subsubheading  Exceptional Situations::

For either function, an error is signaled if @i{disp-char} is not 
a @i{dispatching macro character} in @i{readtable}.  

@subsubheading  See Also::

@ref{readtable}

@subsubheading  Notes::
It is necessary
to use @b{make-dispatch-macro-character} to set up the
dispatch character before specifying its sub-characters.

@node set-macro-character, set-syntax-from-char, set-dispatch-macro-character, Reader Dictionary
@subsection set-macro-character, get-macro-character                         [Function]

@code{get-macro-character}  @i{char {&optional} readtable} @result{}  @i{function, non-terminating-p}

@code{set-macro-character}  @i{char new-function {&optional} non-terminating-p readtable} @result{}  @i{@b{t}}

@subsubheading  Arguments and Values::

@i{char}---a @i{character}.

@i{non-terminating-p}---a @i{generalized boolean}.
 The default is @i{false}.

@i{readtable}---a @i{readtable designator}.

 The default is the @i{current readtable}.

@i{function}---@b{nil}, 
		   or a @i{designator} for a @i{function} of two @i{arguments}.

@i{new-function}---a @i{function designator}.

@subsubheading  Description::

@b{get-macro-character} returns as its @i{primary value}, @i{function},
the @i{reader macro function} associated with @i{char} in @i{readtable} (if any),
or else @b{nil} if @i{char} is not a @i{macro character} in @i{readtable}.
The @i{secondary value}, @i{non-terminating-p}, is @i{true} 
if @i{char} is a @i{non-terminating} @i{macro character};
otherwise, it is @i{false}.

@b{set-macro-character} causes @i{char} to be a @i{macro character}
associated with the @i{reader macro function} @i{new-function} 
(or the @i{designator} for @i{new-function}) in @i{readtable}.
If @i{non-terminating-p} is @i{true},
@i{char} becomes a @i{non-terminating} @i{macro character};
otherwise it becomes a     @i{terminating} @i{macro character}.

@subsubheading  Examples::

@example
 (get-macro-character #\@{) @result{}  NIL, @i{false}
 (not (get-macro-character #\;)) @result{}  @i{false}
@end example

The following is a possible definition for the @i{single-quote} @i{reader macro} 
in @i{standard syntax}:

@example
 (defun single-quote-reader (stream char)
   (declare (ignore char))
   (list 'quote (read stream t nil t))) @result{}  SINGLE-QUOTE-READER
 (set-macro-character #\' #'single-quote-reader) @result{}  T
@end example

Here @t{single-quote-reader} reads an @i{object} following the @i{single-quote}
and returns a @i{list} of @b{quote} and that @i{object}.
The @i{char} argument is ignored.

The following is a possible definition for the @i{semicolon} @i{reader macro}
in @i{standard syntax}:

@example
 (defun semicolon-reader (stream char)
   (declare (ignore char))
   ;; First swallow the rest of the current input line.
   ;; End-of-file is acceptable for terminating the comment.
   (do () ((char= (read-char stream nil #\Newline t) #\Newline)))
   ;; Return zero values.
   (values)) @result{}  SEMICOLON-READER
 (set-macro-character #\; #'semicolon-reader) @result{}  T
@end example

@subsubheading  Side Effects::

The @i{readtable} is modified.

@subsubheading  See Also::

@ref{readtable}

@node set-syntax-from-char, with-standard-io-syntax, set-macro-character, Reader Dictionary
@subsection set-syntax-from-char                                             [Function]

@code{set-syntax-from-char}  @i{to-char from-char {&optional} to-readtable from-readtable} @result{}  @i{@b{t}}

@subsubheading  Arguments and Values::

@i{to-char}---a @i{character}.

@i{from-char}---a @i{character}.

@i{to-readtable}---a @i{readtable}. 
 The default is the @i{current readtable}.

@i{from-readtable}---a @i{readtable designator}.
 The default is the @i{standard readtable}.

@subsubheading  Description::

@b{set-syntax-from-char} makes
the syntax of @i{to-char}   in @i{to-readtable}    be the same as
the syntax of @i{from-char} in @i{from-readtable}.

@b{set-syntax-from-char} copies the @i{syntax types} of @i{from-char}.
If @i{from-char} is a @i{macro character},
its @i{reader macro function} is copied also.
If the character is a @i{dispatching macro character}, 
its entire dispatch table of @i{reader macro functions} is copied.  
The @i{constituent traits} of @i{from-char} are not copied.

A macro definition from a character such as
@t{"} can be copied to another character; the standard definition for @t{"}
looks for another character that is the same as the character that
invoked it.  The definition of @t{(} can not be meaningfully copied
to @t{@{}, on the other hand. 
The result is that @i{lists} are of the form
@t{@{a b c)}, not @t{@{a b c@}},
because the definition
always looks for a closing parenthesis, not a closing brace.  

@subsubheading  Examples::
@example
 (set-syntax-from-char #\7 #\;) @result{}  T
 123579 @result{}  1235
@end example

@subsubheading  Side Effects::

The @i{to-readtable} is modified.

@subsubheading  Affected By::

The existing values in the @i{from-readtable}.

@subsubheading  See Also::

@ref{set-macro-character; get-macro-character}
,
@ref{make-dispatch-macro-character}
,
@ref{Character Syntax Types}

@subsubheading  Notes::                                        

The @i{constituent traits} of a @i{character} are ``hard wired'' 
into the parser for extended @i{tokens}.  For example, if the definition
of @t{S} is copied to @t{*}, then @t{*} will become a @i{constituent} 
that is @i{alphabetic}_2 but that cannot be used as a
@i{short float} @i{exponent marker}.
For further information, see @ref{Constituent Traits}.

@node with-standard-io-syntax, *read-base*, set-syntax-from-char, Reader Dictionary
@subsection with-standard-io-syntax                                             [Macro]

@code{with-standard-io-syntax}  @i{@{@i{form}@}{*}} @result{}  @i{@{@i{result}@}{*}}

@subsubheading  Arguments and Values::

@i{forms}---an @i{implicit progn}.

@i{results}---the @i{values} returned by the @i{forms}.

@subsubheading  Description::

Within the dynamic extent of the body of @i{forms}, all reader/printer control
variables, including any @i{implementation-defined} ones not specified by
this standard, are bound to values that produce standard read/print
behavior.  The values for the variables specified by this standard are listed in 
Figure 23--1.

[Reviewer Note by Barrett: *print-pprint-dispatch* should probably be mentioned here, too.]

@group
@noindent
@w{  Variable                     Value                               }
@w{  @b{*package*}                    The @t{CL-USER} @i{package}                 }
@w{  @b{*print-array*}                @b{t}                                   }
@w{  @b{*print-base*}                 @t{10}                                  }
@w{  @b{*print-case*}                 @t{:upcase}                             }
@w{  @b{*print-circle*}               @b{nil}                                 }
@w{  @b{*print-escape*}               @b{t}                                   }
@w{  @b{*print-gensym*}               @b{t}                                   }
@w{  @b{*print-length*}               @b{nil}                                 }
@w{  @b{*print-level*}                @b{nil}                                 }
@w{  @b{*print-lines*}                @b{nil}                                 }
@w{  @b{*print-miser-width*}          @b{nil}                                 }
@w{  @b{*print-pprint-dispatch*}      The @i{standard pprint dispatch table}  }
@w{  @b{*print-pretty*}               @b{nil}                                 }
@w{  @b{*print-radix*}                @b{nil}                                 }
@w{  @b{*print-readably*}             @b{t}                                   }
@w{  @b{*print-right-margin*}         @b{nil}                                 }
@w{  @b{*read-base*}                  @t{10}                                  }
@w{  @b{*read-default-float-format*}  @b{single-float}                        }
@w{  @b{*read-eval*}                  @b{t}                                   }
@w{  @b{*read-suppress*}              @b{nil}                                 }
@w{  @b{*readtable*}                  The @i{standard readtable}              }

@noindent
@w{         Figure 23--1: Values of standard control variables        }

@end group

@subsubheading  Examples::

@example
 (with-open-file (file pathname :direction :output)
   (with-standard-io-syntax
     (print data file)))

;;; ... Later, in another Lisp:

 (with-open-file (file pathname :direction :input)
   (with-standard-io-syntax
     (setq data (read file))))
@end example

@node *read-base*, *read-default-float-format*, with-standard-io-syntax, Reader Dictionary
@subsection *read-base*                                                      [Variable]

@subsubheading  Value Type::

a @i{radix}.

@subsubheading  Initial Value::

@t{10}.

@subsubheading  Description::

Controls the interpretation of tokens by @b{read} as being
@i{integers} or @i{ratios}.  

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

The effect of @b{*read-base*} on the reading of any particular
@i{rational} number can be locally overridden by explicit use of the
@t{#O}, @t{#X}, @t{#B}, or @t{#@i{n}R} syntax
or by a trailing decimal point.

@subsubheading  Examples::

@example
 (dotimes (i 6)
   (let ((*read-base* (+ 10. i)))
     (let ((object (read-from-string "(\\DAD DAD |BEE| BEE 123. 123)")))
       (print (list *read-base* object)))))
@t{ |> } (10 (DAD DAD BEE BEE 123 123))
@t{ |> } (11 (DAD DAD BEE BEE 123 146))
@t{ |> } (12 (DAD DAD BEE BEE 123 171))
@t{ |> } (13 (DAD DAD BEE BEE 123 198))
@t{ |> } (14 (DAD 2701 BEE BEE 123 227))
@t{ |> } (15 (DAD 3088 BEE 2699 123 258))
@result{}  NIL
@end example

@subsubheading  Notes::

Altering the input radix can be useful when reading data files in special formats.

@node *read-default-float-format*, *read-eval*, *read-base*, Reader Dictionary
@subsection *read-default-float-format*                                      [Variable]

@subsubheading  Value Type::

one of the @i{atomic type specifiers} 
    @b{short-float},
    @b{single-float},
    @b{double-float},
 or @b{long-float}, 
 or else some other @i{type specifier} defined 
    by the @i{implementation} to be acceptable.

@subsubheading  Initial Value::

The @i{symbol} @b{single-float}.

@subsubheading  Description::

Controls the floating-point format that is to be used when reading a
floating-point number that has no @i{exponent marker} or that has
@t{e} or @t{E} for an @i{exponent marker}.  Other @i{exponent markers}
explicitly prescribe the floating-point format to be used.

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

@subsubheading  Examples::

@example
 (let ((*read-default-float-format* 'double-float))
   (read-from-string "(1.0 1.0e0 1.0s0 1.0f0 1.0d0 1.0L0)"))
@result{}  (1.0   1.0   1.0   1.0 1.0   1.0)   ;Implementation has float format F.
@result{}  (1.0   1.0   1.0s0 1.0 1.0   1.0)   ;Implementation has float formats S and F.
@result{}  (1.0d0 1.0d0 1.0   1.0 1.0d0 1.0d0) ;Implementation has float formats F and D.
@result{}  (1.0d0 1.0d0 1.0s0 1.0 1.0d0 1.0d0) ;Implementation has float formats S, F, D.
@result{}  (1.0d0 1.0d0 1.0   1.0 1.0d0 1.0L0) ;Implementation has float formats F, D, L.
@result{}  (1.0d0 1.0d0 1.0s0 1.0 1.0d0 1.0L0) ;Implementation has formats S, F, D, L.
@end example

@node *read-eval*, *read-suppress*, *read-default-float-format*, Reader Dictionary
@subsection *read-eval*                                                      [Variable]

@subsubheading  Value Type::

a @i{generalized boolean}.

@subsubheading  Initial Value:: 

@i{true}.

@subsubheading  Description::

If it is @i{true}, the @t{#.} @i{reader macro} has its normal effect.
Otherwise, that @i{reader macro} signals an error of @i{type} @b{reader-error}.

@subsubheading  See Also::

@b{*print-readably*}

@subsubheading  Notes::

If @b{*read-eval*} is @i{false} and @b{*print-readably*} is @i{true}, 
any @i{method} for @b{print-object} that would output a reference
to the @t{#.} @i{reader macro} either outputs something different
or signals an error of @i{type} @b{print-not-readable}.

@node *read-suppress*, *readtable*, *read-eval*, Reader Dictionary
@subsection *read-suppress*                                                  [Variable]

@subsubheading  Value Type::

a @i{generalized boolean}.

@subsubheading  Initial Value::

@i{false}.

@subsubheading  Description::

This variable is intended primarily to support the operation of the
read-time conditional notations @t{#+} and @t{#-}. It is important for the
@i{reader macros} which implement these notations
to be able to skip over the printed representation of an
@i{expression} despite the possibility that the syntax of the skipped
@i{expression} may not be entirely valid for the current implementation,
since @t{#+} and @t{#-} exist in order to allow the same program to be
shared among several @r{Lisp} implementations (including dialects other than @r{Common Lisp})
despite small incompatibilities of syntax.

If it is @i{false}, the @i{Lisp reader} operates normally.

If the @i{value} of @b{*read-suppress*} is @i{true},
      @b{read},
      @b{read-preserving-whitespace},
      @b{read-delimited-list},
  and @b{read-from-string}
all return a @i{primary value} of @b{nil} when they complete successfully;
however, they continue to parse the representation of an @i{object}
in the normal way, in order to skip over the @i{object},
and continue to indicate @i{end of file} in the normal way.
Except as noted below,
any @i{standardized} @i{reader macro}_2
that is defined to @i{read}_2 
a following @i{object} or @i{token} 
will do so,
but not signal an error if the @i{object}
read is not of an appropriate type or syntax.
The @i{standard syntax} and its associated @i{reader macros}
will not construct any new @i{objects} 
 (@i{e.g.}, when reading the representation of a @i{symbol},
      no @i{symbol} will be constructed or interned).

@table @asis

@item Extended tokens  
All extended tokens are completely uninterpreted.
Errors such as those that might otherwise be signaled due to
     detection of invalid @i{potential numbers},
     invalid patterns of @i{package markers},
 and invalid uses of the @i{dot} character are suppressed.

@item Dispatching macro characters (including @i{sharpsign})  
@i{Dispatching macro characters} continue to parse an infix numerical
argument, and invoke the dispatch function.  The @i{standardized}
@i{sharpsign} @i{reader macros} do not enforce any constraints
on either the presence of or the value of the numerical argument.

@item #=  
The @t{#=} notation is totally ignored.  It does not read
a following @i{object}. It produces no @i{object},
but is treated as @i{whitespace}_2.

@item ##  
The @t{##} notation always produces @b{nil}.
@end table

No matter what the @i{value} of @b{*read-suppress*},
parentheses still continue to delimit and construct @i{lists};
the @t{#(} notation continues to delimit @i{vectors};
and comments, @i{strings}, 
and the @i{single-quote} and @i{backquote} notations continue to be
interpreted properly.  Such situations as
@t{')},	@t{#<}, 
@t{#)}, and @t{#<@i{Space}>} continue to signal errors.

@subsubheading  Examples::

@example
 (let ((*read-suppress* t))
   (mapcar #'read-from-string
           '("#(foo bar baz)" "#P(:type :lisp)" "#c1.2"
             "#.(PRINT 'FOO)" "#3AHELLO" "#S(INTEGER)"
             "#*ABC" "#\GARBAGE" "#RALPHA" "#3R444")))
@result{}  (NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL)
@end example

@subsubheading  See Also::

@ref{read; read-preserving-whitespace}
,
{@ref{Syntax}}

@subsubheading  Notes::

@i{Programmers} and @i{implementations} that define additional
@i{macro characters} are strongly encouraged to make them respect
@b{*read-suppress*} just as @i{standardized} @i{macro characters} do.
That is, when the @i{value} of @b{*read-suppress*} is @i{true},
they should ignore type errors when reading a following @i{object}
and the @i{functions} that implement @i{dispatching macro characters}
should tolerate @b{nil} as their infix @i{parameter} value even if a numeric
value would ordinarily be required.

@node *readtable*, reader-error, *read-suppress*, Reader Dictionary
@subsection *readtable*                                                      [Variable]

@subsubheading  Value Type::

a @i{readtable}.

@subsubheading  Initial Value::

A @i{readtable} that conforms to the description of @r{Common Lisp} syntax in @ref{Syntax}.

@subsubheading  Description::

The @i{value} of @b{*readtable*} is called the @i{current readtable}.
It controls the parsing behavior of the @i{Lisp reader},
and can also influence the @i{Lisp printer} (@i{e.g.}, see the @i{function} @b{readtable-case}).

@subsubheading  Examples::

@example
 (readtablep *readtable*) @result{}  @i{true}
 (setq zvar 123) @result{}  123
 (set-syntax-from-char #\z #\' (setq table2 (copy-readtable))) @result{}  T
 zvar @result{}  123
 (setq *readtable* table2) @result{}  #<READTABLE>
 zvar @result{}  VAR
 (setq *readtable* (copy-readtable nil)) @result{}  #<READTABLE>
 zvar @result{}  123
@end example

@subsubheading  Affected By::

@b{compile-file},
@b{load}

@subsubheading  See Also::

@ref{compile-file}
,
@ref{load}
,
@ref{readtable}
,
@ref{The Current Readtable}

@node reader-error,  , *readtable*, Reader Dictionary
@subsection reader-error                                               [Condition Type]

@subsubheading  Class Precedence List::
@b{reader-error},
@b{parse-error},
@b{stream-error},
@b{error},
@b{serious-condition},
@b{condition},
@b{t}

@subsubheading  Description::

The @i{type} @b{reader-error} consists of
error conditions that are related to tokenization and parsing
done by the @i{Lisp reader}.

@subsubheading  See Also::

@ref{read; read-preserving-whitespace}
,
@ref{stream-error-stream}
,
@ref{Reader Concepts}

@c end of including dict-reader

@c %**end of chapter