io.tex

%Part{Io, Root = "CLM.MSS"}
%%%Chapter of Common Lisp Manual.  Copyright 1984, 1988, 1989 Guy L. Steele Jr.

\clearpage\def\pagestatus{FINAL PROOF}

\chapter{Input/Output}
\label{IO}

%\chapter{Система ввода/вывода}
%\label{IO}

Common Lisp provides a rich set of facilities for performing input/output.
All input/output operations are performed on streams of various kinds.
This chapter is devoted to stream data transfer operations.
Streams are discussed in chapter~\ref{STREAM}, and
ways of manipulating files through streams are discussed in
chapter~\ref{FILES}.

While there is provision for reading and writing binary data,
most of the I/O operations in Common Lisp read or write characters.
There are simple primitives for reading and writing single characters
or lines of data.  The \cdf{format} function can perform complex
formatting of output data, directed by a control string
in manner similar to a Fortran \cdf{FORMAT} statement
or a \cd{PL/I} \cd{PUT EDIT} statement.  The most useful I/O operations,
however, read and write printed representations of arbitrary
Lisp objects.

\section{Printed Representation of Lisp Objects}

Lisp objects in general are not text strings but complex data structures.
They have very different properties from text strings as a consequence of
their internal representation.  However, to make it possible to get at
and talk about Lisp objects, Lisp provides a representation of
most objects in the form of printed text; this is called the \emph{printed
representation}, which is used for input/output purposes and in the
examples throughout this book.  Functions such as \cdf{print} take a
Lisp object and send the characters of its printed representation to a
stream.  The collection of routines that does this is known as the
(Lisp) \emph{printer}.  The \cdf{read} function takes characters from a
stream, interprets them as a printed representation of a Lisp object,
builds that object, and returns it; the collection of routines
that does this is called the (Lisp) \emph{reader}.
\indexterm{printer}
\indexterm{printed representation}
\indexterm{reader}

\indexterm{printer}
\indexterm{printed representation}
\indexterm{reader}

Ideally, one could print a Lisp object and
then read the printed representation back in, and so obtain the same identical
object.  In practice this is difficult and for some purposes not even desirable.
Instead, reading a printed representation produces an object that is (with
obscure technical exceptions) \cdf{equal} to the originally printed object.

Most Lisp objects have more than one possible printed representation.
For example, the integer twenty-seven can be written in any of these ways:
\begin{lisp}
27~~~~27.~~~~\#o33~~~~\#x1B~~~~\#b11011~~~~\#.(* 3 3 3)~~~~81/3
\end{lisp}
A list of two symbols \cdf{A} and \cdf{B} can be printed in many ways:
\begin{lisp}
~~~~(A B)~~~~(a b)~~~~(~~a~~b~)~~~~({\Xbackslash}A |B|) \\
~~~~(|{\Xbackslash}A| \\
~~B \\
)
\end{lisp}
The last example, which is spread over three lines, may be ugly, but it
is legitimate.  In general, wherever whitespace is permissible in a printed
representation, any number of spaces and newlines may appear.

When \cdf{print} produces a printed representation, it must choose arbitrarily
from among many possible printed representations.  It attempts to choose
one that is readable.  There are a number of global variables that can
be used to control the actions of \cdf{print}, and a number of different
printing functions.

This section describes in detail what is the standard printed
representation for any Lisp object and also describes how \cdf{read} operates.

\subsection{What the Read Function Accepts}
\label{READER}
\indexterm{reader}

The purpose of the Lisp reader is to accept characters, interpret them
as the printed representation of a Lisp object, and construct and
return such an object.  The reader cannot accept everything that the
printer produces; for example, the printed representations of compiled
code objects cannot be read in.  However, the reader has
many features that are not used by the output of the printer at all,
such as comments, alternative representations, and convenient
abbreviations for frequently used but unwieldy constructs.  The reader is
also parameterized in such a way that it can be used as a lexical
analyzer for a more general user-written parser.

The reader is organized as a recursive-descent parser.
Broadly speaking,
the reader operates by reading a character from
the input stream and treating it in one of three ways.
Whitespace characters serve as separators but are otherwise
ignored.  Constituent and escape characters are accumulated
to make a \emph{token}, which is then interpreted as a number or symbol.
Macro characters trigger the invocation of functions (possibly
user-supplied) that can perform arbitrary parsing actions,
including recursive invocation of the reader.

More precisely,
when the reader is invoked, it reads a single character from the input stream
and dispatches according to the syntactic type of that character.
Every character that can appear in the input stream
must be of exactly one of the following kinds:
\emph{illegal},
\emph{whitespace},
\emph{constituent},
\emph{single escape},
\emph{multiple escape}, or
\emph{macro}.
Macro characters are further divided
into the types \emph{terminating} and \emph{non-terminating} (of tokens).
(Note that macro characters have nothing whatever to do with macros
in their operation.  There is a superficial similarity in that macros allow
the user to extend the syntax of Common Lisp at the level of forms,
while macro characters allow the user to extend the syntax at the
level of characters.)
Constituents additionally have one or more attributes,
the most important of which is \emph{alphabetic}; these attributes are discussed
further in section~\ref{PARSE-TOKENS-SECTION}.

The parsing of Common Lisp expressions is discussed in terms of these
syntactic character types because the types of individual characters
are not fixed
but may be altered by the user (see \cdf{set-syntax-from-char}
and \cdf{set-macro-character}).
The characters of the standard character set initially have the
syntactic types shown in table~\ref{Standard-Character-Syntax-Table}.
Note that
the brackets, braces, question mark, and exclamation point
(that is, \cd{{\Xlbracket}}, \cd{{\Xrbracket}}, \cd{{\Xlbrace}},
\cd{{\Xrbrace}}, \cd{?},
and \cd{!}) are normally defined to be constituents, but they
are not used for any purpose in standard Common Lisp syntax and do not occur
in the names of built-in Common Lisp functions or variables.
These characters are explicitly reserved to the user.
The primary intent
is that they be used as macro characters; but a user might choose,
for example, to make \cd{!} be a \emph{single escape} character
(as it is in Portable Standard Lisp).

\begin{table}
\caption{Standard Character Syntax Types}
\label{Standard-Character-Syntax-Table}

\begin{tabular*}{\textwidth}{@{}l@{\extracolsep{\fill}}ll@{}}
$\langle$tab$\rangle$\cd{~~}\emph{whitespace}&$\langle$page$\rangle$\cd{~~}\emph{whitespace}&$\langle$newline$\rangle$\cd{~~}\emph{whitespace} \\
$\langle$space$\rangle$\cd{~~}\emph{whitespace}&\cd{{\Xatsign}~~}\emph{constituent}&\cd{{\Xbq}~~}\emph{terminating macro} \\
\cd{!~~}\emph{constituent} *&\cd{A~~}\emph{constituent}&\cd{a~~}\emph{constituent} \\
\cd{"~~}\emph{terminating macro}&\cd{B~~}\emph{constituent}&\cd{b~~}\emph{constituent} \\
\cd{\#~~}\emph{non-terminating macro}&\cd{C~~}\emph{constituent}&\cd{c~~}\emph{constituent} \\
\cd{\$~~}\emph{constituent}&\cd{D~~}\emph{constituent}&\cd{d~~}\emph{constituent} \\
\cd{\%~~}\emph{constituent}&\cd{E~~}\emph{constituent}&\cd{e~~}\emph{constituent} \\
\cd{\&~~}\emph{constituent}&\cd{F~~}\emph{constituent}&\cd{f~~}\emph{constituent} \\
\cd{'~~}\emph{terminating macro}&\cd{G~~}\emph{constituent}&\cd{g~~}\emph{constituent} \\
\cd{(~~}\emph{terminating macro}&\cd{H~~}\emph{constituent}&\cd{h~~}\emph{constituent} \\
\cd{)~~}\emph{terminating macro}&\cd{I~~}\emph{constituent}&\cd{i~~}\emph{constituent} \\
\cd{*~~}\emph{constituent}&\cd{J~~}\emph{constituent}&\cd{j~~}\emph{constituent} \\
\cd{+~~}\emph{constituent}&\cd{K~~}\emph{constituent}&\cd{k~~}\emph{constituent} \\
\cd{,~~}\emph{terminating macro}&\cd{L~~}\emph{constituent}&\cd{l~~}\emph{constituent} \\
\cd{-~~}\emph{constituent}&\cd{M~~}\emph{constituent}&\cd{m~~}\emph{constituent} \\
\cd{.~~}\emph{constituent}&\cd{N~~}\emph{constituent}&\cd{n~~}\emph{constituent} \\
\cd{/~~}\emph{constituent}&\cd{O~~}\emph{constituent}&\cd{o~~}\emph{constituent} \\
\cd{0~~}\emph{constituent}&\cd{P~~}\emph{constituent}&\cd{p~~}\emph{constituent} \\
\cd{1~~}\emph{constituent}&\cd{Q~~}\emph{constituent}&\cd{q~~}\emph{constituent} \\
\cd{2~~}\emph{constituent}&\cd{R~~}\emph{constituent}&\cd{r~~}\emph{constituent} \\
\cd{3~~}\emph{constituent}&\cd{S~~}\emph{constituent}&\cd{s~~}\emph{constituent} \\
\cd{4~~}\emph{constituent}&\cd{T~~}\emph{constituent}&\cd{t~~}\emph{constituent} \\
\cd{5~~}\emph{constituent}&\cd{U~~}\emph{constituent}&\cd{u~~}\emph{constituent} \\
\cd{6~~}\emph{constituent}&\cd{V~~}\emph{constituent}&\cd{v~~}\emph{constituent} \\
\cd{7~~}\emph{constituent}&\cd{W~~}\emph{constituent}&\cd{w~~}\emph{constituent} \\
\cd{8~~}\emph{constituent}&\cd{X~~}\emph{constituent}&\cd{x~~}\emph{constituent} \\
\cd{9~~}\emph{constituent}&\cd{Y~~}\emph{constituent}&\cd{y~~}\emph{constituent} \\
\cd{:~~}\emph{constituent}&\cd{Z~~}\emph{constituent}&\cd{z~~}\emph{constituent} \\
\cd{;~~}\emph{terminating macro}&\cd{{\Xlbracket}~~}\emph{constituent} *&\cd{{\Xlbrace}~~}\emph{constituent} * \\
\cd{<~~}\emph{constituent}&\cd{{\Xbackslash}~~}\emph{single escape}&\cd{|~~}\emph{multiple escape} \\
\cd{=~~}\emph{constituent}&\cd{{\Xrbracket}~~}\emph{constituent} *&\cd{{\Xrbrace}~~}\emph{constituent} * \\
\cd{>~~}\emph{constituent}&\cd{{\Xcircumflex}~~}\emph{constituent}&\cd{{\Xtilde}~~}\emph{constituent} \\
\cd{?~~}\emph{constituent} *&\cd{{\Xunderscore}~~}\emph{constituent}&$\langle$rubout$\rangle$\cd{~~}\emph{constituent} \\
$\langle$backspace$\rangle$\cd{~~}\emph{constituent}&$\langle$return$\rangle$\cd{~~}\emph{whitespace}&$\langle$linefeed$\rangle$\cd{~~}\emph{whitespace}
\end{tabular*}

\vfill
\begin{small}
\noindent
The characters marked with an asterisk are initially constituents
but are reserved to the user for use as macro characters or for
any other desired purpose.
\end{small}
\end{table}

The algorithm performed by the Common Lisp reader is roughly as follows:

\begingroup\leftmargini 1.5em
\begin{enumerate}
\item
If at end of file, perform end-of-file processing (as specified
by the caller of the \cdf{read} function).
Otherwise,
read one character from the input stream, call it \emph{x}, and
dispatch according to the syntactic type of \emph{x} to one
of steps~\ref{READER-ILLEGAL} to~\ref{READER-CONSTITUENT}.
\label{READER-START}

\item
If \emph{x} is an \emph{illegal} character, signal an error.
\label{READER-ILLEGAL}

\item
If \emph{x} is a \emph{whitespace} character,
then discard it and go back to step~\ref{READER-START}.
\label{READER-WHITESPACE}

\item
If \emph{x} is a \emph{macro} character (at this point the
distinction between \emph{terminating} and \emph{non-terminating} macro characters
does not matter), then execute the function associated
with that character.  The function may return zero values or one value
(see \cdf{values}).

The macro-character function may of course read characters from the input
stream; if it does, it will see those characters following the macro
character.  The function may even invoke the reader recursively.
This is how the macro character \cd{(} constructs a list:
by invoking the reader recursively to read the elements of the list.

If one value is returned, then return that value as the result of the
read operation; the algorithm is done.
If zero values are returned, then go back to step~\ref{READER-START}.

\item
If \emph{x} is a \emph{single escape} character (normally \cd{{\Xbackslash}}),
then read the next character and call it \emph{y}
(but if at end of file, signal an error instead).
Ignore the usual syntax of \emph{y}
and pretend it is a \emph{constituent} whose only attribute is
\emph{alphabetic}.

For the purposes of \cdf{readtable-case}, \emph{y} is not replaceable.

Use \emph{y} to begin a token, and go to step~\ref{READER-PLAIN-TOKEN}.

\item
If \emph{x} is a \emph{multiple escape} character (normally \cd{|}),
then begin a token (initially
containing no characters) and go to step~\ref{READER-MULTI-TOKEN}.

\item
If \emph{x} is a \emph{constituent} character, then it begins an extended token.
\label{READER-CONSTITUENT}\relax
After the entire token is read in, it will be interpreted
either as representing a Lisp object such as a symbol or number
(in which case that object is returned as the result of the read operation),
or as being of illegal syntax (in which case an error is signaled).

The case of \emph{x\/} should not be altered; instead,
\emph{x} should be regarded as replaceable.

Use \emph{x} to begin a token, and go on to step~\ref{READER-PLAIN-TOKEN}.

\item
(At this point a token is being accumulated, and an even number
of \emph{multiple escape} characters have been encountered.)
If at end of file, go to step~\ref{READER-TOKEN-END}.
Otherwise, read a character (call it \emph{y}), and
perform one of the following actions according to its syntactic type:
\label{READER-PLAIN-TOKEN}

\begin{itemize}
\item
If \emph{y} is a \emph{constituent} or \emph{non-terminating macro},
then do the following.

The case of \emph{y\/} should not be altered; instead,
\emph{y} should be regarded as replaceable.

Append \emph{y} to the token being built,
and repeat step~\ref{READER-PLAIN-TOKEN}.

\item
If \emph{y} is a \emph{single escape} character, then read the next character
and call it \emph{z}
(but if at end of file, signal an error instead).
Ignore the usual syntax of \emph{z}
and pretend it is a \emph{constituent} whose only attribute is
\emph{alphabetic}.

For the purposes of \cdf{readtable-case}, \emph{z} is not replaceable.

Append \emph{z} to the token being built,
and repeat step~\ref{READER-PLAIN-TOKEN}.

\item
If \emph{y} is a \emph{multiple escape} character,
then go to step~\ref{READER-MULTI-TOKEN}.

\item
If \emph{y} is an \emph{illegal} character, signal an error.

\item
If \emph{y} is a \emph{terminating macro} character, it terminates
the token.  First ``unread'' the character \emph{y}
(see \cdf{unread-char}), then go to step~\ref{READER-TOKEN-END}.

\item
If \emph{y} is a \emph{whitespace} character, it terminates
the token.  First ``unread'' \emph{y}
if appropriate (see \cdf{read-preserving-whitespace}),
then go to step~\ref{READER-TOKEN-END}.

\end{itemize}

\item
(At this point a token is being accumulated, and an odd number
of \emph{multiple escape} characters have been encountered.)
If at end of file, signal an error.
Otherwise, read a character (call it \emph{y}), and
perform one of the following actions according to its syntactic type:
\label{READER-MULTI-TOKEN}

\begin{itemize}
\item
If \emph{y} is a \emph{constituent}, \emph{macro}, or \emph{whitespace}
character, then ignore the usual syntax of that character
and pretend it is a \emph{constituent} whose only attribute is
\emph{alphabetic}.

For the purposes of \cdf{readtable-case}, \emph{y} is not replaceable.

Append \emph{y} to the token being built,
and repeat step~\ref{READER-MULTI-TOKEN}.

\item
If \emph{y} is a \emph{single escape} character, then read the next character
and call it \emph{z}
(but if at end of file, signal an error instead).
Ignore the usual syntax of \emph{z}
and pretend it is a \emph{constituent} whose only attribute is
\emph{alphabetic}.

For the purposes of \cdf{readtable-case}, \emph{z} is not replaceable.

Append \emph{z} to the token being built,
and repeat step~\ref{READER-MULTI-TOKEN}.

\item
If \emph{y} is a \emph{multiple escape} character,
then go to step~\ref{READER-PLAIN-TOKEN}.

\item
If \emph{y} is an \emph{illegal} character, signal an error.

\end{itemize}

\item
An entire token has been accumulated.
\begin{newer}
X3J13 voted in June 1989 \issue{READ-CASE-SENSITIVITY} to introduce
\cdf{readtable-case}.  If the accumulated token
is to be interpreted as a symbol, any case conversion of replaceable
characters should be performed at this point according to the value
of the \cdf{readtable-case} slot of the current readtable (the value
of \cdf{*readtable*}).
\end{newer}
Interpret the token as representing
a Lisp object and return that object as the result
of the read operation, or signal an error if the token
is not of legal syntax.
\begin{newer}
X3J13 voted in March 1989 \issue{CHARACTER-PROPOSAL}
to specify that implementation-defined
attributes may be removed from the characters of a symbol token
when constructing the print name.
It is implementation-dependent which attributes are removed.
\end{newer}
\label{READER-TOKEN-END}

\end{enumerate}
\endgroup

As a rule, a \emph{single escape} character never stands for itself but always
serves to cause the following character to be treated as a simple alphabetic
character.  A \emph{single escape} character can be included in a token only
if preceded by another \emph{single escape} character.

A \emph{multiple escape} character also never stands for itself.  The characters
between a pair of \emph{multiple escape} characters are all treated as
simple alphabetic characters, except that \emph{single escape} and
\emph{multiple escape} characters must nevertheless be preceded by
a \emph{single escape} character to be included.

\subsection{Parsing of Numbers and Symbols}
\label{PARSE-TOKENS-SECTION}

When an extended token is read, it is interpreted as a number or symbol.
In general, the token is interpreted as a number if it satisfies
the syntax for numbers specified in table~\ref{NUMBER-SYNTAX-TABLE};
this is discussed in more detail below.

The characters of the extended token may serve various syntactic
functions as shown
in table~\ref{Standard-Readtable-Attributes-Table}, but it must be
remembered that any character included in a token under the control
of an escape character is treated as \emph{alphabetic} rather than
according to the attributes shown in the table.
One consequence of this rule is that a whitespace, macro, or escape
character will always be treated as alphabetic within an extended token
because such a character cannot be included in an extended
token except under the control of an escape character.

To allow for extensions to the syntax of numbers, a
syntax for \emph{potential numbers} is defined in Common Lisp that is
more general than the actual syntax for numbers.
Any token that is not a potential number and does not consist
entirely of dots will always be taken to be a symbol,
now and in the future; programs may rely on this fact.
Any token that is a potential number but does not fit the
actual number syntax defined below is a \emph{reserved token} and
has an implementation-dependent interpretation;
an implementation may signal an error, quietly treat the token
as a symbol, or take some other action.  Programmers should avoid
the use of such reserved tokens.  (A symbol whose name looks like a reserved
token can always be written using one or more escape characters.)

Just as \emph{bignum} is the standard term used by Lisp implementors for
very large integers, and \emph{flonum} (rhymes with ``low hum'') refers
to a floating-point number, the term \emph{potnum} has been used widely
as an abbreviation for ``potential number.''  ``Potnum'' rhymes with ``hot rum.''

\goodbreak

A token is a potential number if it satisfies the following
requirements:

\begin{table}[t]
\caption{Actual Syntax of Numbers}
\label{NUMBER-SYNTAX-TABLE}
\tabbingsep=0pt
\normalsize
\begin{tabbing}
\emph{number} ::= \emph{integer} {\Mor} \emph{ratio} {\Mor} \emph{floating-point-number} \\
\emph{integer} ::= \Mopt{\emph{sign}} \Mplus{\emph{digit}} \Mopt{\emph{decimal-point}} \\
\emph{ratio} ::= \Mopt{\emph{sign}} \Mplus{\emph{digit}} \cdf{/} \Mplus{\emph{digit}} \\
\emph{floating-point-number} ::=\= \Mopt{\emph{sign}} \Mstar{\emph{digit}} \emph{decimal-point} \Mplus{\emph{digit}} \Mopt{\emph{exponent}} \\
\>{\Mor} \'\Mopt{\emph{sign}} \Mplus{\emph{digit}} \Mopt{\emph{decimal-point}
\Mstar{\emph{digit}}} \emph{exponent} \\ \emph{sign} ::= \cdf{+} {\Mor} \cdf{-} \\
\emph{decimal-point} ::= \cd{.} \\
\emph{digit} ::= \cd{0} {\Mor} \cd{1} {\Mor} \cd{2} {\Mor} \cd{3} {\Mor} \cd{4}
         {\Mor} \cd{5} {\Mor} \cd{6} {\Mor} \cd{7} {\Mor} \cd{8} {\Mor} \cd{9} \\
\emph{exponent} ::= \emph{exponent-marker} \Mopt{\emph{sign}} \Mplus{\emph{digit}} \\
\emph{exponent-marker} ::= \cdf{e} {\Mor} \cdf{s} {\Mor} \cdf{f} {\Mor} \cdf{d} {\Mor} \cdf{l}
                   {\Mor} \cdf{E} {\Mor} \cdf{S} {\Mor} \cdf{F} {\Mor} \cdf{D} {\Mor} \cdf{L}
\end{tabbing}
\end{table}

\begin{itemize}
\item
It consists entirely of digits, signs (\cdf{+} or \cdf{-}),
ratio markers (\cdf{/}), decimal points (\cd{.}), extension characters
(\cd{{\Xcircumflex}} or \cd{{\Xunderscore}}), and number markers.  (A number marker is
a letter.  Whether a letter may be treated as a number marker depends
on context, but no letter that is adjacent to another letter may ever be
treated as a number marker.  Floating-point exponent markers are instances
of number markers.)

\item
It contains at least one digit.  (Letters may be considered to be
digits, depending on the value of \cd{*read-base*}, but only
in tokens containing no decimal points.)

\item
It begins with a digit, sign, decimal point, or extension character.

\item
It does not end with a sign.
\end{itemize}
As examples, the following tokens are potential numbers,
but they are \emph{not} actually numbers as defined below, and so are
reserved tokens.  (They do indicate some interesting possibilities
for future extensions.)

\begin{table}
\caption{Standard Constituent Character Attributes}
\label{Standard-Readtable-Attributes-Table}

\begin{tabular*}{\textwidth}{@{\extracolsep{\fill}}l@{\extracolsep{\fill}}lllll@{}}
\cd{!}&\emph{alphabetic}&$\langle$page$\rangle$&\emph{illegal}&$\langle$backspace$\rangle$&\emph{illegal} \\
\cd{"}&\emph{alphabetic} *&$\langle$return$\rangle$&\emph{illegal} *&$\langle$tab$\rangle$&\emph{illegal} * \\
\cd{\#}&\emph{alphabetic} *&$\langle$space$\rangle$&\emph{illegal} *&$\langle$newline$\rangle$&\emph{illegal} * \\
\cd{\$}&\emph{alphabetic}&$\langle$rubout$\rangle$&\emph{illegal}&$\langle$linefeed$\rangle$&\emph{illegal} * \\
\cd{\%}&\emph{alphabetic}&\cd{.}&\multicolumn{3}{l}{\emph{alphabetic}, \emph{dot}, \emph{decimal point}}\\
\cd{\&}&\emph{alphabetic}&\cdf{+}&\multicolumn{3}{l}{\emph{alphabetic}, \emph{plus sign}} \\
\cd{'}&\emph{alphabetic} *&\cdf{-}&\multicolumn{3}{l}{\emph{alphabetic}, \emph{minus sign}} \\
\cd{(}&\emph{alphabetic} *&\cdf{*}&\emph{alphabetic} \\
\cd{)}&\emph{alphabetic} *&\cdf{/}&\multicolumn{3}{l}{\emph{alphabetic}, \emph{ratio marker}} \\
\cd{,}&\emph{alphabetic} *&\cd{{\Xatsign}}&\emph{alphabetic} \\
\cd{0}&\emph{alphadigit}&\cdf{A}, \cdf{a}&\emph{alphadigit} \\
\cd{1}&\emph{alphadigit}&\cdf{B}, \cdf{b}&\emph{alphadigit} \\
\cd{2}&\emph{alphadigit}&\cdf{C}, \cdf{c}&\emph{alphadigit} \\
\cd{3}&\emph{alphadigit}&\cdf{D}, \cdf{d}&\multicolumn{3}{l}{\emph{alphadigit}, \emph{double-float exponent marker}} \\
\cd{4}&\emph{alphadigit}&\cdf{E}, \cdf{e}&\multicolumn{3}{l}{\emph{alphadigit}, \emph{float exponent marker}} \\
\cd{5}&\emph{alphadigit}&\cdf{F}, \cdf{f}&\multicolumn{3}{l}{\emph{alphadigit}, \emph{single-float exponent marker}} \\
\cd{6}&\emph{alphadigit}&\cdf{G}, \cdf{g}&\emph{alphadigit} \\
\cd{7}&\emph{alphadigit}&\cdf{H}, \cdf{h}&\emph{alphadigit} \\
\cd{8}&\emph{alphadigit}&\cdf{I}, \cdf{i}&\emph{alphadigit} \\
\cd{9}&\emph{alphadigit}&\cdf{J}, \cdf{j}&\emph{alphadigit} \\
\cd{:}&\emph{package marker}~~~~~~&\cdf{K}, \cdf{k}&\emph{alphadigit} \\
\cd{;}&\emph{alphabetic} *&\cdf{L}, \cdf{l}&\multicolumn{3}{l}{\emph{alphadigit}, \emph{long-float exponent marker}} \\
\cdf{<}&\emph{alphabetic}&\cdf{M}, \cdf{m}&\emph{alphadigit} \\
\cdf{=}&\emph{alphabetic}&\cdf{N}, \cdf{n}&\emph{alphadigit} \\
\cdf{>}&\emph{alphabetic}&\cdf{O}, \cdf{o}&\emph{alphadigit} \\
\cd{?}&\emph{alphabetic}&\cdf{P}, \cdf{p}&\emph{alphadigit} \\
\cd{{\Xlbracket}}&\emph{alphabetic}&\cdf{Q}, \cdf{q}&\emph{alphadigit} \\
\cd{{\Xbackslash}}&\emph{alphabetic} *&\cdf{R}, \cdf{r}&\emph{alphadigit} \\
\cd{{\Xrbracket}}&\emph{alphabetic}&\cdf{S}, \cdf{s}&\multicolumn{3}{l}{\emph{alphadigit}, \emph{short-float exponent marker}} \\
\cd{{\Xcircumflex}}&\emph{alphabetic}&\cdf{T}, \cdf{t}&\emph{alphadigit} \\
\cd{{\Xunderscore}}&\emph{alphabetic}&\cdf{U}, \cdf{u}&\emph{alphadigit} \\
\cd{{\Xbq}}&\emph{alphabetic} *&\cdf{V}, \cdf{v}&\emph{alphadigit} \\
\cd{{\Xlbrace}}&\emph{alphabetic}&\cdf{W}, \cdf{w}&\emph{alphadigit} \\
\cd{|}&\emph{alphabetic} *&\cdf{X}, \cdf{x}&\emph{alphadigit} \\
\cd{{\Xrbrace}}&\emph{alphabetic}&\cdf{Y}, \cdf{y}&\emph{alphadigit} \\
\cd{{\Xtilde}}&\emph{alphabetic}&\cdf{Z}, \cdf{z}&\emph{alphadigit} \\
\end{tabular*}

\vfill
\begin{footnotesize}
\noindent
These interpretations apply only to characters whose
syntactic type is \emph{constituent}.  Entries marked
with an asterisk are normally shadowed because the characters
are of syntactic type
\emph{whitespace}, \emph{macro}, \emph{single escape}, or \emph{multiple escape}.
An \emph{alphadigit} character is interpreted as a
digit if it is a valid digit in the radix specified by {\small \cd{*read-base*}};
otherwise it is alphabetic.
Characters with an \emph{illegal} attribute can never appear in
a token except under the control of an escape character.
\end{footnotesize}
\end{table}

\begin{lisp}
\hskip 0.2\linewidth\=\hskip 0.2\linewidth\=\hskip 0.2\linewidth\=\hskip 0.2\linewidth\=\kill
1b5000\>777777q\>1.7J\>-3/4+6.7J\>12/25/83 \\
27{\Xcircumflex}19\>3{\Xcircumflex}4/5\>6//7\>3.1.2.6\>{\Xcircumflex}-43{\Xcircumflex} \\
3.141{\Xunderscore}592{\Xunderscore}653{\Xunderscore}589{\Xunderscore}793{\Xunderscore}238{\Xunderscore}4\>\>\>-3.7+2.6i-6.17j+19.6k
\end{lisp}
The following tokens are \emph{not} potential numbers but are always
treated as symbols:
\begin{lisp}
\hskip 0.2\linewidth\=\hskip 0.2\linewidth\=\hskip 0.2\linewidth\=\hskip 0.2\linewidth\=\kill
/\>/5\>+\>1+\>1- \\*
foo+\>ab.cd\>{\Xunderscore}\>{\Xcircumflex}\>{\Xcircumflex}/-
\end{lisp}
The following tokens are potential numbers if the value of
\cd{*read-base*} is \cd{16} (an abnormal situation), but they are
always treated as symbols if the value of \cd{*read-base*}
is \cd{10} (the usual value):
\begin{lisp}
\hskip 0.2\linewidth\=\hskip 0.2\linewidth\=\hskip 0.2\linewidth\=\hskip 0.2\linewidth\=\kill
bad-face\>25-dec-83\>a/b\>fad{\Xunderscore}cafe\>f{\Xcircumflex}
\end{lisp}
It is possible for there to be an ambiguity as to whether
a letter should be treated as a digit or as a number marker.
In such a case, the letter is always treated as a digit
rather than as a number marker.

Note that the printed representation for a potential
number may not contain any escape characters.
An escape character robs the following character of all syntactic
qualities, forcing it to be strictly alphabetic and therefore unsuitable
for use in a potential number.  For example,
all of the following representations are interpreted as symbols, not numbers:
\begin{lisp}
{\Xbackslash}256~~~25{\Xbackslash}64~~~1.0{\Xbackslash}E6~~~|100|~~~3{\Xbackslash}.14159~~~|3/4|~~~3{\Xbackslash}/4~~~5||
\end{lisp}
In each case, removing the escape character(s) would allow the token
to be treated as a number.

If a potential number can in fact
be interpreted as a number according to the BNF
syntax in table~\ref{NUMBER-SYNTAX-TABLE}, then a number object of the
appropriate type is constructed and returned.  It should be noted that in
a given implementation it may be that not all tokens conforming to the
actual syntax for numbers can actually be converted into number objects.
For example, specifying too large or too small an exponent for a floating-point
number may make the number impossible to represent in the implementation.
Similarly, a ratio with denominator zero (such as \cd{-35/000})
cannot be represented in \emph{any} implementation.
In any such circumstance where
a token with the syntax of a number cannot be converted to an internal
number object, an error is signaled.  (On the other hand, an error
must not be signaled for specifying too many significant digits
for a floating-point number; an appropriately truncated or rounded
value should be produced.)

There is an omission in the syntax of numbers
as described in table~\ref{NUMBER-SYNTAX-TABLE},
in that the syntax does not account for the possible
use of letters as digits.
The radix used for reading integers and ratios is normally decimal.
However, this radix is actually determined by the value of
the variable \cd{*read-base*}, whose initial value is \cd{10}.
\cd{*read-base*} may take on any integral value between \cd{2} and \cd{36};
let this value be \emph{n}.  Then a token \emph{x} is interpreted as
an integer or ratio in base \emph{n} if it could be properly
so interpreted in the syntax \cd{\#\emph{n}R\emph{x}}
(see section~\ref{SHARP-SIGN-MACRO-CHARACTER-SECTION}).
So, for example, if the value of \cd{*read-base*} is \cd{16},
then the printed representation
\begin{lisp}
(a small face in a bad place)
\end{lisp}
would be interpreted as if the following representation had
been read with \cd{*read-base*} set to \cd{10}:
\begin{lisp}
(10 small 64206 in 10 2989 place)
\end{lisp}
because four of the seven tokens in the list can be interpreted
as hexadecimal numbers.  This facility is intended to be used
in reading files of data that for some reason contain numbers
not in decimal radix; it may also be used for reading programs
written in Lisp dialects (such as MacLisp) whose default number radix is not
decimal.  Non-decimal constants in Common Lisp programs
or portable Common Lisp data files should be written using
\cd{\#O}, \cd{\#X}, \cd{\#B}, or \cd{\#\emph{n}R} syntax.

When \cd{*read-base*} has a value greater than \cd{10}, an ambiguity
is introduced into the actual syntax for numbers because a letter can serve
as either a digit or an exponent marker; a simple example is \cd{1E0}
when the value of \cd{*read-base*} is \cd{16}.  The ambiguity is resolved
in accordance with the general principle that interpretation
as a digit is preferred to interpretation as a number marker.
The consequence in this case is that
if a token can be interpreted as either an integer or a floating-point
number, then it is taken to be an integer.

If a token consists solely of dots (with no escape characters), then an
error is signaled, except in one circumstance: if the token is a single
dot and occurs in a situation appropriate to ``dotted list'' syntax,
then it is accepted as a part of such syntax.  Signaling an error
catches not only misplaced dots in dotted list syntax but also
lists that were truncated by \cd{*print-length*} cutoff,
because such lists end with a three-dot sequence (\cd{...}).
Examples:
\begin{lisp}
~~~~~~~~~~~~~~~~\=\kill
(a . b)\>;\textrm{A dotted pair of \cdf{a} and \cdf{b}} \\
(a.b)\>;\textrm{A list of one element, the symbol named \cd{a.b}} \\
(a. b)\>;\textrm{A list of two elements \cd{a.} and \cdf{b}} \\
(a .b)\>;\textrm{A list of two elements \cdf{a} and \cd{.b}} \\
(a {\Xbackslash}. b)\>;\textrm{A list of three elements \cdf{a}, \cd{.}, and \cdf{b}} \\
(a |.| b)\>;\textrm{A list of three elements \cdf{a}, \cd{.}, and \cdf{b}} \\
(a {\Xbackslash}... b)\>;\textrm{A list of three elements \cdf{a}, \cd{...}, and \cdf{b}} \\
(a |...| b)\>;\textrm{A list of three elements \cdf{a}, \cd{...}, and \cdf{b}} \\
(a b . c)\>;\textrm{A dotted list of \cdf{a} and \cdf{b} with \cdf{c} at the end} \\
.iot\>;\textrm{The symbol whose name is \cd{.iot}} \\
(. b)\>;\textrm{Illegal; an error is signaled} \\
(a .)\>;\textrm{Illegal; an error is signaled} \\
(a .. b)\>;\textrm{Illegal; an error is signaled} \\
(a . . b)\>;\textrm{Illegal; an error is signaled} \\
(a b c ...)\>;\textrm{Illegal; an error is signaled}
\end{lisp}

In all other cases, the token is construed to be the name of a symbol.
If there are any package markers
(colons) in the token, they divide the token into pieces used to
control the lookup and creation of the symbol.

\begin{obsolete}
If there is a single package marker, and it occurs at the beginning of the
token, then the token is interpreted as a keyword, that is, a symbol in the
\cdf{keyword} package.  The part of the token after the package marker must
not have the syntax of a number.

If there is a single package marker not at the beginning or end of the
token, then it divides the token into two parts.  The first part
specifies a package; the second part is the name of an external symbol
available in that package.  Neither of the two parts may have the syntax
of a number.

If there are two adjacent package markers not at the beginning or end of the
token, then they divide the token into two parts.  The first part
specifies a package; the second part is the name of a symbol within
that package (possibly an internal symbol).
Neither of the two parts may have the syntax of a number.
\end{obsolete}

\begin{new}
X3J13 voted in March 1988
\issue{COLON-NUMBER}
to clarify that, in the situations described in the
preceding three paragraphs, the restriction on the syntax of the parts should
be strengthened:  none of the parts may have the syntax of even
a \emph{potential} number.  Tokens such as \cd{:3600}, \cd{:1/2},
and \cd{editor:3.14159} were already ruled out; this clarification further
declares that such tokens as \cd{:2{\Xcircumflex} 3}, \cd{compiler:1.7J},
and \cd{Christmas:12/25/83} are also in error and therefore should not be used
in portable programs.  Implementations may differ in their treatment of
such package-marked potential numbers.
\end{new}

If a symbol token contains no package markers, then the entire token
is the name of the symbol.  The symbol is looked up in
the default package, which is the value
of the variable \cdf{*package*}.

All other patterns of package markers,
including the cases where there are more than two
package markers or where a package marker appears at the end of the token,
at present do not mean anything in Common Lisp (see chapter~\ref{XPACK}).
It is therefore currently an error to use such patterns in a Common Lisp program.
The valid patterns for tokens may be summarized as follows:
\begin{tabbing}
\hskip 8pc\=\kill
\emph{nnnnn}\>a number \\
\emph{xxxxx}\>a symbol in the current package \\
\cd{:\emph{xxxxx}}\>a symbol in the keyword package \\
\cd{\emph{ppppp}:\emph{xxxxx}}\>an external symbol in the \emph{ppppp} package \\
\cd{\emph{ppppp}::\emph{xxxxx}}\>a (possibly internal) symbol in the \emph{ppppp} package
\end{tabbing}
where \emph{nnnnn} has the syntax of a number, and \emph{xxxxx} and \emph{ppppp} do
not have the syntax of a number.

\begin{new}
In accordance with the X3J13 decision noted above
\issue{COLON-NUMBER}, \emph{xxxxx} and \emph{ppppp} may not have the syntax of even
a potential number.
\end{new}

\begin{defun}[Variable]
*read-base*

The value of \cd{*read-base*} controls the interpretation of tokens
by \cdf{read} as being integers or ratios.  Its value is the radix
in which integers and ratios are to be read; the value may be any integer
from \cd{2} to \cd{36} (inclusive) and is normally \cd{10} (decimal radix).
Its value affects only the reading of integers and ratios.
In particular, floating-point numbers are always read in decimal radix.
The value of \cd{*read-base*} does not affect the radix for rational numbers
whose radix is explicitly indicated by
\cd{\#O}, \cd{\#X}, \cd{\#B}, or \cd{\#\emph{n}R} syntax
or by a trailing decimal point.

Care should be taken when setting \cd{*read-base*} to a value larger
than \cd{10}, because tokens that would normally be interpreted as
symbols may be interpreted as numbers instead.  For example,
with \cd{*read-base*} set to \cd{16} (hexadecimal radix), variables
with names such as \cdf{a}, \cdf{b}, \cdf{f}, \cdf{bad}, and \cdf{face}
will be treated by the reader as numbers (with decimal values
10, 11, 15, 2989, and 64206, respectively).  The ability to alter
the input radix is provided in Common Lisp primarily for the purpose of
reading data files in special operatorats, rather than for the purpose of altering
the default radix in which to read programs.  The user is strongly
encouraged to use \cd{\#O}, \cd{\#X}, \cd{\#B}, or \cd{\#\emph{n}R} syntax when
notating non-decimal constants in programs.
\end{defun}

\begin{defun}[Variable]
*read-suppress*

When the value of \cd{*read-suppress*} is {\nil}, the Lisp reader
operates normally.  When it is not {\nil}, then most of the interesting
operations of the reader are suppressed; input characters are parsed,
but much of what is read is not interpreted.

The primary purpose of \cd{*read-suppress*} is to support the operation of
the read-time conditional constructs \cd{\#+} and \cd{\#-}
(see section~\ref{SHARP-SIGN-MACRO-CHARACTER-SECTION}).  It is important for these
constructs to be able to skip over the printed representation of a Lisp
expression despite the possibility that the syntax of the skipped
expression may not be entirely legal for the current implementation; this
is because a primary application of \cd{\#+} and \cd{\#-} is to allow the
same program to be shared among several Lisp implementations despite
small incompatibilities of syntax.

A non-{\nil} value of \cd{*read-suppress*} has the following specific
effects on the Common Lisp reader:
\begin{itemize}
\item
All extended tokens are completely uninterpreted.  It matters not
whether the token looks like a number, much less like a valid number;
the pattern of package markers also does not matter.  An extended token
is simply discarded and treated as if it were {\nil}; that is, reading
an extended token when \cd{*read-suppress*} is non-{\nil} simply returns {\nil}.
(One consequence of this is that the error concerning improper
dotted-list syntax will not be signaled.)

\item
Any standard
\cd{\#} macro-character construction that requires, permits, or disallows
an infix numerical argument, such as \cd{\#\emph{n}R}, will not enforce
any constraint on the presence, absence, or value of such an argument.

\item
The \cd{\#{\Xbackslash}} construction always produces the value {\nil}.
It will not signal an error even if an unknown character name is seen.

\item
Each of the \cd{\#B}, \cd{\#O}, \cd{\#X}, and \cd{\#R}
constructions always scans over a following token and produces the value {\nil}.
It will not signal an error even if the token does not have the syntax
of a rational number.

\item
The \cd{\#*} construction always scans over a following token and
produces the value {\nil}.
It will not signal an error even if the token does not consist solely
of the characters \cd{0} and \cd{1}.
\end{itemize}

\begin{itemize}
\item
The \cd{\#.} construction reads the following
form (in suppressed mode, of course) but does not evaluate it.
The form is discarded and {\nil} is produced.
\end{itemize}


\begin{itemize}
\item
Each of the \cd{\#A}, \cd{\#S}, and \cd{\#:}
constructions reads the following
form (in suppressed mode, of course) but does not interpret it in any way;
it need not even be a list in the case of \cd{\#S}, or a symbol
in the case of \cd{\#:}.  The form is discarded and {\nil} is produced.

\item
The \cd{\#=} construction is totally ignored.  It does not read
a following form.  It produces no object, but is treated as whitespace.

\item
The \cd{\#\#} construction always produces {\nil}.
\end{itemize}
Note that, no matter what the value of \cd{*read-suppress*},
parentheses still continue to delimit (and construct) lists;
the \cd{\#(} construction continues to delimit vectors;
and comments, strings, and the quote and backquote constructions continue to be
interpreted properly.  Furthermore, such situations as
\cd{')},
\cd{\#<}, \cd{\#)}, and \cd{\#$\langle$\textrm{space}$\rangle$} continue to signal errors.

In some cases, it may be appropriate for a user-written macro-character
definition to check the value of \cd{*read-suppress*} and to avoid certain
computations or side effects if its value is not {\nil}.
\end{defun}

\begin{defun}[Variable]
*read-eval*

Default value of \cd{*read-eval*} is \cdf{t}.
If \cd{*read-eval*} is false, the \cd{\#.} reader macro signals an error.

Printing is also affected.  If
  \cd{*read-eval*} is false and \cd{*print-readably*} is true, any \cdf{print-object}
  method that would otherwise output a \cd{\#.} reader macro must either output something
  different or signal an error of type \cdf{print-not-readable}.

Binding \cd{*read-eval*} to \cdf{nil} is useful when reading data that came from
  an untrusted source, such as a network or a user-supplied data file; it
  prevents the \cd{\#.} reader macro from being exploited as a ``Trojan horse'' to
  cause arbitrary forms to be evaluated.
\end{defun}

\subsection{Macro Characters}
\label{MACRO-CHARACTERS-SECTION}
\indexterm{parsing}
\indexterm{macro character}
If the reader encounters a macro
character, then the function associated with that macro character is
invoked and may produce an object to be returned.  This function may read
following characters in the stream in whatever syntax it likes (it may
even call \cdf{read} recursively) and return the object represented by
that syntax.  Macro characters may or may not be recognized, of course,
when read as part of other special syntaxes (such as for strings).

The reader is therefore organized into two parts: the basic dispatch loop,
which also distinguishes symbols and numbers, and the collection
of macro characters.  Any character can be reprogrammed as a macro character;
this is a means by which the reader can be extended.
The macro characters normally defined are as follows:
\begin{flushdesc}
\item[\cd{(}]
\indexterm{(!macro character}
The left-parenthesis character initiates reading of a pair or list.
The function~\cdf{read} is called recursively to read successive objects
until a right parenthesis is found to be next in the input stream.
A list of the objects read is returned.  Thus the input sequence
\begin{lisp}
(a b c)
\end{lisp}
is read as a list of three objects (the symbols \cdf{a}, \cdf{b}, and \cdf{c}).
The right parenthesis need not immediately follow the printed representation of
the last object; whitespace
characters and comments may precede it.
This can be useful for putting one object
on each line and making it easy to add new objects:
\begin{lisp}
(defun traffic-light (color) \\
~~(case color \\
~~~~(green) \\
~~~~(red (stop)) \\
~~~~(amber (accelerate))~~~~~;\textrm{Insert more colors after this line} \\
~~~~))
\end{lisp}

It may be that \emph{no} objects precede the right parenthesis, as in \cd{()}
or \cd{(~)}; this reads as a list of zero objects (the empty list).

If a token that is just a dot,
not preceded by an escape character,
is read after some object,
then exactly one more object must follow the dot,
possibly followed by whitespace,
followed by the right parenthesis:
\begin{lisp}
(a b c . d)
\end{lisp}
This means that the \emph{cdr} of the last pair in the list is not {\nil},
but rather the object whose representation followed the dot.
The above example might have been the result of evaluating
\begin{lisp}
(cons 'a (cons 'b (cons 'c 'd))) \EV\ (a b c . d)
\end{lisp}
Similarly, we have
\begin{lisp}
(cons 'znets 'wolq-zorbitan) \EV\ (znets . wolq-zorbitan)
\end{lisp}
It is permissible for the object following the dot to be a list:
\begin{lisp}
(a b c d . (e f . (g)))
\end{lisp}
is the same as
\begin{lisp}
(a b c d e f g)
\end{lisp}
but a list following a dot
is a non-standard form that \cdf{print} will never produce.

\item[\cd{)}]
\indexterm{)!macro character}
The right-parenthesis character is part of various constructs
(such as the syntax for lists) using the left-parenthesis character and
is invalid except when used in such a construct.
%\indexterm{\cd{) }macro character} fix label
%\indexterm{)}

\newpage%required

\item[\cd{{\Xquote}}]
\indexterm{'!macro character}
The single-quote (accent acute) character provides
an abbreviation to make it easier to put constants in programs.
The form
\cd{'\emph{foo}} reads the same as \cd{(quote \emph{foo})}: a list of the symbol
\cdf{quote} and \emph{foo}.

\item[\cd{;}]
Semicolon is used to write comments.
\indexterm{;!macro character}
\indexterm{comments}
The semicolon and all characters
up to and including the next newline are ignored.
Thus a comment can be put at
the end of any line without affecting the reader.
(A comment will terminate a token, but a newline would terminate the
token anyway.)

There is no functional difference between using one semicolon and using
more than one, but the conventions shown here are in common use.

\begin{lisp}
;;;; COMMENT-EXAMPLE function. \\
;;; This function is useless except to demonstrate comments. \\
;;; (Actually, this example is much too cluttered with them.) \\
 \\
(defun comment-example (x y)~~~~~~;X is anything; Y is an a-list. \\
~~(cond ((listp x) x)~~~~~~~~~~~~~;If X is a list, use that. \\
~~~~~~~~;; X is now not a list.  There are two other cases. \\
~~~~~~~~((symbolp x) \\
~~~~~~~~~;; Look up a symbol in the a-list. \\
~~~~~~~~~(cdr (assoc x y)))~~~~~~~;Remember, (cdr {\false}) is {\false}. \\
~~~~~~~~;; Do this when all else fails: \\
~~~~~~~~(t (cons x~~~~~~~~~~~~~~~~;Add x to a default list. \\
~~~~~~~~~~~~~~~~~'((lisp t)~~~~~~~;LISP is okay. \\
~~~~~~~~~~~~~~~~~~~(fortran nil)~~;FORTRAN is not. \\
~~~~~~~~~~~~~~~~~~~(pl/i -500)~~~~;Note that you can put comments in \\
~~~~~~~~~~~~~~~~~~~(ada .001)~~~~~; "data" as well as in "programs". \\
~~~~~~~~~~~~~~~~~~~;; COBOL?? \\
~~~~~~~~~~~~~~~~~~~(teco -1.0e9))))))
\end{lisp}
In this example, comments may begin with one to four semicolons.
\begin{itemize}
\item
Single-semicolon comments are all aligned to the same column at
the right; usually each comment concerns only the code it is next to.
Occasionally a comment is long enough to occupy two or three
lines; in this case, it is conventional to indent the
continued lines of the comment one space (after the
semicolon).

\item
\indexterm{;;!macro character}
Double-semicolon comments are aligned to the level of indentation
of the code.  A space conventionally follows the two semicolons.
Such comments usually describe the state of the program at that point
or the code section that follows the comment.

\item
\indexterm{;;;!macro character}
Triple-semicolon comments are aligned to the left margin.
They usually document whole programs or large code blocks.

\item
\indexterm{;;;;!macro character}
Quadruple-semicolon comments usually indicate titles of whole programs or large code blocks.
\end{itemize}

\item[\cd{"}]
%\indexterm{"!macro character}
\indexterm{'doublequote!macrocharacter} % quote needed for sorting
The double quote character begins the printed representation
of a string.
Successive characters are read from the input stream and accumulated until
another double quote is encountered.
An exception to this occurs if a \emph{single escape} character
is seen; the escape character is discarded,
the next character is accumulated, and accumulation
continues.  When a matching double quote is seen, all the accumulated
characters up to but not including the matching double quote are
made into a simple string and returned.

\item[\cd{{\Xbq}}]
\indexterm{`!macro character}
The backquote (accent grave) character
makes it easier to write programs to construct complex data structures by
using a template.
\label{BACKQUOTE}

As an example, writing
\begin{lisp}
{\Xbq}(cond ((numberp ,x) ,{\Xatsign}y) (t (print ,x) ,{\Xatsign}y))
\end{lisp}
is roughly equivalent to writing
\begin{lisp}
(list 'cond  \\
~~~~~~(cons (list 'numberp x) y)  \\
~~~~~~(list* 't (list 'print x) y))
\end{lisp}
The general idea is that the backquote is followed by a template,
a picture of a data structure to be built.  This template is copied,
except that within the template commas can appear.  Where a comma
occurs, the form following the comma is to be evaluated to produce an object to
be inserted at that point.  Assume \cdf{b} has the value \cd{3}; then
evaluating the form denoted by \cd{{\Xbq}(a b ,b ,(+ b 1) b)} produces
the result \cd{(a b 3 4 b)}.

If a comma is immediately followed by an at-sign (\cd{{\Xatsign}}), then the
form following the at-sign is evaluated to produce a \emph{list} of objects.
These objects are then ``spliced'' into place in the template.  For
example, if \cdf{x} has the value \cd{(a b c)}, then
\begin{lisp}
{\Xbq}(x ,x ,{\Xatsign}x foo ,(cadr x) bar ,(cdr x) baz ,{\Xatsign}(cdr x)) \\
~~~\EV\ (x (a b c) a b c foo b bar (b c) baz b c)
\end{lisp}

The backquote syntax can be summarized formally as follows.
For each of several situations in which backquote can be used,
a possible interpretation of that situation as an equivalent form
is given.  Note that the form is equivalent only
in the sense that when it is evaluated it will calculate the
correct result.
An implementation is quite free to interpret backquote in any way
such that a backquoted form, when evaluated, will produce a result
\cdf{equal} to that produced by the interpretation shown here.
\begin{itemize}
\item
\cd{{\Xbq}\emph{basic}} is the same as \cd{'\emph{basic}},
that is, \cd{(quote \emph{basic})}, for any form \emph{basic} that is not a
list or a general vector.

\item
\cd{{\Xbq},\emph{form}} is the same as \emph{form}, for any \emph{form}, provided
that the representation of \emph{form} does not begin with ``\cd{{\Xatsign}}''
or ``\cd{.}''.  (A similar caveat holds for all occurrences of a form
after a comma.)

\item
\cd{{\Xbq},{\Xatsign}\emph{form}} is an error.

\item
\cd{{\Xbq}(\emph{x1} \emph{x2} \emph{x3} ... \emph{xn} . \emph{atom})} may be interpreted to mean
\begin{lisp}
(append \textrm{[}\emph{x1}\textrm{]} \textrm{[}\emph{x2}\textrm{]}
    \textrm{[}\emph{x3}\textrm{]} ... \textrm{[}\emph{xn}\textrm{]} (quote \emph{atom}))
\end{lisp}
where the brackets are used to indicate
a transformation of an \emph{xj} as follows:
\begin{itemize}
\item
\textrm{[}\emph{form}\textrm{]} is interpreted as \cd{(list {\Xbq}\emph{form})}, which
contains a backquoted form that must then be further interpreted.

\item
\textrm{[}\cd{,\emph{form}}\textrm{]} is interpreted as \cd{(list \emph{form})}.

\item
\textrm{[}\cd{,{\Xatsign}\emph{form}}\textrm{]} is interpreted simply as \emph{form}.
\end{itemize}

\item
\cd{{\Xbq}(\emph{x1} \emph{x2} \emph{x3} ... \emph{xn})} may be interpreted to mean
the same as the backquoted form
\cd{{\Xbq}(\emph{x1} \emph{x2} \emph{x3} ... \emph{xn} . {\nil})},
thereby reducing it to the previous case.

\item
\cd{{\Xbq}(\emph{x1} \emph{x2} \emph{x3} ... \emph{xn} . ,\emph{form})} may be interpreted to mean
\begin{lisp}
(append \textrm{[}\emph{x1}\textrm{]} \textrm{[}\emph{x2}\textrm{]}
    \textrm{[}\emph{x3}\textrm{]} ... \textrm{[}\emph{xn}\textrm{]} \emph{form})
\end{lisp}
where the brackets indicate a transformation of an \emph{xj} as described above.

\item
\cd{{\Xbq}(\emph{x1} \emph{x2} \emph{x3} ... \emph{xn} . ,{\Xatsign}\emph{form})} is an error.

\item
\cd{{\Xbq}\#(\emph{x1} \emph{x2} \emph{x3} ... \emph{xn})} may be interpreted to mean
\begin{lisp}
(apply \#'vector {\Xbq}(\emph{x1} \emph{x2} \emph{x3} ... \emph{xn}))
\end{lisp}
\end{itemize}

No other uses of comma are permitted; in particular, it may not appear within
the \cd{\#A} or \cd{\#S} syntax.

Anywhere ``\cd{,{\Xatsign}}'' may be used, the syntax ``\cd{,.}'' may be used instead
to indicate that it is permissible to destroy the list produced by the form
following the ``\cd{,.}''; this may permit more efficient code, using
\cdf{nconc} instead of \cdf{append}, for example.

If the backquote syntax is nested, the innermost backquoted form
should be expanded first.  This means that if several commas occur
in a row, the leftmost one belongs to the innermost backquote.

Once again, it is emphasized that an implementation is free to interpret
a backquoted form as any form that, when evaluated, will produce a result
that is \cdf{equal} to the result implied by the above definition.
In particular, no guarantees are made as to whether the constructed
copy of the template will or will not share list structure with the
template itself.  As an example, the above definition implies that
\begin{lisp}
{\Xbq}((,a b) ,c ,{\Xatsign}d)
\end{lisp}
will be interpreted as if it were
\begin{lisp}
(append (list (append (list a) (list 'b) '{\nil})) (list c) d '{\nil})
\end{lisp}
but it could also be legitimately interpreted to mean any of the following.
\begin{lisp}
(append (list (append (list a) (list 'b))) (list c) d) \\
(append (list (append (list a) '(b))) (list c) d) \\
(append (list (cons a '(b))) (list c) d) \\
(list* (cons a '(b)) c d) \\
(list* (cons a (list 'b)) c d) \\
(list* (cons a '(b)) c (copy-list d))
\end{lisp}
(There is no good reason why \cdf{copy-list} should be performed, but
it is not prohibited.)

\penalty-10000%required

\begin{new}
Some users complain that backquote syntax is difficult to read,
especially when it is nested.  I agree that it can get complicated,
but in some situations (such as writing macros that expand into
definitions for other macros) such complexity is to be expected,
and the alternative is much worse.

After I gained some experience in writing nested backquote forms,
I found that I was not stopping to analyze the various patterns
of nested backquotes and interleaved commas and quotes; instead, I was
recognizing standard idioms wholesale, in the same manner that I recognize \cdf{cadar}
as the primitive for ``extract the lambda-list from the
form \cd{((lambda ...)~...)})'' without stopping to analyze it into
``\cdf{car} of \cdf{cdr} of \cdf{car}.''  For example, \cd{,x} within
a doubly-nested backquote form means ``the value of \cdf{x} available
during the second evaluation
will appear here once the form has been twice
evaluated,'' whereas \cd{,',x} means ``the value of \cdf{x} available during the
first evaluation will appear here once the form has been twice
evaluated'' and \cd{,,x} means ``the value of the value of \cdf{x} will appear here.''

See appendix~\ref{BACKQUOTE-SIMULATOR} for a systematic set of examples
of the use of nested backquotes.
\end{new}

\item[\cd{,}]
\indexterm{,!macro character}
The comma character is part of the backquote syntax
and is invalid if used other than inside the body of a backquote
construction as described above.

\item[\cd{\#}]
\indexterm{'diez!macro character}
This is a \emph{dispatching} macro character.
It reads an optional digit string and then one more character,
and uses that character to select a function to run as a macro-character
function.

The \cd{\#} character also happens to be a non-terminating
macro character.  This is completely independent of the fact that
it is a dispatching macro character; it is a coincidence that
the only standard dispatching macro character in Common Lisp is
also the only standard non-terminating macro character.

See the next section for predefined \cd{\#} macro-character constructions.
\end{flushdesc}


\subsection{Standard Dispatching Macro Character Syntax}
\label{SHARP-SIGN-MACRO-CHARACTER-SECTION}
%\indexterm{\cd{\# }macro character} fix label
%\indexterm{\#}

The standard syntax includes forms introduced by the \cd{\#} character.
These take the general form of a \cd{\#},
a second character that identifies the syntax,
and following arguments in some form.
If the second character is a letter, then case is not important;
\cd{\#O} and \cd{\#o} are considered to be equivalent, for example.

Certain \cd{\#} forms allow an unsigned decimal number to appear
between the \cd{\#} and the second character; some other
forms even require it.  Those forms that do not explicitly permit
such a number to appear forbid it.

\begin{table}
\caption{Standard \# Macro Character Syntax}
\label{Standard-Sharp-Macro-Definitions-Table}

\begin{tabular*}{\textwidth}{@{\extracolsep{\fill}}l@{\extracolsep{\fill}}lll@{}}
\cd{\#!}&\emph{undefined} *&\cd{\#}$\langle$backspace$\rangle$&\emph{signals error} \\
\cd{\#"}&\emph{undefined}&\cd{\#}$\langle$tab$\rangle$&\emph{signals error} \\
\cd{\#\#}&\emph{reference to \cd{\#=} label}&\cd{\#}$\langle$newline$\rangle$&\emph{signals error} \\
\cd{\#\$}&\emph{undefined}&\cd{\#}$\langle$linefeed$\rangle$&\emph{signals error} \\
\cd{\#\%}&\emph{undefined}&\cd{\#}$\langle$page$\rangle$&\emph{signals error} \\
\cd{\#\&}&\emph{undefined}&\cd{\#}$\langle$return$\rangle$&\emph{signals error} \\
\cd{\#'}&\emph{\cdf{function} abbreviation}&\cd{\#}$\langle$space$\rangle$&\emph{signals error} \\
\cd{\#(}&\emph{simple vector}&\cd{\#+}&\emph{read-time conditional} \\
\cd{\#)}&\emph{signals error}&\cd{\#-}&\emph{read-time conditional} \\
\cd{\#*}&\emph{bit-vector}&\cd{\#.}&\emph{read-time evaluation} \\
\cd{\#,}&\emph{load-time evaluation}&\cd{\#/}&\emph{undefined} \\
\cd{\#0}&\emph{used for infix arguments}~~~~~~&\cd{\#A}, \cd{\#a}&\emph{array} \\
\cd{\#1}&\emph{used for infix arguments}&\cd{\#B}, \cd{\#b}&\emph{binary rational} \\
\cd{\#2}&\emph{used for infix arguments}&\cd{\#C}, \cd{\#c}&\emph{complex number} \\
\cd{\#3}&\emph{used for infix arguments}&\cd{\#D}, \cd{\#d}&\emph{undefined} \\
\cd{\#4}&\emph{used for infix arguments}&\cd{\#E}, \cd{\#e}&\emph{undefined} \\
\cd{\#5}&\emph{used for infix arguments}&\cd{\#F}, \cd{\#f}&\emph{undefined} \\
\cd{\#6}&\emph{used for infix arguments}&\cd{\#G}, \cd{\#g}&\emph{undefined} \\
\cd{\#7}&\emph{used for infix arguments}&\cd{\#H}, \cd{\#h}&\emph{undefined} \\
\cd{\#8}&\emph{used for infix arguments}&\cd{\#I}, \cd{\#i}&\emph{undefined} \\
\cd{\#9}&\emph{used for infix arguments}&\cd{\#J}, \cd{\#j}&\emph{undefined} \\
\cd{\#:}&\emph{uninterned symbol}&\cd{\#K}, \cd{\#k}&\emph{undefined} \\
\cd{\#;}&\emph{undefined}&\cd{\#L}, \cd{\#l}&\emph{undefined} \\
\cd{\#<}&\emph{signals error}&\cd{\#M}, \cd{\#m}&\emph{undefined} \\
\cd{\#=}&\emph{label following object}&\cd{\#N}, \cd{\#n}&\emph{undefined} \\
\cd{\#>}&\emph{undefined}&\cd{\#O}, \cd{\#o}&\emph{octal rational} \\
\cd{\#?}&\emph{undefined} *&\cd{\#P}, \cd{\#p}&\emph{pathname} \\
\cd{\#{\Xatsign}}&\emph{undefined}&\cd{\#Q}, \cd{\#q}&\emph{undefined} \\
\cd{\#{\Xlbracket}}&\emph{undefined} *&\cd{\#R}, \cd{\#r}&\emph{radix-n rational} \\
\cd{\#{\Xbackslash}}&\emph{character object}&\cd{\#S}, \cd{\#s}&\emph{structure} \\
\cd{\#{\Xrbracket}}&\emph{undefined} *&\cd{\#T}, \cd{\#t}&\emph{undefined} \\
\cd{\#{\Xcircumflex}}&\emph{undefined}&\cd{\#U}, \cd{\#u}&\emph{undefined} \\
\cd{\#{\Xunderscore}}&\emph{undefined}&\cd{\#V}, \cd{\#v}&\emph{undefined} \\
\cd{\#{\Xbq}}&\emph{undefined}&\cd{\#W}, \cd{\#w}&\emph{undefined} \\
\cd{\#{\Xlbrace}}&\emph{undefined} *&\cd{\#X}, \cd{\#x}&\emph{hexadecimal rational} \\
\cd{\#|}&\emph{balanced comment}&\cd{\#Y}, \cd{\#y}&\emph{undefined} \\
\cd{\#{\Xrbrace}}&\emph{undefined} *&\cd{\#Z}, \cd{\#z}&\emph{undefined} \\
\cd{\#{\Xtilde}}&\emph{undefined}&\cd{\#}$\langle$rubout$\rangle$&\emph{undefined}
\end{tabular*}

\vfill
\begin{small}
\noindent
The combinations marked by an asterisk are explicitly reserved to the user
and will never be defined by Common Lisp.
\end{small}
\end{table}

The currently defined \cd{\#} constructs are described below
and summarized in table~\ref{Standard-Sharp-Macro-Definitions-Table};
more are likely to be added in the future.  However, the constructs
\cd{\#!}, \cd{\#?}, \cd{\#{\Xlbracket}}, \cd{\#{\Xrbracket}},
\cd{\#{\Xlbrace}}, and \cd{\#{\Xrbrace}}
are explicitly reserved for the user and will never be defined by the
Common Lisp standard.
\begin{flushdesc}
\item[\cd{\#{\Xbackslash}}]
\indexterm{'diezbackslash!macro character}
\cd{\#{\Xbackslash}\emph{x}} reads in as a character object that represents the
character \emph{x}.  Also, \cd{\#{\Xbackslash}\emph{name}} reads in as the character object
whose name is \emph{name}.
%\indexterm{character syntax}
Note that the backslash \cd{{\Xbackslash}} allows this
construct to be parsed easily by {EMACS}-like editors.

In the single-character case, the character \emph{x} must be followed
by a non-constituent character, lest a \emph{name} appear to follow the
\cd{\#{\Xbackslash}}.  A good model of what happens is that after \cd{\#{\Xbackslash}} is read,
the reader backs up over the \cd{{\Xbackslash}} and then reads an extended token,
treating the initial \cd{{\Xbackslash}} as an escape character (whether it really
is or not in the current readtable).

Uppercase and lowercase letters are distinguished after \cd{\#{\Xbackslash}};
\cd{\#{\Xbackslash}A} and \cd{\#{\Xbackslash}a} denote different character objects.  Any
character works after \cd{\#{\Xbackslash}}, even those that are normally special to
\cdf{read}, such as parentheses.  Non-printing characters may be used
after \cd{\#{\Xbackslash}}, although for them names are generally preferred.

\cd{\#{\Xbackslash}\emph{name}} reads in as a character object whose name is \emph{name}
(actually, whose name is \cd{(string-upcase \emph{name})};
therefore the syntax is case-insensitive).
The \emph{name} should have the syntax of a symbol.
The following names are standard across all implementations:
\begin{tabbing}
\hskip 7pc\=\kill
\cdf{newline}\>The character that represents the division between lines \\
\cdf{space}\>The space or blank character
\end{tabbing}
The following names are semi-standard; if an implementation supports
them, they should be used for the described characters and no others.
\begin{tabbing}
\hskip 7pc\=\kill
\cdf{rubout}\>The rubout or delete character.\\
\cdf{page}\>The form-feed or page-separator character \\
\cdf{tab}\>The tabulate character \\
\cdf{backspace}\>The backspace character \\
\cdf{return}\>The carriage return character \\
\cdf{linefeed}\>The line-feed character
\end{tabbing}
In some implementations, one or more of these characters might be
a synonym for a standard character; the \cd{\#{\Xbackslash}Linefeed} character
might be the same as \cd{\#{\Xbackslash}Newline}, for example.

When the Lisp printer types out the name of a special character, it uses the
same table as the \cd{\#{\Xbackslash}} reader; therefore any character name you see typed out
is acceptable as input (in that implementation).  Standard names are always
preferred over non-standard names for printing.

The following convention is used in implementations that support
non-zero bits attributes for character objects.
If a name after \cd{\#{\Xbackslash}} is longer than one character and has a hyphen in it,
then it may be split into the two parts preceding
and following the first hyphen; the first part (actually, \cdf{string-upcase}
of the first part)
may then be interpreted as
the name or initial of a bit, and the second part as the name of the character
(which may in turn contain a hyphen and be subject to further splitting).
For example:
\begin{lisp}
\hskip10pc\=\kill
\#{\Xbackslash}Control-Space			\>\#{\Xbackslash}Control-Meta-Tab \\
\#{\Xbackslash}C-M-Return			\>\#{\Xbackslash}H-S-M-C-Rubout
\end{lisp}
If the character name consists of a single character, then that character
is used.  Another \cd{{\Xbackslash}} may be necessary to quote the character.
\begin{lisp}
\hskip10pc\=\kill
\#{\Xbackslash}Control-\%			\>\#{\Xbackslash}Control-Meta-{\Xbackslash}" \\
\#{\Xbackslash}Control-{\Xbackslash}a			\>\#{\Xbackslash}Meta->
\end{lisp}

\begin{obsolete}
If an unsigned decimal integer appears between the \cd{\#} and \cd{{\Xbackslash}},
it is interpreted as a font number, to become the font attribute
of the character object (see \cdf{char-font}).
\end{obsolete}

\begin{newer}
X3J13 voted in March 1989 \issue{CHARACTER-PROPOSAL}
to replace the notion of bits and font attributes with
that of implementation-defined attributes.  Presumably
this eliminates the portable use of this syntax for font information,
although the vote did not address this question directly.
\end{newer}

\item[\cd{\#'}]
\cd{\#'\emph{foo}} is an abbreviation for \cd{(function \emph{foo})}.
\emph{foo} may be the printed representation of any Lisp object.
This abbreviation may be remembered by analogy with the \cd{'}
macro character, since the \cdf{function} and \cdf{quote} special operators are
similar in form.

\item[\cd{\#(}]
A series of representations of objects enclosed by \cd{\#(} and \cd{)}
is read as a simple vector of those objects.  This is analogous to
the notation for lists.

If an unsigned decimal integer appears between the \cd{\#} and \cd{(},
it specifies explicitly the length of the vector.  In that case,
it is an error if too many objects are specified before the closing \cd{)},
and if too few are specified, the last object
(it is an error if there are none in this case)
is used to fill all
remaining elements of the vector.
For example,
\begin{lisp}
\#(a b c c c c)~~~~~\#6(a b c c c c)~~~~~\#6(a b c)~~~~~\#6(a b c c)
\end{lisp}
all mean the same thing: a vector of length 6 with elements \cdf{a}, \cdf{b},
and four instances of \cdf{c}.  
The notation \cd{\#()} denotes an empty vector, as does \cd{\#0()}
(which is legitimate because it is not the case that too few elements
are specified).

\item[\cd{\#*}]
A series of binary digits (\cd{0} and \cd{1}) preceded by \cd{\#*} is
read as a simple bit-vector containing those bits, the leftmost bit
in the series being bit 0 of the bit-vector.

If an unsigned decimal integer appears between the \cd{\#} and \cdf{*},
it specifies explicitly the length of the vector.  In that case,
it is an error if too many bits are specified,
and if too few are specified the last one
(it is an error if there are none in this case)
is used to fill all remaining elements of the bit-vector.
For example,
\begin{lisp}
\#*101111~~~~~\#6*101111~~~~~\#6*101~~~~~\#6*1011
\end{lisp}
all mean the same thing: a vector of length 6 with elements \cd{1}, \cd{0},
\cd{1}, \cd{1}, \cd{1}, and \cd{1}.
The notation \cd{\#*} denotes an empty bit-vector, as does \cd{\#0*}
(which is legitimate because it is not the case that too few elements
are specified).
\begin{new}
Compare this to \cd{\#B}, used for expressing integers in binary notation.
\end{new}

\item[\cd{\#:}]
\cd{\#:\emph{foo}} requires \emph{foo} to have the syntax of an unqualified
symbol name (no embedded colons).  It denotes an \emph{uninterned} symbol
whose name is \emph{foo}.  Every time this syntax is encountered, a different
uninterned symbol is created.  If it is necessary to refer to the
same uninterned symbol more than once in the same expression,
the \cd{\#=} syntax may be useful.

\item[\cd{\#.}]
\cd{\#.\emph{foo}} is read as the object resulting from the evaluation
of the Lisp object represented by \emph{foo},
which may be the printed representation of any Lisp object.
The evaluation is done during the \cdf{read} process, when the \cd{\#.}
construct is encountered.

\begin{newer}
X3J13 voted in June 1989 \issue{DATA-IO} to add a new reader control variable,
\cd{*read-eval*}.  If it is true,
the \cd{\#.} reader macro behaves as described above;
if it is false, the \cd{\#.} reader macro signals an error.
\end{newer}

The \cd{\#.} syntax therefore performs a read-time evaluation of \emph{foo}.
By contrast, \cd{\#,} (see below) performs a load-time evaluation.

Both \cd{\#.} and \cd{\#,} allow you to include, in an expression
being read, an object that does not have a convenient printed
representation; instead of writing a representation for the object,
you write an expression that will \emph{compute} the object.
\end{flushdesc}

\begin{flushdesc}
\item[\cd{\#B}]
\cd{\#b\emph{rational}} reads \emph{rational} in binary (radix 2).
For example, \cd{\#B1101} \EQ\ \cd{13}, and \cd{\#b101/11} \EQ\ \cd{5/3}.
\begin{new}
Compare this to \cd{\#*}, used for expressing bit-vectors in binary notation.
\end{new}

\item[\cd{\#O}]
\cd{\#o\emph{rational}} reads \emph{rational} in octal (radix 8).
For example, \cd{\#o37/15} \EQ\ \cd{31/13}, and \cd{\#o777} \EQ\ \cd{511}.

\item[\cd{\#X}]
\cd{\#x\emph{rational}} reads \emph{rational} in hexadecimal (radix 16).
The digits above \cd{9} are the letters \cdf{A} through \cdf{F} (the lowercase
letters \cdf{a} through \cdf{f} are also acceptable).  For example,
\cd{\#xF00} \EQ\ \cd{3840}.

\item[\cd{\#\emph{n}R}]
\cd{\#\emph{radix}r\emph{rational}} reads \emph{rational} in radix \emph{radix}.
\emph{radix} must consist of only digits, and
it is read in decimal; its value must be between 2 and 36 (inclusive).

\penalty-10000 %required

For example, \cd{\#3r102} is another way of writing \cd{11}, and \cd{\#11R32}
is another way of writing \cd{35}.  For radices larger than 10, letters of
the alphabet are used in order for the digits after \cd{9}.

\item[\cd{\#\emph{n}A}]
The syntax \cd{\#\emph{n}A\emph{object}} constructs an \emph{n}-dimensional array,
using \emph{object} as the value of the \cd{:initial-contents} argument
to \cdf{make-array}.

The value of \emph{n} makes a difference:
\cd{\#2A((0 1 5) (foo 2 (hot dog)))}, for example, represents a 2-by-3 matrix:
\begin{lisp}
0~~~~~~~1~~~~~~~5 \\
foo~~~~~2~~~~~~~(hot dog)
\end{lisp}
In contrast, \cd{\#1A((0 1 5) (foo 2 (hot dog)))} represents a length-2
array whose elements are lists:
\begin{lisp}
(0 1 5)~~~~(foo 2 (hot dog))
\end{lisp}
Furthermore, \cd{\#0A((0 1 5) (foo 2 (hot dog)))} represents a zero-dimensional
array whose sole element is a list:
\begin{lisp}
((0 1 5) (foo 2 (hot dog)))
\end{lisp}
Similarly, \cd{\#0Afoo} (or, more readably, \cd{\#0A foo}) represents
a zero-dimensional array whose sole element is the symbol \cdf{foo}.
The expression \cd{\#1Afoo} would not be legal because \cdf{foo} is
not a sequence.

\item[\cd{\#S}]
The syntax \cd{\#s(\emph{name} \emph{slot1} \emph{value1} \emph{slot2} \emph{value2} ...)}
denotes a structure.  This is legal only if \emph{name} is the name
of a structure already defined by \cdf{defstruct} and if the
structure has a standard constructor macro, which it normally will.
Let \emph{cm} stand for the name of this constructor macro;
then this syntax is equivalent to
\begin{lisp}
\#.(\emph{cm} \emph{keyword1} '\emph{value1} \emph{keyword2} '\emph{value2} ...)
\end{lisp}
where each \emph{keywordj} is the result of computing
\begin{lisp}
(intern (string \emph{slotj}) 'keyword)
\end{lisp}
(This computation is made so that one need not write a colon in
front of every slot name.)
The net effect is that the constructor macro is called
with the specified slots
having the specified values (note that one does not write quote marks
in the \cd{\#S} syntax).  Whatever object the constructor macro returns
is returned by the \cd{\#S} syntax.
\end{flushdesc}

\begin{newer}
\begin{flushdesc}
\item[\cd{\#P}]
X3J13 voted in June 1989 \issue{PATHNAME-PRINT-READ}
to define the reader syntax \cd{\#p"..."} to be equivalent to
\cd{\#.(parse-namestring "...")}.  Presumably this was meant to
be taken descriptively and not literally.  I would think, for example,
that the committee did not wish to quibble over the package in which
the name \cdf{parse-namestring} was to be read.  Similarly, I would
presume that the \cd{\#p} syntax operates normally rather than signaling
an error when \cd{*read-eval*} is false.  I interpret the intent
of the vote to be that \cd{\#p} reads a following form, which should be
a string, that is then converted to a pathname as if by application
of the standard function \cdf{parse-namestring}.
\end{flushdesc}
\end{newer}

\begin{flushdesc}
\item[\cd{\#\emph{n}{\Xequal}}]
The syntax \cd{\#\emph{n}=\emph{object}} reads as whatever Lisp object
has \emph{object} as its printed representation.  However, that object
is labelled by \emph{n}, a required unsigned decimal integer, for
possible reference by the syntax \cd{\#\emph{n}\#} (below).
The scope of the label is the expression being read by the outermost
call to \cdf{read}.  Within this expression
the same label may not appear twice.

\item[\cd{\#\emph{n}\#}]
The syntax \cd{\#\emph{n}\#}, where \emph{n} is a required unsigned decimal integer,
serves as a reference to some object labelled by \cd{\#\emph{n}=};
that is, \cd{\#\emph{n}\#} represents a pointer to the same identical
(\cdf{eq}) object labelled by \cd{\#\emph{n}=}.
This permits notation of structures with shared or circular substructure.
For example, a structure created in the variable \cdf{y} by this code:
\begin{lisp}
(setq x (list 'p 'q)) \\
(setq y (list (list 'a 'b) x 'foo x)) \\
(rplacd (last y) (cdr y))
\end{lisp}
could be represented in this way:
\begin{lisp}
((a b) . \#1=(\#2=(p q) foo \#2\# . \#1\#))
\end{lisp}
Without this notation, but with \cd{*print-length*} set to \cd{10},
the structure would print in this way:
\begin{lisp}
((a b) (p q) foo (p q) (p q) foo (p q) (p q) foo (p q) ...)
\end{lisp}
A reference \cd{\#\emph{n}\#} may occur only after a label \cd{\#\emph{n}=};
forward references are not permitted.  In addition, the reference
may not appear as the labelled object itself (that is,
one may not write \cd{\#\emph{n}= \#\emph{n}\#}), because the object
labelled by \cd{\#\emph{n}=} is not well defined in this case.

\item[\cd{\#+}]
\label{READ-TIME-CONDITIONAL}
The \cd{\#+} syntax provides a read-time conditionalization facility;
the syntax is
\begin{lisp}
\#+\emph{feature} \emph{form}
\end{lisp}
If \emph{feature} is ``true,'' then this syntax represents a Lisp object
whose printed representation is \emph{form}.  If \emph{feature} is ``false,''
then this syntax is effectively whitespace; it is as if it did not appear.

The \emph{feature} should be the printed representation of a symbol or list.
If \emph{feature} is a symbol, then 
it is true if and only if it is a member of the list that is the value of
the global variable \cdf{*features*}.

Otherwise,
\emph{feature} should be a Boolean expression composed of \cdf{and}, \cdf{or}, and
\cdf{not} operators on (recursive) \emph{feature} expressions.

For example, suppose that in implementation A the features \cdf{spice} and
\cdf{perq} are true, and in implementation B the feature \cdf{lispm} is true.
Then the expressions on the left below are read the same as those on the
right in implementation A:
\begin{lisp}
(cons \#+spice "Spice" \#+lispm "Lispm" x)~~~~~~(cons "Spice" x) \\*
(setq a '(1 2 \#+perq 43 \#+(not perq) 27))~~~~~(setq a '(1 2 43)) \\*
(let ((a 3) \#+(or spice lispm) (b 3))~~~~~~~~~(let ((a 3) (b 3)) \\*
~~(foo a))~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~(foo a))\\*
(cons a \#+perq \#-perq b c)~~~~~~~~~~~~~~~~~~~~(cons a c)
\end{lisp}
In implementation B, however, they are read in this way:
\begin{lisp}
(cons \#+spice "Spice" \#+lispm "Lispm" x)~~~~~~(cons "Lispm" x) \\*
(setq a '(1 2 \#+perq 43 \#+(not perq) 27))~~~~~(setq a '(1 2 27)) \\*
(let ((a 3) \#+(or spice lispm) (b 3))~~~~~~~~~(let ((a 3) (b 3)) \\*
~~(foo a))~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~(foo a))\\*
(cons a \#+perq \#-perq b c)~~~~~~~~~~~~~~~~~~~~(cons a c)
\end{lisp}

\newpage%manual

The \cd{\#+} construction must be used judiciously if unreadable code is
not to result.  The user should make a careful choice between read-time
conditionalization and run-time conditionalization.

The \cd{\#+} syntax operates by first reading the \emph{feature} specification
and then skipping over the \emph{form} if the \emph{feature} is ``false.''
This skipping of a form is a bit tricky because of the possibility of
user-defined macro characters and side effects caused by the \cd{\#.}
construction.  It is accomplished by binding the variable 
\cd{*read-suppress*} to a non-{\nil} value and then calling the \cdf{read}
function.  See the description of \cd{*read-suppress*} for the details
of this operation.

\begin{newer}
X3J13 voted in March 1988 \issue{SHARPSIGN-PLUS-MINUS-PACKAGE}
to specify that the \cdf{keyword} package is the default package during
the reading of a feature specification.  Thus \cd{\#+spice} means the
same thing as \cd{\#+:spice}, and
\cd{\#+(or~spice~lispm)} means the same thing as \cd{\#+(or~:spice~:lispm)}.
Symbols in other packages
may be used as feature names, but one must use an explicit package prefix
to cite one after \cd{\#+}.
\end{newer}

\item[\cd{\#-}]
\cd{\#-\emph{feature} \emph{form}} is equivalent to \cd{\#+(not \emph{feature}) \emph{form}}.

\item[\cd{\#|}]
\cd{\#|...|\#} is treated as a comment by the reader, just as everything
from a semicolon to the next newline is treated as a comment.
Anything may appear in the comment, except that it must be balanced
with respect to other occurrences of \cd{\#|} and \cd{|\#}.
Except for this nesting rule, the comment may contain any characters
whatsoever.

The main purpose of this construct is to allow ``commenting out''
of blocks of code or data.  The balancing rule allows such blocks
to contain pieces already so commented out.  In this respect
the \cd{\#|...|\#} syntax of Common Lisp differs from the \cd{/*...*/} comment syntax
used by {PL/I} and C.

\item[\cd{\#<}]
This is not legal reader syntax.
It is conventionally used in the printed representation of objects that cannot
be read back in.  Attempting to read a \cd{\#<} will cause an error.
(More precisely, it \emph{is} legal syntax, but the macro-character
function for \cd{\#<} signals an error.)

\begin{newer}
The usual convention for printing unreadable data objects is to print some identifying
information (the internal machine address of the object, if nothing else)
preceded by \cd{\#<} and followed by \cdf{>}.

X3J13 voted in June 1989 \issue{DATA-IO} to add
\cdf{print-unreadable-object}, a macro that prints an object using \cd{\#<...>}
syntax and also takes care of checking the variable \cd{*print-readably*}.
\end{newer}

\item[\cd{\#}$\langle$space$\rangle$, \cd{ \#}$\langle$tab$\rangle$,
      \cd{ \#}$\langle$newline$\rangle$,
      \cd{ \#}$\langle$page$\rangle$, \cd{ \#}$\langle$return$\rangle$]
A \cd{\#} followed by a whitespace character is not legal reader syntax.
This prevents abbreviated forms produced via \cd{*print-level*} cutoff
from reading in again, as a safeguard against losing
information.
(More precisely, this \emph{is} legal syntax, but the macro-character
function for it signals an error.)

\item[\cd{\#)}]
This is not legal reader syntax.
This prevents abbreviated forms produced via \cd{*print-level*} cutoff
from reading in again, as a safeguard against losing information.
(More precisely, this \emph{is} legal syntax, but the macro-character
function for it signals an error.)
\end{flushdesc}

\subsection{The Readtable}
\label{READTABLE-SECTION}
%\indexterm{readtable}

Previous sections describe the standard syntax accepted by the \cdf{read}
function.  This section discusses the advanced topic of altering the
standard syntax either to provide extended syntax for Lisp objects
or to aid the writing of other parsers.

There is a data structure called the \emph{readtable} that is used to
control the reader.  It contains information about the syntax of each
character equivalent to that in table~\ref{Standard-Character-Syntax-Table}.
It is set up exactly as in
table~\ref{Standard-Character-Syntax-Table} to give the standard Common Lisp
meanings to all the characters, but the user can change the meanings of
characters to alter and customize the syntax of characters.  It is also
possible to have several readtables describing different syntaxes and to
switch from one to another by binding the variable \cd{*readtable*}.

\begin{defun}[Variable]
*readtable*

The value of \cd{*readtable*} is the current readtable.  The initial
value of this is a readtable set up for standard Common Lisp syntax.
You can bind this variable to temporarily change the readtable being used.
\end{defun}

To program the reader for a different syntax, a set of functions are
provided for manipulating readtables.  Normally, you should begin
with a copy of the standard Common Lisp readtable and then customize
the individual characters within that copy.

\begin{defun}[Function]
copy-readtable &optional from-readtable to-readtable

A copy is made of \emph{from-readtable}, which defaults to the current readtable
(the value of the global variable \cd{*readtable*}).  If \emph{from-readtable}
is {\false}, then a copy of a standard Common Lisp readtable is made.
For example,
\begin{lisp}
(setq *readtable* (copy-readtable nil))
\end{lisp}
will restore the input syntax to standard Common Lisp syntax, even if
the original readtable has been clobbered (assuming it is not so
badly clobbered that you cannot type in the above expression!).
On the other hand,
\begin{lisp}
(setq *readtable* (copy-readtable))
\end{lisp}
will merely replace the current readtable with a copy of itself.

If \emph{to-readtable} is unsupplied or {\false}, a fresh copy is made.  Otherwise,
\emph{to-readtable} must be a readtable, which is destructively copied into.
\end{defun}

\begin{defun}[Function]
readtablep object

\cdf{readtablep} is true if its argument is a readtable,
and otherwise is false.
\begin{lisp}
(readtablep x) \EQ\ (typep x 'readtable)
\end{lisp}
\end{defun}

\begin{defun}[Function]
set-syntax-from-char to-char from-char &optional to-readtable from-readtable

This makes the syntax of \emph{to-char} in \emph{to-readtable} be the same as the
syntax of \emph{from-char} in \emph{from-readtable}.  The \emph{to-readtable}
defaults to the current readtable (the value of the global variable
\cd{*readtable*}), and \emph{from-readtable} defaults to {\false}, meaning
to use the syntaxes from the standard Lisp readtable.
\begin{new}
X3J13 voted in January 1989
\issue{ARGUMENTS-UNDERSPECIFIED}
to clarify that the \emph{to-char} and \emph{from-char}
must each be a character.
\end{new}

Only attributes as shown in
table~\ref{Standard-Character-Syntax-Table} are copied; moreover,
if a \emph{macro character} is copied, the macro definition function
is copied also.
However, attributes as shown
in table~\ref{Standard-Readtable-Attributes-Table} are not copied;
they are ``hard-wired'' into the extended-token parser.
For example, if the definition of \cdf{S} is copied to \cdf{*},
then \cdf{*} will become a \emph{constituent} that is
\emph{alphabetic} but cannot be used
as an exponent indicator for short-format floating-point number syntax.

It works to copy a macro definition from a character such as
\cd{"} to another character; the standard definition for \cd{"}
looks for another character that is the same as the character that
invoked it.  It doesn't work to copy the definition of \cd{(}
to \cd{{\Xlbrace}}, for example; it can be done, but it lets one write lists
in the form \cd{{\Xlbrace}a b c)}, not \cd{{\Xlbrace}a b c{\Xrbrace}},
because the definition
always looks for a closing parenthesis, not a closing brace.  See the function
\cdf{read-delimited-list}, which is useful in this connection.

The \cdf{set-syntax-from-char} function returns \cdf{t}.
\end{defun}

\begin{defun}[Function]
set-macro-character char function &optional non-terminating-p readtable \\
get-macro-character char &optional readtable

\cdf{set-macro-character} causes \emph{char} to be a macro character that
when seen by \cdf{read} causes \emph{function} to be called.
If \emph{non-terminating-p} is not {\false} (it defaults to {\false}),
then it will be a non-terminating macro character: it may be embedded
within extended tokens.
\cdf{set-macro-character} returns {\true}.

\cdf{get-macro-character} returns the function associated with \emph{char}
and, as a second value, returns the \emph{non-terminating-p} flag; it returns
{\false} if \emph{char} does not have macro-character syntax.  In each case,
\emph{readtable} defaults to the current readtable.

If \cdf{nil} is explicitly passed as the
second argument to \cdf{get-macro-character}, then the standard readtable is used.
This is consistent with the behavior of \cdf{copy-readtable}.

The \emph{function} is called with two arguments, \emph{stream}
and \emph{char}.  The \emph{stream} is the input stream, and \emph{char} is the
macro character itself.
In the simplest case, \emph{function} may return a Lisp object.
This object is taken to be that whose printed representation
was the macro character and any following characters read
by the \emph{function}.
As an example, a plausible definition of the standard single quote
character is:
\begin{lisp}
(defun single-quote-reader (stream char) \\
~~(declare (ignore char)) \\
~~(list 'quote (read stream t nil t))) \\
 \\
(set-macro-character \#{\Xbackslash}' \#'single-quote-reader)
\end{lisp}
(Note that {\true} is specified for the \emph{recursive-p} argument
to \cdf{read}; see section~\ref{CHARACTER-INPUT-SECTION}.)
The function reads an object following the single-quote and returns
a list of the symbol \cdf{quote} and that object.
The \emph{char} argument is ignored.

\penalty-10000 %required

The function may choose instead to return \emph{zero} values
(for example, by using \cd{(values)} as the return expression).
In this case, the macro character and whatever it may have read
contribute nothing to the object being read.
As an example, here is a plausible definition for the standard semicolon
(comment) character:
\begin{lisp}
(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 \#{\Xbackslash}Newline t) \#{\Xbackslash}Newline))) \\
~~;; Return zero values. \\
~~(values)) \\
 \\
(set-macro-character \#{\Xbackslash}; \#'semicolon-reader)
\end{lisp}
(Note that {\true} is specified for the \emph{recursive-p} argument
to \cdf{read-char}; see section~\ref{CHARACTER-INPUT-SECTION}.)

The \emph{function} should not have any side effects other than on the
\emph{stream}.
Because of backtracking and restarting of the \cdf{read} operation,
front ends (such as editors and
rubout handlers) to the reader may cause
\emph{function} to be called repeatedly during the
reading of a single expression in which the macro character only appears
once.

\begin{new}
Here is an example of a more elaborate set of read-macro characters
that I used in the implementation of the original
simulator for Connection Machine Lisp
\cite{CONNECTION-MACHINE-LISP,CMLISP-IMPLEMENTATION},
a parallel dialect of Common Lisp.  This simulator was used to gain experience with
the language before freezing its design for full-scale implementation on a
Connection Machine computer system.  This example illustrates the typical manner
in which a language designer can embed a new language within the syntactic and
semantic framework of Lisp, saving the effort of designing an implementation
from scratch.

Connection Machine Lisp introduces a new data type called a \emph{xapping},
which is simply an unordered set of ordered pairs of Lisp objects.
The first element of each pair is called the \emph{index} and the second element
the \emph{value}.  We say that the xapping maps each index to its corresponding value.
No two pairs of the same xapping may have the same (that is, \cdf{eql}) index.
Xappings may be finite or infinite sets of pairs; only certain kinds
of infinite xappings are required, and special representations are used for them.

A finite xapping is notated by writing the pairs between braces, separated by whitespace.
A pair is notated by writing the index and the value, separated by a right arrow
(or an exclamation point if the host Common Lisp has no right-arrow character).

\beforenoterule
\begin{sideremark}
The original language design used the right arrow; the exclamation point was
chosen to replace it on {ASCII}-only terminals because it is one of
the six characters \cd{[~] \{~\} !~?} reserved by Common Lisp to the user.

While preparing the \TeX\ manuscript for this book I made a mistake
in font selection and discovered that by an absolutely incredible coincidence
the right arrow has the same numerical code (octal 41) within \TeX\ fonts
as the {ASCII} exclamation point.
The result was that although the manuscript called for right arrows,
exclamation points came out in the printed copy.  Imagine my astonishment!
\end{sideremark}
\afternoterule

Here is an example of a xapping that maps three symbols to strings:
% Stooges
\begin{lisp}
\{moe\Xarrowright "Oh, a wise guy, eh?" larry\Xarrowright "Hey, what's the idea?" \\*
 ~curly\Xarrowright "Nyuk, nyuk, nyuk!"\}
\end{lisp}
For convenience there are certain abbreviated notations.
If the index and value for a pair are the same object \emph{x},
then instead of having to write ``\emph{x}\Xarrowright\,\emph{x}''
(or, worse yet, ``\cd{\#43=\emph{x}\Xarrowright \#43\#}'')
we may write simply \emph{x} for the pair.
If all pairs of a xapping are of this form, we call the xapping a \emph{xet}.
For example, the notation
\begin{lisp}
\{baseball chess cricket curling bocce 43-man-squamish\}
\end{lisp}
is entirely equivalent in meaning to
\begin{lisp}
\{baseball\Xarrowright baseball curling\Xarrowright curling cricket\Xarrowright cricket \\*
~chess\Xarrowright chess bocce\Xarrowright bocce 43-man-squamish\Xarrowright 43-man-squamish\}
\end{lisp}
namely a xet of symbols naming six sports.

Another useful abbreviation covers the situation where the \emph{n} pairs of a finite
xapping are integers, collectively covering a range from zero to $\emph{n}-1$.
This kind of xapping is called a \emph{xector} and may be notated by writing
the values between brackets in ascending order of their indices.
Thus
\begin{lisp}
[tinker evers chance]
\end{lisp}
is merely an abbreviation for
\begin{lisp}
\{tinker\Xarrowright 0 evers\Xarrowright 1 chance\Xarrowright 2\}
\end{lisp}

There are two kinds of infinite xapping: constant and universal.
A constant xapping \cd{\{\Xarrowright \emph{z}\}} maps every object to the same value \emph{z}.
The universal xapping \cd{\{\Xarrowright\}} maps every object to itself and is therefore the xet
of all Lisp objects, sometimes called simply the universe.
Both kinds of infinite xet may be modified by explicitly writing exceptions.
One kind of exception is simply a pair, which specifies the value for a particular index;
the other kind of exception is simply \,\emph{k}\Xarrowright\, indicating that the xapping does
\emph{not} have a pair with index \emph{k} after all.  Thus the notation
\begin{lisp}
\{sky\Xarrowright blue grass\Xarrowright green idea\Xarrowright{} glass\Xarrowright{} \Xarrowright red\}
\end{lisp}
indicates a xapping that maps \cdf{sky} to \cdf{blue}, \cdf{grass} to \cdf{green},
and every other object except \cdf{idea} and \cdf{glass} to \cdf{red}.
Note well that the presence or absence of whitespace on either side
of an arrow is crucial to the correct interpretation
of the notation.

Here is the representation of a xapping as a structure:
\begin{lisp}
(defstruct \\*
~~(xapping (:print-function print-xapping) \\*
~~~~~~~~~~~(:constructor xap \\*
~~~~~~~~~~~~~(domain range \&optional \\*
~~~~~~~~~~~~~~(default ':unknown defaultp) \\*
~~~~~~~~~~~~~~(infinite (and defaultp :constant)) \\*
~~~~~~~~~~~~~~(exceptions '())))) \\
~~domain \\*
~~range \\*
~~default \\*
~~(infinite nil :type (member nil :constant :universal) \\*
~~exceptions)
\end{lisp}
The explicit pairs are represented as two parallel lists, one of indexes (\cdf{domain})
and one of values (\cdf{range}).  The \cdf{default} slot is the default value, relevant
only if the \cdf{infinite} slot is \cd{:constant}.
The \cdf{exceptions} slot is a list of indices for which there are no values.
(See the end of section~\ref{FORMAT-SECTION} for the definition of \cdf{print-xapping}.)

Here, then, is the code for reading xectors in bracket notation:
\begin{lisp}
(defun open-bracket-macro-char (stream macro-char) \\*
~~(declare (ignore macro-char)) \\*
~~(let ((range (read-delimited-list \#{\Xbackslash}] stream t))) \\*
~~~~(xap (iota-list (length range)) range))) \\
 \\
(set-macro-character \#{\Xbackslash}[ \#'open-bracket-macro-char) \\*
(set-macro-character \#{\Xbackslash}] (get-macro-character \#{\Xbackslash}) )) \\
 \\
(defun iota-list (n)~~~~~;\textrm{Return list of integers from $0$ to $\emph{n}-1$}\\*
~~(do ((j (- n 1) (- j 1)) \\*
~~~~~~~(z '() (cons j z))) \\*
~~~~~~((< j 0) z)))
\end{lisp}
The code for reading xappings in the more general brace notation, with all the
possibilities for xets (or individual xet pairs), infinite xappings, and exceptions,
is a bit more complicated; it is shown in table~\ref{XAPPING-MACRO-CHAR-TABLE}.
That code is used in conjunction with the initializations
\begin{lisp}
(set-macro-character \#{\Xbackslash}{\Xlbrace} \#'open-brace-macro-char) \\*
(set-macro-character \#{\Xbackslash}{\Xrbrace} (get-macro-character \#{\Xbackslash}) ))
\end{lisp}
\end{new}
\end{defun}


\begin{table}
\begin{new}
\caption{Macro Character Definition for Xapping Syntax}
\label{XAPPING-MACRO-CHAR-TABLE}
\begin{lisp}
(defun open-brace-macro-char (s macro-char) \\
~~(declare (ignore macro-char)) \\
~~(do ((ch (peek-char t s t nil t) (peek-char t s t nil t)) \\
~~~~~~~(domain '())~~(range '())~~(exceptions '())) \\
~~~~~~((char= ch \#{\Xbackslash}{\Xrbrace}) \\
~~~~~~~(read-char s t nil t) \\
~~~~~~~(construct-xapping (reverse domain) (reverse range))) \\
~~~~(cond ((char= ch \#{\Xbackslash}{\Xarrowright}) \\
~~~~~~~~~~~(read-char s t nil t) \\
~~~~~~~~~~~(let ((nextch (peek-char nil s t nil t))) \\
~~~~~~~~~~~~~(cond ((char= nextch \#{\Xbackslash}{\Xrbrace}) \\
~~~~~~~~~~~~~~~~~~~~(read-char s t nil t) \\
~~~~~~~~~~~~~~~~~~~~(return (xap (reverse domain) \\
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~(reverse range) \\
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~nil :universal exceptions))) \\
~~~~~~~~~~~~~~~~~~~(t (let ((item (read s t nil t))) \\
~~~~~~~~~~~~~~~~~~~~~~~~(cond ((char= (peek-char t s t nil t) \#{\Xbackslash}{\Xrbrace}) \\
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~(read-char s t nil t) \\
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~(return (xap (reverse domain) \\
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~(reverse range) \\
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~item :constant \\
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~exceptions))) \\
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~(t (reader-error s \\
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~"Default~{\Xarrowright} item must be last")))))))) \\
~~~~~~~~~~(t (let ((item (read-preserving-whitespace s t nil t)) \\
~~~~~~~~~~~~~~~~~~~(nextch (peek-char nil s t nil t))) \\
~~~~~~~~~~~~~~~(cond ((char= nextch \#{\Xbackslash}{\Xarrowright}) \\
~~~~~~~~~~~~~~~~~~~~~~(read-char s t nil t) \\
~~~~~~~~~~~~~~~~~~~~~~(cond ((member (peek-char nil s t nil t) \\
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~'(\#{\Xbackslash}Space \#{\Xbackslash}Tab \#{\Xbackslash}Newline)) \\
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~(push item exceptions)) \\
~~~~~~~~~~~~~~~~~~~~~~~~~~~~(t (push item domain) \\
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~(push (read s t nil t) range)))) \\
~~~~~~~~~~~~~~~~~~~~~((char= nch \#{\Xbackslash}{\Xrbrace}) \\
~~~~~~~~~~~~~~~~~~~~~~(read-char s t nil t) \\
~~~~~~~~~~~~~~~~~~~~~~(push item domain) \\
~~~~~~~~~~~~~~~~~~~~~~(push item range) \\
~~~~~~~~~~~~~~~~~~~~~~(return (xap (reverse domain) (reverse range)))) \\
~~~~~~~~~~~~~~~~~~~~~(t (push item domain) \\
~~~~~~~~~~~~~~~~~~~~~~~~(push item range))))))))
\end{lisp}
\end{new}
\end{table}

\begin{defun}[Function]
make-dispatch-macro-character char &optional non-terminating-p readtable

This causes the character \emph{char} to be a dispatching macro character
in \emph{readtable} (which defaults to the current readtable).
If \emph{non-terminating-p} is not {\false} (it defaults to {\false}),
then it will be a non-terminating macro character: it may be embedded
within extended tokens.
\cdf{make-dispatch-macro-character} returns {\true}.

Initially every character in the dispatch table has a character-macro
function that signals an error.  Use \cdf{set-dispatch-macro-character}
to define entries in the dispatch table.
\begin{new}
X3J13 voted in January 1989
\issue{ARGUMENTS-UNDERSPECIFIED}
to clarify that \emph{char} must be a character.
\end{new}

\end{defun}

\begin{defun}[Function]
set-dispatch-macro-character disp-char sub-char function &optional readtable \\
get-dispatch-macro-character disp-char sub-char ~~~~ &optional readtable

\cdf{set-dispatch-macro-character}
causes \emph{function} to be called when the \emph{disp-char}
followed by \emph{sub-char} is read.  The \emph{readtable} defaults to the
current readtable.  The arguments and return values for \emph{function} are
the same as for normal macro characters
except that \emph{function} gets \emph{sub-char}, not \emph{disp-char},
as its second argument and also receives a third
argument that is the non-negative integer whose decimal
representation appeared between
\emph{disp-char} and \emph{sub-char}, or {\false} if no decimal integer appeared
there.

The \emph{sub-char} may not be one of the ten decimal digits;
they are always reserved for specifying an infix integer argument.
Moreover, if \emph{sub-char} is a lowercase character
(see \cdf{lower-case-p}), its uppercase equivalent is used instead.
(This is how the rule is enforced that the case of a dispatch sub-character
doesn't matter.)

\cdf{set-dispatch-macro-character} returns {\true}.

\cdf{get-dispatch-macro-character} returns the macro-character function
for \emph{sub-char} under \emph{disp-char}, or {\nil} if there is no
function associated with \emph{sub-char}.

If the \emph{sub-char} is one of the ten decimal digits \cd{0 1 2 3 4 5 6 7 8 9},
\cdf{get-dispatch-macro-character} always returns {\nil}.
If \emph{sub-char} is a lowercase character,
its uppercase equivalent is used instead.

\begin{new}
X3J13 voted in January 1989
\issue{GET-MACRO-CHARACTER-READTABLE}
to specify that if \cdf{nil} is explicitly passed as the
second argument to \cdf{get-dispatch-macro-character}, then the standard readtable is used.
This is consistent with the behavior of \cdf{copy-readtable}.
\end{new}

For either function,
an error is signaled if the specified \emph{disp-char} is not in fact
a dispatch character in the specified readtable.  It is necessary
to use \cdf{make-dispatch-macro-character} to set up the
dispatch character before specifying its sub-characters.

As an example, suppose one would like \cd{\#\$\emph{foo}} to be read
as if it were \cd{(dollars \emph{foo})}.  One might say:
\begin{lisp}
(defun |\#\$-reader| (stream subchar arg) \\
~~(declare (ignore subchar arg)) \\
~~(list 'dollars (read stream t nil t))) \\
 \\
(set-dispatch-macro-character \#{\Xbackslash}\# \#{\Xbackslash}\$ \#'|\#\$-reader|)
\end{lisp}
\end{defun}

\begin{newer}
\begin{defun}[Function]
readtable-case readtable

X3J13 voted in June 1989 \issue{READ-CASE-SENSITIVITY}
to introduce the function \cdf{readtable-case} to
control the reader's interpretation of case.
It provides access to a slot in a readtable, and may be used with \cdf{setf}
to alter the state of that slot.
The possible values for the slot are \cd{:upcase}, \cd{:downcase},
\cd{:preserve}, and \cd{:invert}; the \cdf{readtable-case} for the standard readtable
is \cd{:upcase}.
Note that \cdf{copy-readtable} is required to copy the \cdf{readtable-case} slot
along with all other readtable information.

Once the reader has accumulated a token as described in section~\ref{READER},
if the token is a symbol, ``replaceable'' characters (unescaped uppercase or
lowercase constituent characters)
may be modified under the control of the \cdf{readtable-case} of the current readtable:
\begin{itemize}
\item For \cd{:upcase}, replaceable characters are converted to uppercase.
(This was the behavior specified by the first edition.)

\item For \cd{:downcase}, replaceable characters are converted to lowercase.

\item For \cd{:preserve}, the cases of all characters remain unchanged.

\item For \cd{:invert}, if all of the replaceable letters
in the extended token are of the same case, they are all converted to the opposite case;
otherwise the cases of all characters in that token remain unchanged.
\end{itemize}
As an illustration, consider the following code.
\begin{lisp}
(let ((*readtable* (copy-readtable nil))) \\*
~~(format t "READTABLE-CASE~~Input~~~Symbol-name{\Xtilde} \\*
~~~~~~~~~~~{\Xtilde}\%\hbox to 0pt{------------------\hss}~~~~~~~~~~~~~~~~~~-----------------{\Xtilde} \\*
~~~~~~~~~~~{\Xtilde}\%") \\
~~(dolist (readtable-case '(:upcase :downcase :preserve :invert)) \\*
~~~~(setf (readtable-case *readtable*) readtable-case) \\*
~~~~(dolist (input '("ZEBRA" "Zebra" "zebra")) \\
~~~~~~(format t ":{\Xtilde}A{\Xtilde}16T{\Xtilde}A{\Xtilde}24T{\Xtilde}A{\Xtilde}\%" \\*
~~~~~~~~~~~~~~~~(string-upcase readtable-case) \\*
~~~~~~~~~~~~~~~~input \\*
~~~~~~~~~~~~~~~~(symbol-name (read-from-string input)))))))
\end{lisp}
The output from this test code should be
\begin{lisp}
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{lisp}
\end{defun}
The \cdf{readtable-case} of the current readtable also affects the printing
of symbols (see \cdf{*print-case*} and \cdf{*print-escape*}).
\end{newer}

\subsection{What the Print Function Produces}
\label{PRINTER}

The Common Lisp printer is controlled by a number of special variables.
These are referred to in the following discussion
and are fully documented at the end of this section.

How an expression is printed depends on its data type, as described
in the following paragraphs.

\begin{flushdesc}
\item[\emph{Integers}]
If appropriate, a radix specifier may be printed; see the
variable \cd{*print-radix*}.
If an integer is negative, a minus sign is printed and then the
absolute value of the integer is printed.
Integers are printed in the radix specified by the
variable \cd{*print-base*}
in the usual positional notation, most significant digit first.
The number zero is represented
by the single digit \cd{0} and never has a sign.
A decimal point may then be printed, depending on the value
of \cd{*print-radix*}.

\item[\emph{Ratios}]
If appropriate, a radix specifier may be printed; see the variable
\cd{*print-radix*}.
If the ratio is negative, a minus sign is printed.
Then the absolute value of the numerator is printed, as for an integer;
then a \cdf{/}; then the denominator.  The numerator and denominator are
both printed in the radix specified by the variable \cd{*print-base*}; they are obtained as if by
the \cdf{numerator} and \cdf{denominator} functions, and so ratios
are always printed in reduced form (lowest terms).

\item[\emph{Floating-point numbers}]
If the sign of the number (as determined by the function \cdf{float-sign})
is negative, then a minus sign is printed.  Then the magnitude is
printed in one of two ways.
If the magnitude of the
floating-point number is either zero or between $10^{-3}$ (inclusive)
and $10^7$ (exclusive), it may be printed as
the integer part of the number, then a decimal point,
followed by the fractional part of the number; there is always at least one
digit on each side of the decimal point.
If the format of the number does not match that specified by the variable
\cdf{*read-default-float-format*}, then the exponent marker for
that format and the digit \cd{0} are also printed.
For example, the base of the natural logarithms as a short-format
floating-point number might be printed as \cd{2.71828S0}.

For non-zero magnitudes
outside of the range $10^{-3}$
to $10^7$, a floating-point number
will be printed in ``computerized scientific
notation.''  The representation of the number is scaled to be between
1 (inclusive) and 10 (exclusive) and then printed, with one digit
before the decimal point and at least one digit after the decimal point.
Next the exponent marker for the format is printed,
except that
if the format of the number matches that specified by the variable
\cdf{*read-default-float-format*}, then the exponent marker \cdf{E}
is used.
Finally, the power of 10 by which the fraction must be multiplied
to equal the original number is printed as a decimal integer.
For example, Avogadro's number as a short-format floating-point number
might be printed as \cd{6.02S23}.

\item[\emph{Complex numbers}]
A complex number is printed as \cd{\#C},
an open parenthesis,
the printed representation of its real part, a space,
the printed representation of its imaginary part, and finally
a close parenthesis.


\begin{obsolete}
\item[\emph{Characters}]
When \cdf{*print-escape*} is {\false}, a character prints as itself;
it is sent directly to the output stream.
When \cdf{*print-escape*} is not {\false}, then \cd{\#{\Xbackslash}} syntax is used.
For example, the
printed representation of the character \cd{\#{\Xbackslash}A} with control and meta
bits on would be \cd{\#{\Xbackslash}CONTROL-META-A}, and that of \cd{\#{\Xbackslash}a} with
control and meta bits on would be \cd{\#{\Xbackslash}CONTROL-META-{\Xbackslash}a}.
\end{obsolete}
\begin{newer}
X3J13 voted in June 1989 \issue{DATA-IO} to specify that if \cd{*print-readably*}
is not {\false} then every object must be printed in a readable form,
regardless of other printer control variables.  For characters, the simplest approach
is always to use \cd{\#{\Xbackslash}} syntax when \cd{*print-readably*}
is not {\false}, regardless of the value of \cdf{*print-escape*}.
\end{newer}


\begin{obsolete}
\item[\emph{Symbols}]

When \cdf{*print-escape*} is {\false}, only the characters of the print name
of the symbol are output (but the case in which to print any
uppercase characters in the print name is controlled by the
variable \cdf{*print-case*}).
\end{obsolete}

\begin{newer}
X3J13 voted in June 1989 \issue{READ-CASE-SENSITIVITY}
to specify that the new \cdf{readtable-case} slot of the current readtable
also controls the case in which letters (whether uppercase or lowercase)
in the print name of a symbol are output, no matter what the value of \cdf{*print-escape*}.
\end{newer}

\begin{obsolete}
The remaining paragraphs describing the printing of symbols cover
the situation when \cdf{*print-escape*} is not {\false}.
\end{obsolete}

\begin{newer}
X3J13 voted in June 1989 \issue{DATA-IO} to specify that if \cd{*print-readably*}
is not {\false} then every object must be printed in a readable form,
regardless of other printer control variables.
For symbols, the simplest approach
is to print them, when \cd{*print-readably*} is not {\false}, as if \cdf{*print-escape*}
were not {\false}, regardless of the actual value of \cdf{*print-escape*}.
\end{newer}

Backslashes \cd{{\Xbackslash}} and
vertical bars \cd{|} are included as required.  In particular,
backslash or vertical-bar syntax is used when the name of
the symbol would be otherwise treated by the reader as a potential number
(see section~\ref{PARSE-TOKENS-SECTION}).
In making this decision, it is assumed that the value of \cd{*print-base*}
being used for printing would be used as the value of \cd{*read-base*}
used for reading; the value of \cd{*read-base*} at the time of printing
is irrelevant.  For example, if the value of \cd{*print-base*} were \cd{16}
when printing the symbol \cdf{face}, it would have to be printed as
\cd{{\Xbackslash}FACE} or \cd{{\Xbackslash}Face} or \cd{|FACE|}, because the token
\cdf{face} would be read as a hexadecimal
number (decimal value 64206) if \cd{*read-base*} were \cd{16}.

\begin{obsolete}
The case in which to print any
uppercase characters in the print name is controlled by the
variable \cdf{*print-case*}.
\end{obsolete}
\begin{newer}
X3J13 voted in June 1989 \issue{PRINT-CASE-PRINT-ESCAPE-INTERACTION}
to clarify the interaction of \cdf{*print-case*} with \cdf{*print-escape*};
see \cdf{*print-case*}.
\end{newer}
As a special case [no pun intended], {\nil} may sometimes be printed as \cd{()} instead,
when \cdf{*print-escape*} and \cdf{*print-pretty*} are both not {\false}.

Package prefixes may be printed (using colon syntax)
if necessary.
The rules for package qualifiers are as follows.
When the symbol is printed, if it is in the
keyword package, then it is printed with a preceding colon; otherwise, if
it is accessible in the current package, it is printed without any
qualification; otherwise, it is printed with qualification.
See chapter~\ref{XPACK}.

\begin{obsolete}
A symbol that is uninterned (has no home package) is printed
preceded by \cd{\#:} if the variables \cd{*print-gensym*}
and \cdf{*print-escape*} are both non-{\nil};
if either is {\nil}, then the symbol is printed without
a prefix, as if it were in the current package.
\end{obsolete}
\begin{newer}
X3J13 voted in June 1989 \issue{DATA-IO} to specify that if \cd{*print-readably*}
is not {\false} then every object must be printed in a readable form,
regardless of other printer control variables.  For uninterned symbols, the simplest approach
is to print them, when \cd{*print-readably*} is not {\false}, as if \cdf{*print-escape*}
and \cd{*print-gensym*}
were not {\false}, regardless of their actual values.
\end{newer}

\beforenoterule
\begin{implementation}
Because the \cd{\#:} syntax does not intern the
following symbol, it is necessary to use circular-list syntax
if \cdf{*print-circle*} is not {\false} and
the same uninterned symbol appears several times in an expression
to be printed.  For example, the result of
\begin{lisp}
(let ((x (make-symbol "FOO"))) (list x x))
\end{lisp}
would be printed as
\begin{lisp}
\cd{(\#:foo \#:foo)}
\end{lisp}
if \cdf{*print-circle*}
were {\false}, but as
\begin{lisp}
\cd{(\#1{\Xequal}\#:foo \#1\#)}
\end{lisp}
if \cdf{*print-circle*}
were not {\false}.
\end{implementation}
\afternoterule

\begin{obsolete}
The case in which symbols are to be printed is controlled by the variable
\cdf{*print-case*}.
\end{obsolete}
\begin{newer}
It is also controlled by \cdf{*print-escape*} and the \cdf{readtable-case} slot of the current
readtable (the value of \cd{*readtable*}).
\end{newer}
\begin{obsolete}
\item[\emph{Strings}]
The characters of the string are output in order.
If \cdf{*print-escape*} is not {\false}, a double quote
is output before and after, and all
double quotes and single escape characters are preceded by backslash.
The printing of strings is not affected by \cd{*print-array*}.
If the string has a fill pointer, then only those characters below
the fill pointer are printed.
\end{obsolete}

\begin{newer}
X3J13 voted in June 1989 \issue{DATA-IO} to specify that if \cd{*print-readably*}
is not {\false} then every object must be printed in a readable form,
regardless of other printer control variables.  For strings, the simplest approach
is to print them, when \cd{*print-readably*} is not {\false}, as if \cdf{*print-escape*}
were not {\false}, regardless of the actual value of \cdf{*print-escape*}.
\end{newer}

\item[\emph{Conses}]
Wherever possible, list notation is preferred over dot
notation.  Therefore the following algorithm is used:
\begin{enumerate}
\item Print an open parenthesis, \cd{(}.
\item Print the \emph{car} of the cons.
\item If the \emph{cdr} is a cons, make it the current cons, print a space, and go to step 2.
\item If the \emph{cdr} is not null, print a space, a dot, a space, and the \emph{cdr}.
\item Print a close parenthesis, \cd{)}.
\end{enumerate}

This form of printing is clearer than showing each individual cons
cell.  Although the two expressions below are equivalent,
and the reader will accept
either one and produce the same data structure, the printer will
always print such a data structure in the second form.
\begin{lisp}
(a . (b . ((c . (d . {\nil})) . (e . {\nil})))) \\
\\
(a b (c d) e)
\end{lisp}
\begin{obsolete}
The printing of conses is affected by the variables \cd{*print-level*}
and \cd{*print-length*}.
\end{obsolete}

\begin{newer}
X3J13 voted in June 1989 \issue{DATA-IO} to specify that if \cd{*print-readably*}
is not {\false} then every object must be printed in a readable form,
regardless of other printer control variables.  For conses, the simplest approach
is to print them, when \cd{*print-readably*} is not {\false}, as if \cd{*print-level*}
and \cd{*print-length*} were {\false}, regardless of their actual values.
\end{newer}

\begin{obsolete}
\item[\emph{Bit-vectors}]
A bit-vector is printed as \cd{\#*} followed by the bits of the bit-vector
in order.  If \cd{*print-array*} is {\false}, however, then the bit-vector is
printed in a format (using \cd{\#<}) that is concise but not readable.
If the bit-vector has a fill pointer, then only those bits below
the fill pointer are printed.
\end{obsolete}
\begin{newer}
X3J13 voted in June 1989 \issue{DATA-IO} to specify that if \cd{*print-readably*}
is not {\false} then every object must be printed in a readable form,
regardless of other printer control variables.  For bit-vectors, the simplest approach
is to print them, when \cd{*print-readably*} is not {\false}, as if \cd{*print-array*}
were not {\false}, regardless of the actual value of \cd{*print-array*}.
\end{newer}

\item[\emph{Vectors}]
Any vector other than a string or bit-vector is printed using
general-vector syntax; this means that information
about specialized vector representations will be lost.
The printed representation of a zero-length vector is \cd{\#()}.  The
printed representation of a non-zero-length vector begins with \cd{\#(}.
Following that, the first element of the vector is printed.  If
there are any other elements, they are printed in turn, with a space
printed before each additional element.  A close parenthesis
after the
last element terminates the printed representation of the vector.
\begin{obsolete}
The
printing of vectors is affected by the variables \cd{*print-level*} and
\cd{*print-length*}.
If the vector has a fill pointer, then only those elements below
the fill pointer are printed.

If \cd{*print-array*} is {\false}, however, then the vector is not printed
as described above, but
in a format (using \cd{\#<}) that is concise but not readable.
\end{obsolete}
\begin{newer}
X3J13 voted in June 1989 \issue{DATA-IO} to specify that if \cd{*print-readably*}
is not {\false} then every object must be printed in a readable form,
regardless of other printer control variables.  For vectors, the simplest approach
is to print them, when \cd{*print-readably*} is not {\false}, as if \cd{*print-level*}
and \cd{*print-length*} were {\false} and \cd{*print-array*} were not {\false},
regardless of their actual values.
\end{newer}

\item[\emph{Arrays}]
Normally any array other than a vector is printed
using \cd{\#\emph{n}A} format.  Let \emph{n} be the rank of the array.
Then \cd{\#} is printed, then \emph{n} as a decimal integer,
then \cdf{A}, then \emph{n} open parentheses.  Next the elements
are scanned in row-major order.  Imagine the array indices being
enumerated in odometer fashion, recalling that the dimensions
are numbered from 0 to $\emph{n}-1$.  Every time the index for
dimension \emph{j} is incremented, the following actions are taken:
\begin{enumerate}
\item
If $\emph{j}<\emph{n}-1$, then print a close parenthesis.

\item
If incrementing the index for dimension \emph{j} caused it to equal
dimension \emph{j}, reset that index to zero and increment dimension
$\emph{j}-1$ (thereby performing these three steps recursively),
unless $\emph{j}=0$, in which case simply terminate the entire algorithm.
If incrementing the index for dimension \emph{j} did not cause it to
equal dimension \emph{j}, then print a space.

\item
If $\emph{j}<\emph{n}-1$, then print an open parenthesis.
\end{enumerate}
This causes the contents to be printed in a format suitable for
use as the \cd{:initial-\discretionary{}{}{}contents} argument to \cdf{make-array}.
\begin{obsolete}
The lists effectively printed by this procedure are subject to
truncation by \cd{*print-level*} and \cd{*print-length*}.
\end{obsolete}

If the array is of a specialized type, containing bits or string-characters,
then the innermost lists generated by the algorithm given above may instead
be printed using bit-vector or string syntax, provided that these innermost
lists would not be subject to truncation by \cd{*print-length*}.  For example,
a 3-by-2-by-4 array of string-characters that would ordinarily be printed as
\begin{lisp}
\#3A(((\#{\Xbackslash}s \#{\Xbackslash}t \#{\Xbackslash}o \#{\Xbackslash}p) (\#{\Xbackslash}s \#{\Xbackslash}p \#{\Xbackslash}o \#{\Xbackslash}t)) \\
~~~~((\#{\Xbackslash}p \#{\Xbackslash}o \#{\Xbackslash}s \#{\Xbackslash}t) (\#{\Xbackslash}p \#{\Xbackslash}o \#{\Xbackslash}t \#{\Xbackslash}s)) \\
~~~~((\#{\Xbackslash}t \#{\Xbackslash}o \#{\Xbackslash}p \#{\Xbackslash}s) (\#{\Xbackslash}o \#{\Xbackslash}p \#{\Xbackslash}t \#{\Xbackslash}s)))
\end{lisp}
may instead be printed more concisely as
\begin{lisp}
\#3A(("stop" "spot") ("post" "pots") ("tops" "opts"))
\end{lisp}

\begin{obsolete}
If \cd{*print-array*} is {\false}, then the array is printed
in a format (using \cd{\#<}) that is concise but not readable.
\end{obsolete}
\begin{newer}
X3J13 voted in June 1989 \issue{DATA-IO} to specify that if \cd{*print-readably*}
is not {\false} then every object must be printed in a readable form,
regardless of other printer control variables.  For arrays, the simplest approach
is to print them, when \cd{*print-readably*} is not {\false}, as if \cd{*print-level*}
and \cd{*print-length*} were {\false} and \cd{*print-array*} were not {\false},
regardless of their actual values.
\end{newer}

\item[\emph{Random-states}]
Common Lisp does not specify a specific syntax
for printing objects of type \cdf{random-state}.  However, every implementation
must arrange to print a random-state object in such a way that,
within the same implementation of Common Lisp, the function \cdf{read}
can construct from the printed representation a copy of the random-state
object as if the copy had been made by \cdf{make-random-state}.

\item[\emph{Pathnames}]
If \cdf{*print-escape*} is true, a pathname
should be printed by \cdf{write} as \cd{\#P"..."} where \cd{"..."} is the
namestring representation of the pathname.  If \cdf{*print-escape*}
is false, \cdf{write} prints a pathname by printing its namestring
(presumably without escape characters or surrounding double quotes).

If \cd{*print-readably*}
is not {\false} then every object must be printed in a readable form,
regardless of other printer control variables.  For pathnames, the simplest approach
is to print them, when \cd{*print-readably*} is not {\false}, as if \cdf{*print-escape*}
were {\false},
regardless of its actual value.
\end{flushdesc}

Structures defined by \cdf{defstruct} are printed under the
control of the user-specified \cd{:print-function} option to \cdf{defstruct}.
If the user does not provide a printing function explicitly,
then a default printing function is supplied that prints the structure
using \cd{\#S} syntax (see section~\ref{SHARP-SIGN-MACRO-CHARACTER-SECTION}).

If \cd{*print-readably*}
is not {\false} then every object must be printed in a readable form,
regardless of the values of other printer control variables; if this is not possible,
then an error of type \cdf{print-not-readable} must be signaled to avoid
printing an unreadable syntax such as \cd{\#<...>}.

Macro \cdf{print-unreadable-object} prints an object using \cd{\#<...>}
syntax and also takes care of checking the variable \cd{*print-readably*}.

When debugging or when frequently dealing with large or
deep objects at top level, the user may wish to restrict the printer
from printing large amounts of information.  The variables
\cd{*print-level*} and \cd{*print-length*} allow the user to control how deep
the printer will print and how many elements at a given level the
printer will print.  Thus the user can see enough of the object to
identify it without having to wade through the entire expression.

\begin{defun}[Variable]
*print-readably*

The default value of \cd{*print-readably*} is
  \cdf{nil}.  If \cd{*print-readably*} is true, then printing any object must either
  produce a
  printed representation that the reader will accept or signal an error.
  If printing is successful, the reader will, on reading the printed representation,
  produce an object that is ``similar as a constant''
  (see section~\ref{SIMILAR-AS-A-CONSTANT-SECTION}) to the object that was printed.

  If \cd{*print-readably*} is true and printing a readable printed
  representation is not possible, the printer signals an error of type
  \cdf{print-not-readable} rather than using an unreadable syntax such as \cd{\#<}.
  The printed representation produced when \cd{*print-readably*} is true might
  or might not be the same as the printed representation produced when
  \cd{*print-readably*} is false.

  If \cd{*print-readably*} is true and another printer control variable
  (such as \cd{*print-length*}, \cd{*print-level*}, \cdf{*print-escape*}, \cd{*print-gensym*},
  \cd{*print-\discretionary{}{}{}array*}, or an implementation-defined printer control variable)
  would cause the preceding requirements to be violated, that other
  printer control variable is ignored.

  The printing of interned symbols is not affected by \cd{*print-readably*}.

  Note that the ``similar as a constant'' rule for readable printing
  implies that \cd{\#A} or \cd{\#(} syntax cannot be used for arrays of element-type
  other than \cdf{t}.  An implementation will have to use another syntax or
  signal a \cdf{print-not-readable} error.  A \cdf{print-not-readable} error will not
  be signaled for strings or bit-vectors.

  All methods for \cdf{print-object} must obey \cd{*print-readably*}.  This
  rule applies to both user-defined methods and implementation-defined methods.

  The reader control variable \cd{*read-eval*} also affects printing.
  If \cd{*read-eval*} is false and \cd{*print-readably*} is true, any \cdf{print-object}
  method that would otherwise output a \cd{\#.} reader macro must either output something
  different or signal an error of type \cdf{print-not-readable}.

  Readable printing of structures and objects of type \cdf{standard-object}
  is controlled
  by their \cdf{print-object} methods, not by their \cdf{make-load-form} methods.
  ``Similarity as a constant'' for these objects is application-dependent
  and hence is defined to be whatever these methods do.

  \cd{*print-readably*} allows errors involving data with no
  readable printed representation to be detected when writing the file rather than
  later on when the file is read.

  \cd{*print-readably*} is more rigorous than \cdf{*print-escape*}; output printed
  with escapes must be merely generally recognizable by humans, with a good chance
  of being recognizable by computers, whereas
  output printed readably must be reliably recognizable by computers.
\end{defun}

\begin{defun}[Variable]
*print-escape*

When this flag is {\false}, then escape characters are not output
when an expression is printed.  In particular, a symbol is printed
by simply printing the characters of its print name.
The function \cdf{princ} effectively binds \cdf{*print-escape*} to {\false}.

When this flag is not {\false}, then an attempt is made to print an
expression in such a way that it can be read again to produce an
\cdf{equal} structure.
The function \cd{prin1} effectively binds \cdf{*print-escape*} to {\true}.
The initial value of this variable is {\true}.
\end{defun}

\begin{defun}[Variable]
*print-pretty*

When this flag is {\false}, then only a small amount of whitespace is
output when printing an expression.

When this flag is not {\false}, then the printer will endeavor to insert
extra whitespace where appropriate to make the expression more readable.
A few other simple changes may be made, such as printing \cd{'foo}
instead of \cd{(quote foo)}.

The initial value of \cdf{*print-pretty*} is implementation-dependent.

\begin{new}
X3J13 voted in January 1989
\issue{PRETTY-PRINT-INTERFACE}
to adopt a facility for user-controlled pretty printing
in Common Lisp
(see chapter~\ref{PPRINT}).
\end{new}
\end{defun}

\begin{defun}[Variable]
*print-circle*

When this flag is {\false} (the default), then the printing process proceeds
by recursive descent; an attempt to print a circular structure may lead
to looping behavior and failure to terminate.

If \cdf{*print-circle*} is true, the printer is required
to detect not only cycles but shared substructure, indicating both through the
use of \cd{\#\emph{n\/}=} and \cd{\#\emph{n\/}\#} syntax.
As an example, under the specification of the first edition
\begin{lisp}
(print '(\#1=(a \#1\#) \#1\#))
\end{lisp}
might legitimately print \cd{(\#1=(A \#1\#) \#1\#)} or
\cd{(\#1=(A \#1\#) \#2=(A \#2\#))}; the vote specifies that the first
form is required.

User-defined printing functions for the \cdf{defstruct}
\cd{:print-function} option, as well as user-defined methods for the
CLOS generic function \cdf{print-object}, may print objects to the
supplied stream using \cdf{write}, \cd{print1}, \cdf{princ}, \cdf{format},
or \cdf{print-object} and expect circularities to be detected and printed
using \cd{\#\emph{n\/}\#} syntax (when \cdf{*print-circle*} is non-\cdf{nil}, of course).

It seems to me that the same ought to apply to abbreviation
as controlled by \cd{*print-level*} and \cd{*print-length*}, but that
was not addressed by this vote.
\end{defun}

\begin{defun}[Variable]
*print-base*

The value of \cd{*print-base*} determines in what radix the printer will print
rationals.  This may be any integer from \cd{2} to \cd{36}, inclusive;
the default value is \cd{10} (decimal radix).
For radices above \cd{10}, letters of the alphabet are used to represent
digits above \cd{9}.
\end{defun}

\begin{defun}[Variable]
*print-radix*

If the variable \cd{*print-radix*} is non-{\false}, the printer will print a
radix specifier to indicate the radix in which it is printing a rational
number.  To prevent confusion of the letter \cdf{O} with the digit \cd{0},
and of the letter \cdf{B} with the digit \cd{8}, the radix specifier
is always printed using lowercase letters.
For example, if the current base is twenty-four (decimal), the
decimal integer twenty-three would print as \cd{\#24rN}.  If \cd{*print-base*}
is \cd{2}, \cd{8}, or \cd{16}, then the radix specifier used is \cd{\#b},
\cd{\#o}, or \cd{\#x}.  For integers, base ten is indicated by a trailing
decimal point instead of a leading radix specifier; for ratios, however,
\cd{\#10r} is used.  The default value of \cd{*print-radix*} is {\false}.
\end{defun}

\begin{defun}[Variable]
*print-case*

The \cdf{read} function normally converts lowercase characters
appearing in symbols to corresponding uppercase characters,
so that internally print
names normally contain only uppercase characters.
However, users may prefer to see output using lowercase letters
or letters of mixed case.
This variable controls the case (upper, lower, or mixed) in which to print
any uppercase characters in the names of symbols
when vertical-bar syntax is not used.
The value of \cdf{*print-case*} should be one of the keywords
\cd{:upcase}, \cd{:downcase}, or \cd{:capitalize};
the initial value is \cd{:upcase}.

Lowercase characters in the internal print name
are always printed in lowercase, and are
preceded by a single escape character or enclosed by multiple
escape characters.
Uppercase characters in the internal print name
are printed in uppercase, in lowercase, or in mixed case
so as to capitalize words, according to the value of
\cdf{*print-case*}.  The convention for what constitutes
a ``word'' is the same as for the function \cdf{string-capitalize}.

\begin{newer}
X3J13 voted in June 1989 \issue{PRINT-CASE-PRINT-ESCAPE-INTERACTION}
to clarify the interaction of \cdf{*print-case*} with \cdf{*print-escape*}.
When \cdf{*print-escape*} is \cdf{nil}, \cdf{*print-case*} determines the
case in which to print all uppercase characters in the print name of the symbol.
When \cdf{*print-escape*} is not \cdf{nil}, the implementation has some freedom
as to which characters will be printed so as to appear in an ``escape context''
(after an escape character, typically~\cd{\Xbackslash}, or between multiple escape characters,
typically~\cd{|}); \cdf{*print-case*} determines the
case in which to print all uppercase characters that will not appear in an escape context.
For example, when the value of \cdf{*print-case*} is \cd{:upcase},
an implementation might choose to print the symbol whose print name is \cd{"(S)HE"}
as \cd{{\Xbackslash}(S{\Xbackslash})HE} or as \cd{|(S)HE|}, among other possibilities.
When the value of \cdf{*print-case*} is \cd{:downcase}, the corresponding output
should be \cd{{\Xbackslash}(s{\Xbackslash})he} or \cd{|(S)HE|}, respectively.

Consider the following test code.  (For the sake of this example
assume that \cdf{readtable-case} is \cd{:upcase} in the current readtable; this is
discussed further below.)
\begin{lisp}
(let ((tabwidth 11)) \\*
~~(dolist (sym '(|x| |FoObAr| |fOo|)) \\*
~~~~(let ((tabstop -1)) \\
~~~~~~(format t "{\Xtilde}\&") \\*
~~~~~~(dolist (escape '(t nil)) \\
~~~~~~~~(dolist (case '(:upcase :downcase :capitalize)) \\
~~~~~~~~~~(format t "{\Xtilde}VT" (* (incf tabstop) tabwidth)) \\*
~~~~~~~~~~(write sym :escape escape :case case))))) \\*
~~(format t "~\%"))
\end{lisp}
An implementation that leans heavily on multiple-escape characters (vertical bars)
might produce the following output:
\begin{lisp}
|x|~~~~~~~~|x|~~~~~~~~|x|~~~~~~~~x~~~~~~~~~~x~~~~~~~~~~x \\*
|FoObAr|~~~|FoObAr|~~~|FoObAr|~~~FoObAr~~~~~foobar~~~~~Foobar \\*
|fOo|~~~~~~|fOo|~~~~~~|fOo|~~~~~~fOo~~~~~~~~foo~~~~~~~~foo
\end{lisp}
An implementation that leans heavily on single-escape characters (backslashes)
might produce the following output:
\begin{lisp}
{\Xbackslash}x~~~~~~~~~{\Xbackslash}x~~~~~~~~~{\Xbackslash}x~~~~~~~~~x~~~~~~~~~~x~~~~~~~~~~x \\*
F{\Xbackslash}oO{\Xbackslash}bA{\Xbackslash}r~~f{\Xbackslash}oo{\Xbackslash}ba{\Xbackslash}r~~F{\Xbackslash}oo{\Xbackslash}ba{\Xbackslash}r~~FoObAr~~~~~foobar~~~~~Foobar \\*
{\Xbackslash}fO{\Xbackslash}o~~~~~~{\Xbackslash}fo{\Xbackslash}o~~~~~~{\Xbackslash}fo{\Xbackslash}o~~~~~~fOo~~~~~~~~foo~~~~~~~~foo
\end{lisp}
These examples are not exhaustive; output using both kinds of escape characters
(for example, \cd{|FoO|{\Xbackslash}bA{\Xbackslash}r}) is permissible (though ugly).

X3J13 voted in June 1989 \issue{READ-CASE-SENSITIVITY}
to add a new \cdf{readtable-case} slot to readtables to control
automatic case conversion during the reading of symbols.
The value of \cdf{readtable-case} in the current readtable also affects the printing
of unescaped letters (letters appearing in an escape context are always
printed in their own case).
\begin{itemize}
\item If \cdf{readtable-case} is \cd{:upcase}, unescaped uppercase letters are printed
    in the case specified by \cdf{*print-case*} and unescaped lowercase letters
    are printed in their own case.  (If \cdf{*print-escape*} is non-{\false},
    all lowercase letters will necessarily be escaped.)

\item If \cdf{readtable-case} is \cd{:downcase}, unescaped lowercase letters are printed
    in the case specified by \cdf{*print-case*} and unescaped uppercase letters
    are printed in their own case.  (If \cdf{*print-escape*} is non-{\false},
    all uppercase letters will necessarily be escaped.)

\item  If \cdf{readtable-case} is \cd{:preserve},
    all unescaped letters are printed in their own case,
    regardless of the value of \cdf{*print-case*}.  There is no
    need to escape any letters, even if \cdf{*print-escape*} is non-{\false},
    though the X3J13 vote did not prohibit escaping letters in this situation.

\item If \cdf{readtable-case} is \cd{:invert},
    and if all unescaped letters are of the same
    case, then the case of all the unescaped letters is inverted; but if the unescaped
    letters are not all of the same case then each is printed in its own case.
    (Thus \cd{:invert} does not always invert the case; the inversion is conditional.)
    There is no
    need to escape any letters, even if \cdf{*print-escape*} is non-{\false},
    though the X3J13 vote did not prohibit escaping letters in this situation.
\end{itemize}
Consider the following code.
\begin{lisp}
;;; Generate a table illustrating READTABLE-CASE and *PRINT-CASE*. \\*
\\*
(let ((*readtable* (copy-readtable nil)) \\*
~~~~~~(*print-case* *print-case*)) \\*
~~(format t "READTABLE-CASE~*PRINT-CASE*~~Symbol-name~~Output{\Xtilde} \\*
~~~~~~~~~~~{\Xtilde}\%\hbox to 0pt{-------------------------\hss}~~~~~~~~~~~~~~~~~~~~~~~~~-------------------------{\Xtilde} \\*
~~~~~~~~~~~{\Xtilde}\%") \\
~~(dolist (readtable-case '(:upcase :downcase :preserve :invert)) \\*
~~~~(setf (readtable-case *readtable*) readtable-case) \\*
~~~~(dolist (print-case '(:upcase :downcase :capitalize)) \\*
~~~~~~(dolist (sym '(|ZEBRA| |Zebra| |zebra|)) \\*
~~~~~~~~(setq *print-case* print-case) \\
~~~~~~~~(format t ":{\Xtilde}A{\Xtilde}15T:{\Xtilde}A{\Xtilde}29T{\Xtilde}A{\Xtilde}42T{\Xtilde}A{\Xtilde}\%" \\*
~~~~~~~~~~~~~~~~~~(string-upcase readtable-case) \\*
~~~~~~~~~~~~~~~~~~(string-upcase print-case) \\*
~~~~~~~~~~~~~~~~~~(symbol-name sym) \\*
~~~~~~~~~~~~~~~~~~(prin1-to-string sym)))))))
\end{lisp}

\vskip 0pt plus 3pt
\noindent
Note that the call to \cd{prin1-to-string}
(the last argument in the call to \cdf{format} that is within the nested loops)
effectively uses a non-{\false} value for \cdf{*print-escape*}.

Assuming an implementation that uses vertical bars around a symbol name
if any characters need escaping,
the output from this test code should be
\def\foo{-6pt}
\begin{lisp}
READTABLE-CASE *PRINT-CASE*~~Symbol-name~~Output \\*
-------------------------------------------------- \\*
:UPCASE~~~~~~~~:UPCASE~~~~~~~ZEBRA~~~~~~~~ZEBRA \\*
:UPCASE~~~~~~~~:UPCASE~~~~~~~Zebra~~~~~~~~|Zebra| \\*
:UPCASE~~~~~~~~:UPCASE~~~~~~~zebra~~~~~~~~|zebra| \\*
:UPCASE~~~~~~~~:DOWNCASE~~~~~ZEBRA~~~~~~~~zebra \\*
:UPCASE~~~~~~~~:DOWNCASE~~~~~Zebra~~~~~~~~|Zebra| \\*
:UPCASE~~~~~~~~:DOWNCASE~~~~~zebra~~~~~~~~|zebra| \\
:UPCASE~~~~~~~~:CAPITALIZE~~~ZEBRA~~~~~~~~Zebra \\*
:UPCASE~~~~~~~~:CAPITALIZE~~~Zebra~~~~~~~~|Zebra| \\*
:UPCASE~~~~~~~~:CAPITALIZE~~~zebra~~~~~~~~|zebra| \\
:DOWNCASE~~~~~~:UPCASE~~~~~~~ZEBRA~~~~~~~~|ZEBRA| \\*
:DOWNCASE~~~~~~:UPCASE~~~~~~~Zebra~~~~~~~~|Zebra| \\*
:DOWNCASE~~~~~~:UPCASE~~~~~~~zebra~~~~~~~~ZEBRA \\
:DOWNCASE~~~~~~:DOWNCASE~~~~~ZEBRA~~~~~~~~|ZEBRA| \\*
:DOWNCASE~~~~~~:DOWNCASE~~~~~Zebra~~~~~~~~|Zebra| \\*
:DOWNCASE~~~~~~:DOWNCASE~~~~~zebra~~~~~~~~zebra \\
:DOWNCASE~~~~~~:CAPITALIZE~~~ZEBRA~~~~~~~~|ZEBRA| \\*
:DOWNCASE~~~~~~:CAPITALIZE~~~Zebra~~~~~~~~|Zebra| \\*
:DOWNCASE~~~~~~:CAPITALIZE~~~zebra~~~~~~~~Zebra \\
:PRESERVE~~~~~~:UPCASE~~~~~~~ZEBRA~~~~~~~~ZEBRA \\*
:PRESERVE~~~~~~:UPCASE~~~~~~~Zebra~~~~~~~~Zebra \\*
:PRESERVE~~~~~~:UPCASE~~~~~~~zebra~~~~~~~~zebra \\
:PRESERVE~~~~~~:DOWNCASE~~~~~ZEBRA~~~~~~~~ZEBRA \\*
:PRESERVE~~~~~~:DOWNCASE~~~~~Zebra~~~~~~~~Zebra \\*
:PRESERVE~~~~~~:DOWNCASE~~~~~zebra~~~~~~~~zebra \\
:PRESERVE~~~~~~:CAPITALIZE~~~ZEBRA~~~~~~~~ZEBRA \\*
:PRESERVE~~~~~~:CAPITALIZE~~~Zebra~~~~~~~~Zebra \\*
:PRESERVE~~~~~~:CAPITALIZE~~~zebra~~~~~~~~zebra \\
:INVERT~~~~~~~~:UPCASE~~~~~~~ZEBRA~~~~~~~~zebra \\*
:INVERT~~~~~~~~:UPCASE~~~~~~~Zebra~~~~~~~~Zebra \\*
:INVERT~~~~~~~~:UPCASE~~~~~~~zebra~~~~~~~~ZEBRA \\
:INVERT~~~~~~~~:DOWNCASE~~~~~ZEBRA~~~~~~~~zebra \\*
:INVERT~~~~~~~~:DOWNCASE~~~~~Zebra~~~~~~~~Zebra \\*
:INVERT~~~~~~~~:DOWNCASE~~~~~zebra~~~~~~~~ZEBRA \\
:INVERT~~~~~~~~:CAPITALIZE~~~ZEBRA~~~~~~~~zebra \\*
:INVERT~~~~~~~~:CAPITALIZE~~~Zebra~~~~~~~~Zebra \\*
:INVERT~~~~~~~~:CAPITALIZE~~~zebra~~~~~~~~ZEBRA \\[\foo]
\end{lisp}

This illustrates all combinations for
\cdf{readtable-case} and \cdf{*print-case*}.
\end{newer}
\end{defun}

\penalty-10000 %required

\begin{defun}[Variable]
*print-gensym*

The \cd{*print-gensym*} variable controls whether the prefix \cd{\#:}
is printed before symbols that have no home package.
The prefix is printed if the variable is not {\false}.
The initial value of \cd{*print-gensym*} is {\true}.
\end{defun}

\begin{table}[t]
\caption{Examples of Print Level and Print Length Abbreviation}
\label{LEVEL-LENGTH-TABLE}
\begin{lisp}
\begin{tabular*}{\textwidth}{@{}l@{\extracolsep{\fill}}@{}ll@{}}
\emph{v}&\emph{n}&Output \\
\hlinesp
0&1&\# \\
1&1&(if ...) \\
1&2&(if \# ...) \\
1&3&(if \# \# ...) \\
1&4&(if \# \# \#) \\
2&1&(if ...) \\
2&2&(if (member x ...) ...) \\
2&3&(if (member x y) (+ \# 3) ...) \\
3&2&(if (member x ...) ...) \\
3&3&(if (member x y) (+ (car x) 3) ...) \\
3&4&(if (member x y) (+ (car x) 3) '(foo . \#(a b c d ...))) \\
3&5&(if (member x y) (+ (car x) 3) '(foo . \#(a b c d "Baz")))
\end{tabular*}
\end{lisp}
\end{table}

\begin{defun}[Variable]
*print-level* \\
*print-length*

The \cd{*print-level*} variable controls how many levels deep a nested
data object will print.
If \cd{*print-level*} is {\false} (the initial value), then no control is exercised.
Otherwise, the value should be an integer, indicating the maximum level to
be printed.  An object to be printed is at level \cd{0};
its components (as of a list or vector) are at level \cd{1}; and so on.
If an object to be recursively printed has components and is at a level
equal to or greater than the value of \cd{*print-level*}, then the object
is printed as simply \cd{\#}.

The \cd{*print-length*} variable controls how many elements at a given level
are printed.  A value of {\false} (the initial value) indicates that there
be no limit to the number of components printed.  Otherwise, the value of
\cd{*print-length*} should be an integer.  Should the number of elements of a
data object exceed the value \cd{*print-length*}, the printer will print three
dots, \cd{...}, in place of those elements beyond the number specified
by \cd{*print-length*}.  (In the case of a dotted list, if the list contains
exactly as many elements as the value of \cd{*print-length*}, and in addition
has the non-null atom terminating it, that terminating atom is printed
rather than the three dots.)

\cd{*print-level*} and \cd{*print-length*} affect the printing not only of lists
but also of vectors, arrays, and any other object printed with
a list-like syntax.  They do not affect the printing of symbols,
strings, and bit-vectors.

The Lisp reader will normally signal an error when reading
an expression that has been abbreviated because of level or length limits.
This signal is given because the \cd{\#} dispatch character normally signals
an error when followed by whitespace or \cd{)}, and because \cd{...}
is defined to be an illegal token, as are all tokens consisting
entirely of periods (other than the single dot used in dot notation).

As an example, table~\ref{LEVEL-LENGTH-TABLE} shows the ways the object
\begin{lisp}
(if (member x y) (+ (car x) 3) '(foo . \#(a b c d "Baz")))
\end{lisp}
would be printed for various values of \cd{*print-level*}
(in the column labeled \emph{v}) and \cd{*print-length*} (in the column labeled \emph{n}).
\end{defun}

\begin{defun}[Variable]
*print-array*

If \cd{*print-array*} is {\false}, then the contents of arrays other than strings
are never printed.  Instead, arrays are printed in a concise form (using
\cd{\#<}) that gives enough information for the user to be able to
identify the array but does not include the entire array contents.
If \cd{*print-array*} is not {\false}, non-string arrays are printed using
\cd{\#(}, \cd{\#*}, or \cd{\#\emph{n}A} syntax.
\begin{new}%CORR
\emph{Notice of correction.}
In the first edition, the preceding paragraph mentioned the nonexistent
variable \cdf{print-array} instead of \cd{*print-array*}.
\end{new}
The initial value of \cd{*print-array*} is implementation-dependent.
\end{defun}

\begin{defmac}
with-standard-io-syntax {declaration}* {form}*
 
Within the dynamic extent of the body, all reader/printer control
    variables, including any implementation-defined ones not specified by
    Common Lisp, are bound to values that produce standard read/print
    behavior.  Table~\ref{WITH-STANDARD-IO-SYNTAX-TABLE} shows
    the values to which standard Common Lisp variables are bound.

\begin{table}[t]
\caption{Standard Bindings for I/O Control Variables}
\label{WITH-STANDARD-IO-SYNTAX-TABLE}
\begin{flushleft}
\cf
\begin{tabular}{@{}ll@{}}
\textrm{Variable}&\textrm{Value} \\
\hlinesp
      {*package*}                      &     \textrm{the \cdf{common-lisp-user} package} \\
      {*print-array*}                  &     t \\
      {*print-base*}                   &     10 \\
      {*print-case*}                   &     :upcase \\
      {*print-circle*}                 &     nil \\
      {*print-escape*}                 &     t \\
      {*print-gensym*}                 &     t \\
      {*print-length*}                 &     nil \\
      {*print-level*}                  &     nil \\
      {*print-lines*}                  &     nil \textrm{*} \\
      {*print-miser-width*}            &     nil \textrm{*} \\
      {*print-pprint-dispatch*}        &     nil \textrm{*} \\
      {*print-pretty*}                 &     nil \\
      {*print-radix*}                  &     nil \\
      {*print-readably*}               &     t \\
      {*print-right-margin*}           &     nil \textrm{*} \\
      {*read-base*}                    &     10 \\
      {*read-default-float-format*}    &     single-float \\
      {*read-eval*}                    &     t \\
      {*read-suppress*}                &     nil \\
      {*readtable*}                    &     \textrm{the standard readtable}
\end{tabular}
\end{flushleft}
* X3J13 voted in June 1989 \issue{PRETTY-PRINT-INTERFACE}
to introduce the printer control variables
\cdf{*print-right-margin*},
\cdf{*print-miser-width*},
\cdf{*print-lines*},
and \cdf{*print-pprint-dispatch*}
(see section~\ref{PPRINT-VARIABLES-SECTION})
but did not specify the values to which \cdf{with-standard-io-syntax}
should bind them.  I recommend that all four should be bound to \cdf{nil}.
\end{table}

    The values returned by \cdf{with-standard-io-syntax} are the values
    of the last body \emph{form}, or \cdf{nil} if there are no body forms.

The intent is that a pair of executions, as shown in the following example,
should provide reasonable reliable communication of data from
one Lisp process to another:
\begin{lisp}
;;; Write DATA to a file. \\*
(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{lisp}

Using \cdf{with-standard-io-syntax} to bind all the variables,
  instead of using \cdf{let} and explicit bindings,
  ensures that nothing is overlooked and avoids problems with
  implementation-defined reader/printer control variables.
  If the user wishes to use a non-standard value for some variable, such as
  \cdf{*package*} or \cd{*read-eval*}, it can be bound by \cdf{let} inside the body of
  \cdf{with-standard-io-syntax}.  For example:
\begin{lisp}
;;; Write DATA to a file.  Forbid use of \#. syntax. \\*
(with-open-file (file pathname :direction :output) \\*
~~(let ((*read-eval* nil)) \\*
~~~~(with-standard-io-syntax \\*
~~~~~~(print data file)))) \\
\\
;;; Read DATA from a file.  Forbid use of \#. syntax. \\*
(with-open-file (file pathname :direction :input) \\*
~~(let ((*read-eval* nil)) \\*
~~~~(with-standard-io-syntax \\*
~~~~~~(setq data (read file)))))
\end{lisp}
Similarly, a user who dislikes the
  arbitrary choice of values for \cd{*print-\discretionary{}{}{}circle*} and \cdf{*print-pretty*}
  can bind these variables to other values inside the body.

The X3J13 vote left it unclear whether \cdf{with-standard-io-syntax}
permits declarations to appear before the body of the macro call.
I believe that was the intent, and this is reflected in the syntax shown above;
but this is only my interpretation.
\end{defmac}

\section{Input Functions}

The input functions are divided into two groups: those that
operate on streams of characters and those that operate on
streams of binary data.

\subsection{Input from Character Streams}
\label{CHARACTER-INPUT-SECTION}

Many character
input functions take optional arguments called \emph{input-stream},
\emph{eof-error-p}, and \emph{eof-value}.  The \emph{input-stream} argument is the
stream from
which to obtain input; if unsupplied or {\false} it defaults to the value of
the special variable \cdf{*standard-input*}.  One may also specify {\true}
as a stream, meaning the value of the special variable
\cdf{*terminal-io*}.

The \emph{eof-error-p} argument
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 \emph{eof-error-p} is true (the default), an error will be signaled
at end of file.  If it is false, then no error is signaled, and instead
the function returns \emph{eof-value}.

An \emph{eof-value} argument
may be any Lisp datum whatsoever.

Functions such as \cdf{read} that read the representation
of an object rather than a single
character will always signal an error, regardless of \emph{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, \cdf{read} will complain.  If a file ends in a symbol or a number
immediately followed by end-of-file, \cdf{read} will read the symbol or
number successfully and when called again will see the end-of-file and
only then act according to \emph{eof-error-p}.
Similarly, the function \cdf{read-line}
will successfully read the last line of a file even if that line
is terminated by end-of-file rather than the newline character.
If a file contains ignorable text at the end, such
as blank lines and comments, \cdf{read} will not consider it to end in the
middle of an object.
Thus an \emph{eof-error-p} argument controls what happens
when the file ends \emph{between} objects.

Many input functions also take an argument called \emph{recursive-p}.
If specified and not {\nil}, this argument specifies that
this call is not a ``top-level'' call to \cdf{read} but an imbedded call,
typically from the function for a macro character.
It is important to distinguish such recursive calls for three reasons.

First, a top-level call establishes the context within which the
\cd{\#\emph{n}=} and \cd{\#\emph{n}\#} syntax is scoped.  Consider, for example,
the expression
\begin{lisp}
(cons '\#3=(p q r) '(x y . \#3\#))
\end{lisp}
If the single-quote macro character were defined in this way:
\begin{lisp}
(set-macro-character \#{\Xbackslash}' \\
~~~~~~~~~~~~~~~~~~~~~\#'(lambda (stream char) \\
~~~~~~~~~~~~~~~~~~~~~~~~~(declare (ignore char)) \\
~~~~~~~~~~~~~~~~~~~~~~~~~(list 'quote (read stream))))
\end{lisp}
then the expression could not be read properly, because there would be no way
to know when \cdf{read} is called recursively by the first
occurrence of \cd{'} that the label \cd{\#3=} would be referred to
later in the containing expression.
There would be no way to know because \cdf{read}
could not determine that it was called by a macro-character function
rather than from ``top level.''  The correct way to define the single quote
macro character uses the \emph{recursive-p} argument:
\begin{lisp}
(set-macro-character \#{\Xbackslash}' \\
~~~~~~~~~~~~~~~~~~~~~\#'(lambda (stream char) \\
~~~~~~~~~~~~~~~~~~~~~~~~~(declare (ignore char)) \\
~~~~~~~~~~~~~~~~~~~~~~~~~(list 'quote (read stream t nil t))))
\end{lisp}

Second, a recursive call does not alter whether the reading process
is to preserve whitespace or not (as determined by whether the
top-level call was to \cdf{read} or \cdf{read-preserving-whitespace}).
Suppose again that the single quote had the first, incorrect, macro-character
definition shown above.  Then a call to \cdf{read-preserving-whitespace}
that read the expression \cd{'foo } would fail to preserve the space
character following the symbol \cdf{foo} because the single-quote
macro-character function calls \cdf{read}, not \cdf{read-preserving-whitespace},
to read the following expression (in this case \cdf{foo}).
The correct definition, which passes the value {\true} for the \emph{recursive-p}
argument to \cdf{read}, allows the top-level call to determine
whether whitespace is preserved.

Third, when end-of-file is encountered and the \emph{eof-error-p} argument
is not {\nil}, the kind of error that is signaled may depend on the value
of \emph{recursive-p}.  If \emph{recursive-p} is not {\nil}, then the end-of-file
is deemed to have occurred within the middle of a printed representation;
if \emph{recursive-p} is {\nil}, then the end-of-file may be deemed to have
occurred between objects rather than within the middle of one.


\begin{defun}[Function]
read &optional input-stream eof-error-p eof-value recursive-p

\cdf{read} reads in the printed representation of a Lisp object
from \emph{input-stream}, builds a corresponding Lisp object, and returns
the object.

Note that when the variable \cd{*read-suppress*} is not {\nil},
then \cdf{read} reads in a printed representation as best it can,
but most of the work of interpreting the representation is avoided
(the intent being that the result is to be discarded anyway).
For example, all extended tokens produce the result {\nil} regardless
of their syntax.
\end{defun}

\begin{defun}[Variable]
*read-default-float-format*

The value of this variable must be a type specifier symbol for
a specific floating-point format; these include
\cdf{short-float}, \cdf{single-float},
\cdf{double-float}, and \cdf{long-float} and may include implementation-specific
types as well.  The default value is \cdf{single-float}.

\cdf{*read-default-float-format*}
indicates the floating-point format to be used
for reading floating-point numbers that have no exponent marker or have
\cdf{e} or \cdf{E} for an exponent marker.  (Other exponent markers
explicitly prescribe the floating-point format to be used.)
The printer also uses this variable to guide the choice of exponent
markers when printing floating-point numbers.
\end{defun}

\begin{defun}[Function]
read-preserving-whitespace &optional in-stream eof-error-p eof-value recursive-p

Certain printed representations given to \cdf{read}, notably those of symbols
and numbers, require a delimiting character after them.  (Lists do not, because
the close parenthesis marks the end of the list.)
Normally \cdf{read} will throw away the delimiting character if it is a
whitespace character;
but \cdf{read} will preserve the character (using \cdf{unread-char}) if it is
syntactically meaningful, because it may be the start of the next expression.

\begin{new}
X3J13 voted in January 1989
\issue{PEEK-CHAR-READ-CHAR-ECHO}
to clarify the interaction of \cdf{unread-char}
with echo streams.  These changes indirectly affect the echoing behavior
of \cdf{read-preserving-whitespace}.
\end{new}

The function \cdf{read-preserving-whitespace} is provided for some specialized
situations where it is desirable to determine precisely what character
terminated the extended token.

As an example, consider this macro-character definition:
\begin{lisp}
(defun slash-reader (stream char) \\
~~(declare (ignore char)) \\
~~(do ((path (list (read-preserving-whitespace stream)) \\
~~~~~~~~~~~~~(cons (progn (read-char stream nil nil t) \\
~~~~~~~~~~~~~~~~~~~~~~~~~~(read-preserving-whitespace \\
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~stream)) \\
~~~~~~~~~~~~~~~~~~~path))) \\
~~~~~~((not (char= (peek-char nil stream nil nil t) \#{\Xbackslash}/)) \\
~~~~~~~(cons 'path (nreverse path))))) \\
(set-macro-character \#{\Xbackslash}/ \#'slash-reader)
\end{lisp}
(This is actually a rather dangerous definition to make because
expressions such as \cd{(/ x 3)} will no longer be read properly.
The ability to reprogram the reader syntax is very powerful and
must be used with caution.  This redefinition of \cdf{/} is shown
here purely for the sake of example.)

Consider now calling \cdf{read} on this expression:
\begin{lisp}
(zyedh /usr/games/zork /usr/games/boggle)
\end{lisp}
The \cdf{/} macro reads objects separated by more \cdf{/} characters;
thus \cd{/usr/games/zork} is intended to be read as \cd{(path usr games zork)}.
The entire example expression should therefore be read as
\begin{lisp}
(zyedh (path usr games zork) (path usr games boggle))
\end{lisp}
However, if \cdf{read} had been used instead of
\cdf{read-preserving-whitespace}, then after the reading of the symbol
\cdf{zork}, the following space would be discarded; the next call
to \cdf{peek-char} would see the following \cdf{/}, and the loop would
continue, producing this interpretation:
\begin{lisp}
(zyedh (path usr games zork usr games boggle))
\end{lisp}
On the other hand, there are times when whitespace \emph{should} be discarded.
If a command interpreter takes single-character commands,
but occasionally reads a Lisp object, then if the whitespace
after a symbol is not discarded it might be interpreted as a command
some time later after the symbol had been read.

Note that \cdf{read-preserving-whitespace} behaves \emph{exactly} like \cdf{read}
when the \emph{recursive-p} argument is not {\nil}.  The distinction is established
only by calls with \emph{recursive-p} equal to {\nil} or omitted.
\end{defun}

\begin{defun}[Function]
read-delimited-list char &optional input-stream recursive-p

This reads objects from \emph{stream} until the next character after an object's
representation (ignoring whitespace characters and comments) is \emph{char}.
(The \emph{char} should not have whitespace syntax in the current
readtable.)
A list of the objects read is returned.

To be more precise, \cdf{read-delimited-list} looks ahead at each step
for the next non-whitespace character and peeks at it
as if with \cdf{peek-char}.  If it is \emph{char}, then the
character is consumed and the list of objects is returned.
If it is a constituent or escape character, then \cdf{read} is used
to read an object, which is added to the end of the list.
If it is a macro character, the associated macro function
is called; if the function returns a value, that value is added
to the list.  The peek-ahead process is then repeated.

\begin{new}
X3J13 voted in January 1989
\issue{PEEK-CHAR-READ-CHAR-ECHO}
to clarify the interaction of \cdf{peek-char}
with echo streams.  These changes indirectly affect the echoing behavior
of the function \cdf{read-delimited-list}.
\end{new}

This function is particularly useful for defining new macro characters.
Usually it is desirable for the terminating character \emph{char} to be a
terminating macro character so that it may be used to delimit tokens;
however, \cdf{read-delimited-list} makes no attempt to alter the syntax
specified for \emph{char} by the current readtable.  The user must make any
necessary changes to the readtable syntax explicitly.  The following
example illustrates this.

Suppose you wanted \cd{\#{\Xlbrace}\emph{a} \emph{b} \emph{c} ... \emph{z}{\Xrbrace}}
to be read as a list of all pairs of the elements \emph{a}, \emph{b}, \emph{c}, \cd{...},
\emph{z}; for example:
\begin{lisp}
\#{\Xlbrace}p q z a{\Xrbrace}~~\textrm{reads as}~~((p q) (p z) (p a) (q z) (q a) (z a))
\end{lisp}
This can be done by specifying a macro-character definition for \cd{\#{\Xlbrace}}
that does two things: read in all the items up to the \cd{{\Xrbrace}},
and construct the pairs.  \cdf{read-delimited-list} performs
the first task.

\begin{new}
Note that \cdf{mapcon} allows the mapped function to examine
the items of the list after the current one, and that
\cdf{mapcon} uses \cdf{nconc}, which is all right because \cdf{mapcar}
will produce fresh lists.
\end{new}

\penalty-10000 %required

\begin{lisp}
(defun |\#{\Xlbrace}-reader| (stream char arg) \\
~~(declare (ignore char arg)) \\
~~(mapcon \#'(lambda (x) \\
~~~~~~~~~~~~~~(mapcar \#'(lambda (y) (list (car x) y)) (cdr x))) \\
~~~~~~~~~~(read-delimited-list \#{\Xbackslash}{\Xrbrace} stream t))) \\
 \\
(set-dispatch-macro-character \#{\Xbackslash}\# \#{\Xbackslash}{\Xlbrace} \#'|\#{\Xlbrace}-reader|) \\
 \\
(set-macro-character \#{\Xbackslash}{\Xrbrace} (get-macro-character \#{\Xbackslash}) {\nil}))
\end{lisp}
(Note that {\true} is specified for the \emph{recursive-p} argument.)

It is necessary here to give a definition to the character \cd{{\Xrbrace}} as
well to prevent it from being a constituent.
If the line
\begin{lisp}
(set-macro-character \#{\Xbackslash}{\Xrbrace} (get-macro-character \#{\Xbackslash}) {\nil}))
\end{lisp}
shown above were not included, then the \cd{{\Xrbrace}} in
\begin{lisp}
\#{\Xlbrace}p q z a{\Xrbrace}
\end{lisp}
would be considered a constituent character, part of the symbol named
\cd{a{\Xrbrace}}.  One could correct for this by putting a space before
the \cd{{\Xrbrace}}, but it is better simply to use the call to
\cdf{set-macro-character}.

Giving \cd{{\Xrbrace}} the same
definition as the standard definition of the character \cd{)} has the
twin benefit of making it terminate tokens for use with \cdf{read-delimited-list}
and also making it illegal for use in any other context (that is, attempting to
read a stray \cd{{\Xrbrace}} will signal an error).

Note that \cdf{read-delimited-list} does not take an \emph{eof-error-p}
(or \emph{eof-value})
argument.  The reason is that it is always an error
to hit end-of-file during the operation of \cdf{read-delimited-list}.
\end{defun}

\begin{defun}[Function]
read-line &optional input-stream eof-error-p eof-value recursive-p

\cdf{read-line} reads in a line of text terminated by a newline.
It returns the line as a character string (\emph{without} the newline character).
This function is usually used to get a line of input from the user.
A second returned value is a flag that is false if the line was
terminated normally, or true if end-of-file terminated the (non-empty) line.
If end-of-file is encountered immediately (that is, appears to terminate
an empty line), then end-of-file processing is controlled in the
usual way by the \emph{eof-error-p}, \emph{eof-value}, and \emph{recursive-p} arguments.

The corresponding output function is \cdf{write-line}.
\end{defun}

\begin{defun}[Function]
read-char &optional input-stream eof-error-p eof-value recursive-p

\cdf{read-char} inputs one character from \emph{input-stream} and returns it
as a character object.

The corresponding output function is \cdf{write-char}.

\begin{new}
X3J13 voted in January 1989
\issue{PEEK-CHAR-READ-CHAR-ECHO}
to clarify the interaction of \cdf{read-char} with echo streams
(as created by \cdf{make-echo-stream}).  A character is echoed from the input stream
to the associated output stream the first time it is seen.
If a character is read again because of an intervening \cdf{unread-char} operation,
the character is not echoed again when read for the second time or any subsequent time.
\end{new}
\end{defun}

\begin{defun}[Function]
unread-char character &optional input-stream

\cdf{unread-char} puts the \emph{character} onto the front of \emph{input-stream}.
The \emph{character} must be the same character that was most recently read
from the \emph{input-stream}.  The \emph{input-stream} ``backs up'' over this
character; when a character is next read from \emph{input-stream}, it will
be the specified character followed by the previous contents of
\emph{input-stream}.  \cdf{unread-char} returns {\false}.

One may apply \cdf{unread-char} only to the character most recently
read from \emph{input-stream}.  Moreover, one may not invoke \cdf{unread-char}
twice consecutively without an intervening \cdf{read-char}
operation.  The result is that one may back up only by one character,
and one may not insert any characters into the input stream that were not already there.

\begin{new}
X3J13 voted in January 1989
\issue{UNREAD-CHAR-AFTER-PEEK-CHAR}
to clarify that one also may not invoke
\cdf{unread-char} after invoking \cdf{peek-char} without an intervening
\cdf{read-char} operation.  This is consistent with the notion that
\cdf{peek-char} behaves much like \cdf{read-char} followed by \cdf{unread-char}.
\end{new}

\beforenoterule
\begin{rationale}
This is not intended to be a general mechanism, but rather
an efficient mechanism for allowing the Lisp reader and other parsers
to perform one-character lookahead in the input stream.
This protocol admits a wide variety of efficient implementations,
such as simply decrementing a buffer pointer.
To have to specify the character in the call to \cdf{unread-char} is
admittedly redundant, since at any given time there is only one character
that may be legally specified.  The redundancy is intentional,
again to give the implementation latitude.
\end{rationale}
\afternoterule

\begin{new}
X3J13 voted in January 1989
\issue{PEEK-CHAR-READ-CHAR-ECHO}
to clarify the interaction of \cdf{unread-char} with echo streams
(as created by \cdf{make-echo-stream}).  When a character is ``unread'' from an echo
stream, no attempt is made to ``unecho'' the character.  However, a character
placed back into an echo stream by \cdf{unread-char} will not be re-echoed
when it is subsequently re-read by \cdf{read-char}.
\end{new}
\end{defun}

\newpage%required

\begin{defun}[Function]
peek-char &optional peek-type input-stream eof-error-p eof-value recursive-p

What \cdf{peek-char} does depends on the \emph{peek-type}, which
defaults to {\false}.  With a \emph{peek-type} of {\false},
\cdf{peek-char} returns the next character to be read from 
\emph{input-stream}, without actually removing it from the input stream.
The next time input is done from \emph{input-stream}, the character will still
be there.  It is as if one had called \cdf{read-char} and then \cdf{unread-char}
in succession.

If \emph{peek-type} is {\true}, then \cdf{peek-char} skips over whitespace
characters (but not comments)
and then performs the peeking operation on the next
character.
This is useful for finding the (possible) beginning
of the next printed representation of a Lisp object.
The last character examined (the one that starts an object)
is not removed from the input stream.

If \emph{peek-type} is a character object, then \cdf{peek-char} skips
over input characters until a character that
is \cdf{char=} to that object is found;
that character is left in the input stream.

\begin{new}
X3J13 voted in January 1989
\issue{PEEK-CHAR-READ-CHAR-ECHO}
to clarify the interaction of \cdf{peek-char} with echo streams
(as created by \cdf{make-echo-stream}).  When a character from an echo
stream is only peeked at, it is not echoed at that time.  The character remains in
the input stream and may be echoed when read by \cdf{read-char} at a later time.
Note, however, that if the \emph{peek-type} is not \cdf{nil}, then characters
skipped over (and therefore consumed) by \cdf{peek-char} are treated as if they had been read
by \cdf{read-char}, and will be echoed if \cdf{read-char} would have echoed them.
\end{new}
\end{defun}

\begin{defun}[Function]
listen &optional input-stream

The predicate \cdf{listen} is true if there is a character
immediately available from \emph{input-stream}, and is false if not.
This is particularly useful when the stream obtains characters
from an interactive device such as a keyboard.  A call to \cdf{read-char}
would simply wait until a character was available, but \cdf{listen} can
sense whether or not input is available and allow the program to
decide whether or not to attempt input.  On a non-interactive stream,
the general rule is that \cdf{listen} is true except when at
end-of-file.
\end{defun}

\begin{defun}[Function]
read-char-no-hang &optional input-stream eof-error-p eof-value recursive-p

This function is exactly like \cdf{read-char}, except
that if it would be necessary to wait in order to get a character (as
from a keyboard), {\false} is immediately returned without waiting.  This
allows one to efficiently check for input availability and get the
input if it is available.
This is different from the \cdf{listen} operation in
two~ways.  First, \cdf{read-char-no-hang} potentially reads a character,
whereas \cdf{listen} never inputs a character.  Second,
\cdf{listen} does not distinguish between end-of-file and no input being
available, whereas \cdf{read-char-no-hang} does make that distinction, returning
\emph{eof-value} at end-of-file (or signaling an error if no \emph{eof-error-p}
is true) but always returning {\false} if no input
is available.
\end{defun}

\begin{defun}[Function]
clear-input &optional input-stream

This clears any buffered input associated with \emph{input-stream}.
It is primarily useful for clearing type-ahead from keyboards when
some kind of asynchronous error has occurred.  If this operation
doesn't make sense for the stream involved, then \cdf{clear-input}
does nothing.  \cdf{clear-input} returns {\false}.
\end{defun}

\begin{defun}[Function]
read-from-string string &optional eof-error-p eof-value &key :start :end :preserve-whitespace

The characters of \emph{string} are given successively to the Lisp reader,
and the Lisp object built by the reader is returned.  Macro characters
and so on will all take effect.

The arguments \cd{:start} and \cd{:end} delimit a substring of \emph{string}
beginning at the character indexed by \cd{:start} and up to but not
including the character indexed by \cd{:end}.  By default \cd{:start} is \cd{0}
(the beginning of the string) and \cd{:end} is \cd{(length \emph{string})}.
This is the same as for other string functions.

The flag \cd{:preserve-whitespace}, if provided and not {\nil}, indicates
that the operation should preserve whitespace as
for \cdf{read-preserving-whitespace}.  It defaults to {\nil}.

As with other reading functions,
the arguments \emph{eof-error-p} and \emph{eof-value} control the action
if the end of the (sub)string is reached
before the operation is completed;
reaching the end of the string is treated as any other end-of-file event.

\cdf{read-from-string} returns two values: the first is the object read,
and the second is the index of the first character in the string not
read.  If the entire string was read, the second result
will be either the length of
the string or one greater than the length of the string.  The parameter
\cd{:preserve-whitespace} may affect this second value.

\begin{lisp}
(read-from-string "(a b c)") \EV\ (a b c) \textrm{and} 7
\end{lisp}
\end{defun}

\begin{defun}[Function]
parse-integer string &key :start :end :radix :junk-allowed

This function examines the substring of \emph{string} delimited by \cd{:start}
and \cd{:end} (which default to the beginning and end of the string).
It skips over whitespace characters and then attempts to
parse an integer.  The \cd{:radix} parameter defaults to \cd{10}
and must be an integer between 2 and 36.

If \cd{:junk-allowed} is not {\false}, then the first value
returned is the value of the number parsed
as an integer or {\false} if no syntactically correct integer
was seen.

If \cd{:junk-allowed} is {\false} (the default), then the entire substring is scanned.
The returned value is the value of the number parsed as an integer.
An error is signaled if the substring does not consist entirely of
the representation of an integer, possibly surrounded on either side by
whitespace characters.

In either case, the second value is the index into the string of the delimiter
that terminated the parse, or it is the index beyond the substring if the
parse terminated at the end of the substring (as will always be the case if
\cd{:junk-allowed} is false).

Note that \cdf{parse-integer} does not recognize the syntactic radix-specifier
prefixes \cd{\#O}, \cd{\#B}, \cd{\#X}, and \cd{\#\emph{n}R}, nor does it recognize
a trailing decimal point.  It permits only an optional sign
(\cdf{+} or \cdf{-}) followed
by a non-empty sequence of digits in the specified radix.
\end{defun}

\begin{defun}[Function]
read-sequence sequence input-stream &key :start :end

This function reads elements from input-stream into sequence. The position of
the first unchanged element of sequence is returned.
\end{defun}

\subsection {Input from Binary Streams}

Common Lisp currently specifies only a very simple facility for binary input:
the reading of a single byte as an integer.

\begin{defun}[Function]
read-byte binary-input-stream &optional eof-error-p eof-value

\cdf{read-byte} reads one byte from the \emph{binary-input-stream} and returns
it in the form of an integer.
\end{defun}

\section {Output Functions}

The output functions are divided into two groups: those that
operate on streams of characters and those that operate on
streams of binary data.  The function \cdf{format} operates
on streams of characters but is described in a section
separate from the other character-output functions
because of its great complexity.

\subsection {Output to Character Streams}

These functions all take an optional argument called \emph{output-stream},
which is where to send the output.  If unsupplied or {\false}, \emph{output-stream}
defaults to the value of the variable
\cdf{*standard-output*}.  If it is {\true}, the value of the variable
\cdf{*terminal-io*} is used.

X3J13 voted in June 1989 \issue{DATA-IO} to add the keyword argument
\cd{:readably} to the function \cdf{write}, and voted in June 1989 \issue{PRETTY-PRINT-INTERFACE}
to add the keyword arguments \cd{:right-margin}, \cd{:miser-width}, \cd{:lines},
and \cd{:pprint-dispatch}.
The revised description
is as follows.

\begin{defun}[Function]
write object &key :stream :escape :radix :base :circle
   :pretty :level :length :case :gensym :array :readably
   :right-margin :miser-width :lines :pprint-dispatch

The printed representation of \emph{object} is written to the output stream
specified by \cd{:stream}, which defaults to the value of \cdf{*standard-output*}.

The other keyword arguments specify values used to control the
generation of the printed representation.  Each defaults to the
value of the corresponding global variable: see \cdf{*print-escape*},
\cd{*print-radix*}, \cd{*print-base*}, \cdf{*print-circle*}, \cdf{*print-pretty*},
\cd{*print-level*}, \cd{*print-length*}, and \cdf{*print-case*}, in addition to
\cd{*print-array*},
\cd{*print-gensym*},
\cd{*print-readably*},
\cd{*print-right-margin*},
\cd{*print-miser-width*},
\cd{*print-lines*},
and \cd{*print-pprint-dispatch*}.
(This is the means by which these variables affect printing operations:
supplying default values for the \cdf{write} function.)
Note that the printing of symbols is also affected by the value
of the variable \cdf{*package*}.
\cdf{write} returns \emph{object}.
\end{defun}

\begin{defun}[Function]
prin1 object &optional output-stream \\
print object &optional output-stream \\
pprint object &optional output-stream \\
princ object &optional output-stream

\cd{prin1} outputs the printed representation of \emph{object} to
\emph{output-stream}.  Escape characters are used as appropriate.
Roughly speaking, the output from \cd{prin1} is suitable for input to
the function \cdf{read}.  \cd{prin1} returns the \emph{object} as its value.
\begin{lisp}
(prin1 \emph{object} \emph{output-stream}) \\
~~~\EQ\ (write \emph{object} :stream \emph{output-stream} :escape t)
\end{lisp}

\cdf{print} is just like \cd{prin1} except that the printed representation
of \emph{object} is preceded by a newline (see \cdf{terpri})
and followed by a space.
\cdf{print} returns \emph{object}.

\cdf{pprint} is just like \cdf{print} except that the trailing
space is omitted and the
\emph{object} is printed with the \cdf{*print-pretty*} flag non-{\nil}
to produce ``pretty'' output.
\cdf{pprint} returns no values (that is, what the expression
\cd{(values)} returns: zero values).

\begin{new}
X3J13 voted in January 1989
\issue{PRETTY-PRINT-INTERFACE}
to adopt a facility for user-controlled pretty printing
(see chapter~\ref{PPRINT}).
\end{new}

\cdf{princ} is just like \cd{prin1} except that the
output has no escape characters.  A symbol is printed as simply the characters
of its print name; a string is printed without surrounding double quotes;
and there may be differences for other data types as well.
The general rule is that output from \cdf{princ} is intended to look
good to people, while output from \cd{prin1} is intended to
be acceptable to the function \cdf{read}.
\begin{newer}
X3J13 voted in June 1987 \issue{PRINC-CHARACTER}
to clarify that \cdf{princ} prints a character in exactly
the same manner as \cdf{write-char}: the character is simply sent to the output \emph{stream}.
This was implied by the specification in section~\ref{PRINTER} in the first edition,
but is worth pointing out explicitly here.
\end{newer}
\cdf{princ} returns the \emph{object} as its value.
\begin{lisp}
(princ \emph{object} \emph{output-stream}) \\
~~~\EQ\ (write \emph{object} :stream \emph{output-stream} :escape {\false})
\end{lisp}
\end{defun}


\begin{defun}[Function]
write-to-string object &key :escape :radix :base :circle :pretty
   :level :length :case :gensym :array :readably
   :right-margin :miser-width :lines :pprint-dispatch \\
prin1-to-string object \\
princ-to-string object

The object is effectively printed as if by \cdf{write},
\cd{prin1}, or \cdf{princ}, respectively,
and the characters that would be output are made into a string,
which is returned.
\end{defun}


\begin{defun}[Function]
write-char character &optional output-stream

\cdf{write-char} outputs the \emph{character} to \emph{output-stream},
and returns \emph{character}.
\end{defun}


\begin{defun}[Function]
write-string string &optional output-stream &key :start :end{\negthinspace\negthinspace} \\
write-line string &optional output-stream &key :start :end

\cdf{write-string} writes the characters of the specified
substring of \emph{string} to
the \emph{output-stream}.  The \cd{:start} and \cd{:end} parameters
delimit a substring of \emph{string} in the usual manner
(see chapter~\ref{KSEQUE}).
\cdf{write-line} does the same thing but then
outputs a newline afterwards.  (See \cdf{read-line}.)
In either case, the \emph{string} is returned (\emph{not} the substring
delimited by \cd{:start} and \cd{:end}).
In some implementations these may be much
more efficient than an explicit loop using \cdf{write-char}.
\end{defun}

\begin{defun}[Function]
write-sequence sequence output-stream &key :start :end


write-sequence writes the elements of the subsequence of \emph{sequence} bounded by \emph{start} and \emph{end} to \emph{output-stream}.
\end{defun}

\begin{defun}[Function]
terpri &optional output-stream \\
fresh-line &optional output-stream

The function \cdf{terpri} outputs a newline to \emph{output-stream}.
It is identical in effect to
\cd{(write-char \#{\Xbackslash}Newline \emph{output-stream})}; however,
\cdf{terpri} always returns {\false}.

\cdf{fresh-line} is similar to \cdf{terpri} but outputs a newline
only if the stream is not already at the start of a line.
(If for some reason this cannot be determined, then a newline
is output anyway.)
This guarantees that the stream will be on a ``fresh line'' while
consuming as little vertical distance as possible.
\cdf{fresh-line} is a predicate that is true if it output a
newline, and otherwise false.
\end{defun}

\begin{defun}[Function]
finish-output &optional output-stream \\
force-output &optional output-stream \\
clear-output &optional output-stream

Some streams may be implemented in an asynchronous or buffered manner.
The function \cdf{finish-output} attempts to ensure that all output
sent to \emph{output-stream} has reached its destination, and only then
returns {\false}.  \cdf{force-output} initiates the emptying of any
internal buffers but returns {\nil} without waiting for completion
or acknowledgment.

The function \cdf{clear-output}, on the other hand, attempts to abort any
outstanding output operation in progress in order
to allow as little output as possible
to continue to the destination.  This is useful, for example, to abort
a lengthy output to the terminal when an asynchronous error occurs.
\cdf{clear-output} returns {\false}.

The precise actions of all three of these operations are
implementation-dependent.
\end{defun}

\begin{defmac}
print-unreadable-object (object stream
                         <\!:type! type | \!:identity! id>)
                        {declaration}* {form}*

    Function will output a printed representation of \emph{object} on \emph{stream},
    beginning with
    \cd{\#<} and ending with \cdf{>}.  Everything output to the \emph{stream} during
    execution of the body
    forms is enclosed in the angle brackets.  If \emph{type} is true, the body
    output is preceded by a brief description of the object's type and a
    space character.  If \emph{id} is true, the body output is followed by
    a space character and a representation of the object's identity,
    typically a storage address.

    If \cd{*print-readably*} is true, \cdf{print-unreadable-object} signals an error
    of type \cdf{print-not-readable} without printing anything.

    The \emph{object}, \emph{stream}, \emph{type}, and \emph{id} arguments are all evaluated
    normally.  The \emph{type} and \emph{id} default to false.  It is valid to provide
    no body forms.  If \emph{type} and \emph{id} are both true and there are no
    body forms, only one space character separates the printed type and the printed identity.

    The value returned by \cdf{print-unreadable-object} is \cdf{nil}.
\begin{lisp}
(defmethod print-object ((obj airplane) stream) \\*
~~(print-unreadable-object (obj stream :type t :identity t) \\*
~~~~(princ (tail-number obj) stream))) \\
(print my-airplane)~~\textrm{prints} \\*
\#<Airplane NW0773 777500123135>~~~~~;\textrm{In implementation A} \\*
~~~~~~~~~~~~~~~~~~~~~\textrm{or perhaps} \\*
\#<FAA:AIRPLANE NW0773 17>~~~~~~~~~~~;\textrm{In implementation B}
\end{lisp}
The big advantage of
\cdf{print-unreadable-object} is that it allows a user to write \cdf{print-object} methods that
  adhere to implementation-specific style without requiring the user to write
  implementation-dependent code.

The X3J13 vote left it unclear whether \cdf{print-unreadable-object}
permits declarations to appear before the body of the macro call.
I believe that was the intent, and this is reflected in the syntax shown above;
but this is only my interpretation.
\end{defmac}

\subsection {Output to Binary Streams}

Common Lisp currently specifies only a very simple facility for binary output:
the writing of a single byte as an integer.

\begin{defun}[Function]
write-byte integer binary-output-stream

\cdf{write-byte} writes one byte, the value of \emph{integer}.
It is an error if \emph{integer} is not of the type
specified as the \cd{:element-type} argument to \cdf{open} when the stream
was created.
The value \emph{integer} is returned.
\end{defun}


\subsection{Formatted Output to Character Streams}
\label{FORMAT-SECTION}
%\indexterm{formatted output}

The function \cdf{format} is very useful for producing
nicely formatted text, producing good-looking messages, and so on.
\cdf{format} can generate a string or output to a stream.

Formatted output is performed not only by the \cdf{format} function
itself but by certain other functions that accept a control string
``the way \cdf{format} does.''  For example, error-signaling functions
such as \cdf{cerror} accept \cdf{format} control strings.

\begin{defun}[Function]
format destination control-string &rest arguments

\cdf{format} is used to produce formatted output.
\cdf{format} outputs the characters of \emph{control-string},
except that a tilde (\cd{{\Xtilde}}) introduces a directive.
The character after
the tilde, possibly preceded by prefix parameters and modifiers, specifies
what kind of formatting is desired.  Most directives use one or more
elements of \emph{arguments} to create their output; the typical directive
puts the next element of \emph{arguments} into the output, formatted in
some special way.  It is an error if no argument remains for a directive
requiring an argument, but it is not an error if one or more arguments
remain unprocessed by a directive.

The output is sent to \emph{destination}.  If \emph{destination} is
{\false}, a string is created that contains the output; this string is
returned as the value of the call to \cdf{format}.

When the first argument
to \cdf{format} is \cdf{nil}, \cdf{format} creates a stream
of type \cdf{string-stream} in much the same manner as \cdf{with-output-to-string}.
(This stream may be visible to the user if, for example, the \cd{{\Xtilde}S}
directive is used to print a \cdf{defstruct} structure that has a user-supplied
print function.)

In all other cases
\cdf{format} returns {\false}, performing output to \emph{destination}
as a side effect.
If \emph{destination} is a stream, the output is sent to it.  If
\emph{destination} is {\true}, the output is sent to the stream
that is the value of the variable \cdf{*standard-output*}.
If \emph{destination} is a string with a fill pointer, then
in effect the output characters are added to the end of the string
(as if by use of \cdf{vector-push-extend}).

The \cdf{format} function includes some extremely complicated and specialized
features.  It is not necessary to understand all or even most of its
features to use \cdf{format} effectively.  The beginner should
skip over anything in the following documentation that is not
immediately useful or clear.  The more sophisticated features
(such as conditionals and iteration) are
there for the convenience of programs with especially complicated formatting
requirements.

A \cdf{format} directive consists of a tilde (\cd{{\Xtilde}}),
optional prefix parameters
separated by commas, optional colon (\cd{:}) and at-sign (\cd{{\Xatsign}}) modifiers,
and a single character indicating what kind of directive this is.
The alphabetic case of the directive character is ignored.
The prefix parameters are generally integers,
notated as optionally signed decimal numbers.

If both colon and at-sign modifiers are present, they may appear
in either order; thus \cd{{\Xtilde}:{\Xatsign}R} and \cd{{\Xtilde}{\Xatsign}:R}
mean the same thing.  However, it is traditional to put the colon first, and all the
examples in this book put colons before at-signs.

Examples of control strings:
\begin{lisp}
"{\Xtilde}S"~~~~~~~~~~~;\textrm{An \cd{{\Xtilde}S} directive with no parameters or modifiers} \\
"{\Xtilde}3,-4:{\Xatsign}s"~~~~~;\textrm{An \cd{{\Xtilde}S} directive with two parameters, 3 and $-4$,} \\
~~~~~~~~~~~~~~~; \textrm{and both the colon and at-sign flags} \\
"{\Xtilde},+4S"~~~~~~~~;\textrm{First prefix parameter is omitted and takes} \\
~~~~~~~~~~~~~~~; \textrm{on its default value; the second parameter is 4}
\end{lisp}
Sometimes a prefix parameter is used to specify a character, for
instance the padding character in a right- or left-justifying operation.
In this case a single quote (\cd{'}) followed by the desired
character may be used as a prefix parameter, to mean the character
object that is the character following the single quote.  For
example, you can use \cd{{\Xtilde}5,'0d}
to print an integer in decimal radix in five columns with leading zeros,
or \cd{{\Xtilde}5,'*d} to get leading asterisks.

In place of a prefix parameter to a directive, you can put the letter
\cdf{V} (or \cdf{v}), which takes an argument from \emph{arguments} for use as a parameter to
the directive.  Normally this should be an integer or character object,
as appropriate.  This feature allows variable-width fields and the like.
If the argument used by a \cdf{V} parameter is {\nil},
the effect is as if the parameter had been omitted.
You may also use the character \cd{\#} in place of a parameter; it
represents the number of arguments remaining to be processed.

It is an error to give a format directive more parameters than
it is described here as accepting.  It is also an error to give
colon or at-sign modifiers to a directive in a combination not
specifically described here as being meaningful.
\end{defun}

\penalty-10000 %manual

\begin{new}
X3J13 voted in January 1989
\issue{FORMAT-PRETTY-PRINT}
to clarify the interaction between \cdf{format}
and the various printer control variables (those named \cd{*print-\emph{xxx}*}).
This is important because many \cdf{format} operations are defined, directly
or indirectly, in terms of \cd{prin1} or \cdf{princ}, which are affected
by the printer control variables.  The general rule is that \cdf{format}
does not bind any of the standard printer control variables except as
specified in the individual descriptions of directives.  An implementation
may not bind any standard printer control variable not specified in the
description of a \cdf{format} directive, nor may an implementation fail
to bind any standard printer control variables that is specified to be bound
by such a description.  (See these
descriptions for specific changes voted by X3J13.)

One consequence of this change is that the user is guaranteed to be able
to use the \cdf{format} \cd{{\Xtilde}A} and \cd{{\Xtilde}S} directives
to do pretty printing, under control of the \cdf{*print-pretty*} variable.
Implementations have differed on this point in their interpretations of
the first edition.  The new \cd{{\Xtilde}W} directive may be more appropriate
than either \cd{{\Xtilde}A} and \cd{{\Xtilde}S} for some purposes,
whether for pretty printing or ordinary printing.
See section~\ref{PPRINT-FORMAT-DIRECTIVES-SECTION} for a discussion of
\cd{{\Xtilde}W} and other new \cdf{format} directives related to pretty printing.
\end{new}


Here are some relatively simple examples to give you the general
flavor of how \cdf{format} is used.
\begin{lisp}
(format {\false} "foo") \EV\ "foo" \\
 \\
(setq x 5) \\
 \\
(format {\false} "The answer is {\Xtilde}D." x) \EV\ "The answer is 5." \\
 \\
(format {\false} "The answer is {\Xtilde}3D." x) \EV\ "The answer is~~~5." \\
 \\
(format {\false} "The answer is {\Xtilde}3,'0D." x) \EV\ "The answer is 005." \\
 \\
(format {\false} "The answer is {\Xtilde}:D." (expt 47 x)) \\
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\EV\ "The answer is 229,345,007."
\end{lisp}

\begin{lisp}
(setq y "elephant") \\
 \\
(format {\false} "Look at the {\Xtilde}A!" y) \EV\ "Look at the elephant!" \\
 \\
(format {\false} "Type {\Xtilde}:C to {\Xtilde}A." \\
~~~~~~~~(set-char-bit \#{\Xbackslash}D :control t) \\
~~~~~~~~"delete all your files") \\
~~~\EV\ "Type Control-D to delete all your files."
\end{lisp}

\newpage%manual

\begin{lisp}
(setq n 3)
\end{lisp}
\begin{lisp}
(format {\false} "{\Xtilde}D item{\Xtilde}:P found." n) \EV\ "3 items found."
\end{lisp}
\begin{lisp}
(format {\false} "{\Xtilde}R dog{\Xtilde}:{\Xlbracket}s are{\Xtilde}; is{\Xtilde}{\Xrbracket} here." n (= n 1)) \\
~~~~~~\EV\ "three dogs are here."
\end{lisp}
\begin{lisp}
(format {\false} "{\Xtilde}R dog{\Xtilde}:*{\Xtilde}{\Xlbracket}s are{\Xtilde}; is{\Xtilde}:;s are{\Xtilde}{\Xrbracket} here." n) \\
~~~~~~\EV\ "three dogs are here."
\end{lisp}
\begin{lisp}
(format {\false} "Here {\Xtilde}{\Xlbracket}are{\Xtilde};is{\Xtilde}:;are{\Xtilde}{\Xrbracket} {\Xtilde}:*{\Xtilde}R pupp{\Xtilde}:{\Xatsign}P." n) \\
~~~~~~\EV\ "Here are three puppies."
\end{lisp}

In the descriptions of the directives that follow,
the term \emph{arg} in general
refers to the next item of the set of \emph{arguments} to be processed.
The word or phrase at the beginning of each description is a mnemonic
(not necessarily an accurate one) for the directive.
\begin{flushdesc}
\item[\cd{{\Xtilde}A}]
\emph{Ascii}.  An \emph{arg}, any Lisp object, is printed without escape characters
(as by \cdf{princ}).  In particular, if \emph{arg} is a string, its characters
will be output verbatim.
If \emph{arg} is {\nil}, it will
be printed as {\false}; the colon modifier
(\cd{{\Xtilde}:A}) will cause an \emph{arg} of {\nil} to be printed as {\emptylist},
but if \emph{arg} is a composite structure, such as a list or vector,
any contained occurrences of {\nil} will still be printed as {\false}.

\cd{{\Xtilde}\emph{mincol}A} inserts spaces on the right, if necessary, to make the
width at least \emph{mincol} columns.  The \cd{{\Xatsign}} modifier causes the spaces
to be inserted on the left rather than the right.

\cd{{\Xtilde}\emph{mincol},\emph{colinc},\emph{minpad},\emph{padchar}A} is the full form of \cd{{\Xtilde}A},
which allows elaborate control of the padding.
The string is padded on the right (or on the left if the
\cd{{\Xatsign}} modifier is used) with at least \emph{minpad} copies
of \emph{padchar}; padding characters are then inserted \emph{colinc} characters
at a time until the total width is at least \emph{mincol}.
The defaults are \cd{0} for \emph{mincol} and \emph{minpad}, \cd{1} for \emph{colinc},
and the space character for \emph{padchar}.

\cdf{format} binds \cdf{*print-escape*}
to \cdf{nil} during the processing of the \cd{{\Xtilde}A} directive.

\item[\cd{{\Xtilde}S}]
\emph{S-expression}.
This is just like \cd{{\Xtilde}A}, but \emph{arg} is printed \emph{with} escape
characters (as by \cd{prin1} rather than \cdf{princ}).  The output is
therefore suitable for input to \cdf{read}.  \cd{{\Xtilde}S} accepts
all the arguments and modifiers that \cd{{\Xtilde}A} does.

\cdf{format} binds \cdf{*print-escape*}
to \cdf{t} during the processing of the \cd{{\Xtilde}S} directive.

\newpage%required

\item[\cd{{\Xtilde}D}]
\emph{Decimal}.
An \emph{arg}, which should be an integer, is printed in decimal radix.
\cd{{\Xtilde}D} will never put a decimal point after the number.

\cd{{\Xtilde}\emph{mincol}D} uses a column width of \emph{mincol}; spaces are inserted on
the left if the number requires fewer than \emph{mincol} columns for its digits
and sign.  If the number doesn't fit in \emph{mincol} columns, additional columns
are used as needed.

\cd{{\Xtilde}\emph{mincol},\emph{padchar}D} uses \emph{padchar} as the pad character
instead of space.

If \emph{arg} is not an integer, it is printed
in \cd{{\Xtilde}A} format and decimal base.

\cdf{format} binds \cdf{*print-escape*}
to \cdf{nil}, \cd{*print-radix*} to \cdf{nil}, and \cd{*print-base*} to \cd{10}
during processing of \cd{{\Xtilde}D}.

The \cd{{\Xatsign}} modifier causes the number's sign to be printed always; the default
is to print it only if the number is negative.
The \cd{:} modifier causes commas to be printed between groups of three digits;
the third prefix parameter may be used to change the character used as the comma.
Thus the most general form of \cd{{\Xtilde}D} is
\cd{{\Xtilde}\emph{mincol},\emph{padchar},\emph{commachar}D}.

\begin{new}
X3J13 voted in March 1988
\issue{FORMAT-COMMA-INTERVAL}
to add a fourth parameter, the \emph{commainterval}.
This must be an integer; if it is not provided,
it defaults to 3.  This parameter controls the number of digits in each
group separated by the \emph{commachar}.

By extension, each of the \cd{{\Xtilde}B}, \cd{{\Xtilde}O}, and \cd{{\Xtilde}X} directives
accepts a \emph{commainterval} as a fourth parameter,
and the \cd{{\Xtilde}R} directive accepts a \emph{commainterval} as its fifth parameter.
Examples:
\begin{lisp}
(format nil "{\Xtilde},,' ,4B" \#xFACE) \EV\ "1111 1010 1100 1110" \\
(format nil "{\Xtilde},,' ,4B" \#x1CE) \EV\ "1 1100 1110" \\
(format nil "{\Xtilde}19,,' ,4B" \#xFACE) \EV\ "1111 1010 1100 1110" \\
(format nil "{\Xtilde}19,,' ,4B" \#x1CE) \EV\ "0000 0001 1100 1110"
\end{lisp}
This is one of those little improvements that probably don't matter much
but aren't hard to implement either.  It was pretty silly having the number 3 wired
into the definition of comma separation when it is just as easy to make it
a parameter.
\end{new}

\item[\cd{{\Xtilde}B}]
\emph{Binary}.
This is just like \cd{{\Xtilde}D} but prints in binary radix (radix 2)
instead of decimal.  The full form is therefore
\cd{{\Xtilde}\emph{mincol},\emph{padchar},\emph{commachar}B}.

\cdf{format} binds \cdf{*print-escape*}
to \cdf{nil}, \cd{*print-radix*} to \cdf{nil}, and \cd{*print-base*} to \cd{2}
during processing of \cd{{\Xtilde}B}.

\item[\cd{{\Xtilde}O}]
\emph{Octal}.
This is just like \cd{{\Xtilde}D} but prints in octal radix (radix 8)
instead of decimal.  The full form is therefore
\cd{{\Xtilde}\emph{mincol},\emph{padchar},\emph{commachar}O}.

\cdf{format} binds \cdf{*print-escape*}
to \cdf{nil}, \cd{*print-radix*} to \cdf{nil}, and \cd{*print-base*} to \cd{8}
during processing of \cd{{\Xtilde}O}.

\item[\cd{{\Xtilde}X}]
\emph{Hexadecimal}.
This is just like \cd{{\Xtilde}D} but prints in hexadecimal radix
(radix 16) instead of decimal.  The full form is therefore
\cd{{\Xtilde}\emph{mincol},\emph{padchar},\emph{commachar}X}.

\cdf{format} binds \cdf{*print-escape*}
to \cdf{nil}, \cd{*print-radix*} to \cdf{nil}, and \cd{*print-base*} to \cd{16}
during processing of \cd{{\Xtilde}X}.

\item[\cd{{\Xtilde}R}]
\emph{Radix}.
\cd{{\Xtilde}\emph{n}R} prints \emph{arg} in radix \emph{n}.
The modifier flags and any remaining parameters are used as for
the \cd{{\Xtilde}D} directive.
Indeed, \cd{{\Xtilde}D} is the same as \cd{{\Xtilde}10R}.  The full form here is therefore
\cd{{\Xtilde}\emph{radix},\emph{mincol},\emph{padchar},\emph{commachar}R}.

\cdf{format} binds \cdf{*print-escape*}
to \cdf{nil}, \cd{*print-radix*} to \cdf{nil}, and \cd{*print-base*} to the value
of the first parameter
during the processing of the \cd{{\Xtilde}R} directive with a parameter.

If no parameters are given to \cd{{\Xtilde}R}, then an entirely different
interpretation is given.
\begin{new}%CORR
\emph{Notice of correction.}
In the first edition, this sentence referred to ``arguments'' given to \cd{{\Xtilde}R}.
The correct term is ``parameters.''
\end{new}
The argument should be an integer;
suppose it is \cd{4}. Then
\cd{{\Xtilde}R} prints \emph{arg} as a cardinal English number: \cdf{four};
\cd{{\Xtilde}:R} prints \emph{arg} as an ordinal English number: \cdf{fourth};
\cd{{\Xtilde}{\Xatsign}R} prints \emph{arg} as a Roman numeral: \cdf{IV}; and
\cd{{\Xtilde}:{\Xatsign}R} prints \emph{arg} as an old Roman numeral: \cdf{IIII}.

\cdf{format} binds \cd{*print-base*} to \cd{10}
during the processing of the \cd{{\Xtilde}R} directive with no parameter.

\begin{new}
The first edition did not specify how \cd{{\Xtilde}R} and its variants should
handle arguments that are very large or not positive.  Actual practice varies,
and X3J13 has not yet addressed the topic.
Here is a sampling of current practice.

For \cd{{\Xtilde}{\Xatsign}R} and \cd{{\Xtilde}:{\Xatsign}R}, nearly all implementations
produce Roman numerals only for integers in the range 1 to 3999, inclusive.
Some implementations will produce old-style Roman numerals for integers in
the range 1 to 4999, inclusive.  All other integers are printed in decimal
notation, as if \cd{{\Xtilde}D} had been used.

For zero, most implementations print \cdf{zero} for \cd{{\Xtilde}R}
and \cdf{zeroth} for \cd{{\Xtilde}:R}.

For \cd{{\Xtilde}R} with a negative argument, most implementations simply print
the word \cdf{minus} followed by its absolute value as a cardinal in English.

For \cd{{\Xtilde}:R} with a negative argument, some implementations also print
the word \cdf{minus} followed by its absolute value as an ordinal in English;
other implementations print the absolute value followed by the word \cdf{previous}.
Thus the argument \cd{-4} might produce \cd{minus~fourth} or \cd{fourth~previous}.
Each has its charm, but one is not always a suitable substitute for the other;
users should be careful.

There is standard English nomenclature for fairly large integers (up to $10^60$,
at least), based on appending the suffix -illion to Latin names of integers.
Thus we have the names \emph{trillion}, \emph{quadrillion}, \emph{sextillion},
\emph{septillion}, and so on.  For extremely large integers, one may express powers
of ten in English.
One implementation gives
\cd{1606938044258990275541962092341162602522202993782792835301376}
(which is $2^{200}$, the result of \cd{(ash 1 200)})
in this manner:
\begin{flushleft}
\small \cf
one times ten to the sixtieth power six hundred six times ten to the
fifty-seventh power nine hundred thirty-eight septdecillion forty-four
sexdecillion two hundred fifty-eight quindecillion nine hundred ninety
quattuordecillion two hundred seventy-five tredecillion five hundred forty-one
duodecillion nine hundred sixty-two undecillion ninety-two decillion three
hundred forty-one nonillion one hundred sixty-two octillion six hundred two
septillion five hundred twenty-two sextillion two hundred two quintillion nine
hundred ninety-three quadrillion seven hundred eighty-two trillion seven hundred
ninety-two billion eight hundred thirty-five million three hundred one thousand
three hundred seventy-six
\end{flushleft}
Another implementation prints it this way (note the use of \cdf{plus}):
\begin{flushleft}
\small \cf
one times ten to the sixtieth power plus six hundred six times ten to the fifty-seventh power plus
... plus two hundred seventy-five times ten to the
forty-second power plus five hundred forty-one duodecillion nine hundred sixty-two undecillion
...  three hundred seventy-six
\end{flushleft}
(I have elided some of the text here to save space.)

Unfortunately, the meaning of this nomenclature differs between American English (in which {\it
k}-illion means $10^{3(\hbox{\scriptsize\it k}+1)}$, so one trillion is $10^{12}$) and British English (in which {\it
k}-illion means $10^{6\hbox{\scriptsize\it k}}$, so one trillion is $10^{18}$).
To avoid both confusion and prolixity, 
I recommend using decimal notation for all numbers above 999,999,999;
this is similar to the escape hatch used for Roman numerals.
\end{new}

\item[\cd{{\Xtilde}P}]
\emph{Plural}.
If \emph{arg} is not \cdf{eql} to the integer \cd{1}, a lowercase \cdf{s} is
printed; if \emph{arg} is \cdf{eql} to \cd{1}, nothing is printed.  (Notice
that if \emph{arg} is a floating-point \cd{1.0}, the \cdf{s} \emph{is}
printed.)
\cd{{\Xtilde}:P} does the same thing, after doing a \cd{{\Xtilde}:*} to back up one argument;
that is, it prints a lowercase \cdf{s} if the \emph{last} argument was not
\cd{1}.  This is useful after printing a number using \cd{{\Xtilde}D}.
\cd{{\Xtilde}{\Xatsign}P} prints \cdf{y} if the argument is \cd{1}, or \cdf{ies} if it is
not.  \cd{{\Xtilde}:{\Xatsign}P} does the same thing, but backs up first.
\begin{lisp}
(format {\false} "{\Xtilde}D tr{\Xtilde}:{\Xatsign}P/{\Xtilde}D win{\Xtilde}:P" 7 1) \EV\ "7 tries/1 win" \\
(format {\false} "{\Xtilde}D tr{\Xtilde}:{\Xatsign}P/{\Xtilde}D win{\Xtilde}:P" 1 0) \EV\ "1 try/0 wins" \\
(format {\false} "{\Xtilde}D tr{\Xtilde}:{\Xatsign}P/{\Xtilde}D win{\Xtilde}:P" 1 3) \EV\ "1 try/3 wins"
\end{lisp}

\item[\cd{{\Xtilde}C}]
\emph{Character}.  The next \emph{arg} should be a character; it is printed
according to the modifier flags.

\begin{obsolete}
\cd{{\Xtilde}C} prints the character in an implementation-dependent
abbreviated format.  This format should be culturally compatible with the
host environment.
\end{obsolete}

\begin{newer}
X3J13 voted in June 1987 \issue{FORMAT-OP-C} to specify that
\cd{{\Xtilde}C} performs exactly the same action as \cdf{write-char}
if the character to be printed has zero for its bits attributes.
X3J13 voted in March 1989 \issue{CHARACTER-PROPOSAL} to eliminate
the bits and font attributes, replacing them with the notion of
implementation-defined attributes.  The net effect is that characters
whose implementation-defined attributes all have the ``standard''
values should be printed by \cd{{\Xtilde}C} in the same way
that \cdf{write-char} would print them.
\end{newer}

\cd{{\Xtilde}:C} spells out the names of the control bits
and represents non-printing characters
by their names: \cdf{Control-Meta-F}, \cdf{Control-Return}, \cdf{Space}.
This is a ``pretty'' format for printing characters.

\cd{{\Xtilde}:{\Xatsign}C} prints what \cd{{\Xtilde}:C} would, and then
if the character requires unusual shift keys on the keyboard to type it,
this fact is mentioned: \cd{Control-$\partial$ (Top-F)}.  This is the
format for telling the user about a key he or she is expected to type,
in prompts, for instance.  The precise output may depend not only
on the implementation but on the particular I/O devices in use.

\cd{{\Xtilde}{\Xatsign}C} prints the character so that the Lisp reader can read it,
using \cd{\#{\Xbackslash}} syntax.

\begin{new}
X3J13 voted in January 1989
\issue{FORMAT-PRETTY-PRINT}
to specify that \cdf{format} binds \cdf{*print-escape*} to \cdf{t}
during the processing of the \cd{{\Xtilde}{\Xatsign}C} directive.
Other variants of the \cd{{\Xtilde}C} directive do not bind any printer control variables.
\end{new}

\beforenoterule
\begin{rationale}
In some implementations the \cd{{\Xtilde}S} directive would
do what \cd{{\Xtilde}C} does,
but \cd{{\Xtilde}C} is compatible
with Lisp dialects such as MacLisp that do not have a character data type.
\end{rationale}
\afternoterule

\item[\cd{{\Xtilde}F}]
\emph{Fixed-format floating-point}.
The next \emph{arg} is printed as a floating-point
number.

The full form is \cd{{\Xtilde}\emph{w},\emph{d},\emph{k},\emph{overflowchar},\emph{padchar\/}F}.
The parameter \emph{w}
is the width of the field to be printed; \emph{d} is the number
of digits to print after the decimal point; \emph{k} is a scale factor
that defaults to zero.

Exactly \emph{w} characters will
be output.  First, leading copies of the character \emph{padchar}
(which defaults to a space) are printed, if necessary, to pad the
field on the left.
If the \emph{arg} is negative, then a minus sign is printed;
if the \emph{arg} is not negative, then a plus sign is printed
if and only if the \cd{{\Xatsign}} modifier was specified.  Then a sequence
of digits, containing a single embedded decimal point, is printed;
this represents the magnitude of the value of \emph{arg} times $10^{\hbox{\scriptsize\it k}}$,
rounded to \emph{d} fractional digits.
(When rounding up and rounding down would produce printed values
equidistant from the scaled value of \emph{arg}, then the implementation
is free to use either one.  For example, printing the argument
\cd{6.375} using the format \cd{{\Xtilde}4,2F} may correctly produce
either \cd{6.37} or \cd{6.38}.)
Leading zeros are not permitted, except that a single
zero digit is output before the decimal point if the printed value
is less than 1, and this single zero digit is not output
after all if $\emph{w}=\emph{d}+1$.

If it is impossible to print the value in the required format in a field
of width \emph{w}, then one of two actions is taken.  If the
parameter \emph{overflowchar} is specified, then \emph{w} copies of that
parameter are printed instead of the scaled value of \emph{arg}.
If the \emph{overflowchar} parameter is omitted, then the scaled value
is printed using more than \emph{w} characters, as many more as may be
needed.

If the \emph{w} parameter is omitted, then the field is of variable width.
In effect, a value is chosen
for \emph{w} in such a way that no leading pad characters need to be printed
and exactly \emph{d} characters will follow the decimal point.
For example, the directive \cd{{\Xtilde},2F} will print exactly
two digits after the decimal point and as many as necessary before the
decimal point.

If the parameter \emph{d} is omitted, then there is no constraint
on the number of digits to appear after the decimal point.
A value is chosen for \emph{d} in such a way that as many digits
as possible may be printed subject to the width constraint
imposed by the parameter \emph{w} and the constraint that no trailing
zero digits may appear in the fraction, except that if the
fraction to be printed is zero, then a single zero digit should
appear after the decimal point if permitted by the width constraint.

If both \emph{w} and \emph{d} are omitted, then the effect is to print
the value using ordinary free-format output; \cd{prin1} uses this format
for any number whose magnitude is either zero or between
$10^{-3}$ (inclusive) and $10^7$ (exclusive).

If \emph{w} is omitted, then if the magnitude of \emph{arg} is so large (or, if
\emph{d} is also omitted, so small) that more than 100 digits would have to
be printed, then an implementation is free, at its discretion, to print
the number using exponential notation instead, as if by the directive
\cd{{\Xtilde}E} (with all parameters to \cd{{\Xtilde}E} defaulted, not
taking their values from the \cd{{\Xtilde}F} directive).

If \emph{arg} is a rational number, then it is coerced to be a \cdf{single-float}
and then printed.  (Alternatively, an implementation is permitted to
process a rational number by any other method that has essentially the
same behavior but avoids such hazards as loss of precision or overflow
because of the coercion.  However, note that if \emph{w} and \emph{d} are
unspecified and the number has no exact decimal representation,
for example \cd{1/3}, some precision cutoff must be chosen
by the implementation: only a finite number of digits may be printed.)

If \emph{arg} is a complex number or some non-numeric
object, then it is printed using the format directive \cd{{\Xtilde}\emph{w\/}D},
thereby printing it in decimal radix and a minimum field width of \emph{w}.
(If it is desired to print each of the real part and imaginary part
of a complex number using a \cd{{\Xtilde}F} directive, then this must
be done explicitly with two \cd{{\Xtilde}F} directives and code to
extract the two parts of the complex number.)

\begin{new}
X3J13 voted in January 1989
\issue{FORMAT-PRETTY-PRINT}
to specify that \cdf{format} binds \cdf{*print-escape*} to \cdf{nil}
during the processing of the \cd{{\Xtilde}F} directive.
\end{new}

\begin{lisp}
(defun foo (x) \\
~~(format nil "{\Xtilde}6,2F|{\Xtilde}6,2,1,'*F|{\Xtilde}6,2,,'?F|{\Xtilde}6F|{\Xtilde},2F|{\Xtilde}F" \\
~~~~~~~~~~x x x x x x)) \\
(foo 3.14159)~~\EV\ "~~3.14|~31.42|~~3.14|3.1416|3.14|3.14159" \\
(foo -3.14159)~\EV\ "~-3.14|-31.42|~-3.14|-3.142|-3.14|-3.14159" \\
(foo 100.0)~~~~\EV\ "100.00|******|100.00|~100.0|100.00|100.0" \\
(foo 1234.0)~~~\EV\ "1234.00|******|??????|1234.0|1234.00|1234.0" \\
(foo 0.006)~~~~\EV\ "~~0.01|~~0.06|~~0.01|~0.006|0.01|0.006"
\end{lisp}

\item[\cd{{\Xtilde}E}]
\emph{Exponential floating-point}.
The next \emph{arg} is printed in exponential notation.

The full form is \cd{{\Xtilde}\emph{w},\emph{d},\emph{e},\emph{k},\emph{overflowchar},\emph{padchar},\emph{exponentchar}E}.
The parameter \emph{w}
is the width of the field to be printed; \emph{d} is the number
of digits to print after the decimal point; \emph{e} is the number
of digits to use when printing the exponent;
\emph{k} is a scale factor that defaults to 1 (not zero).

Exactly \emph{w} characters will
be output.  First, leading copies of the character \emph{padchar}
(which defaults to a space) are printed, if necessary, to pad the
field on the left.
If the \emph{arg} is negative, then a minus sign is printed;
if the \emph{arg} is not negative, then a plus sign is printed
if and only if the \cd{{\Xatsign}} modifier was specified.  Then a sequence
of digits, containing a single embedded decimal point, is printed.
The form of this sequence of digits depends on the scale factor \emph{k}.
If \emph{k} is zero, then \emph{d} digits are printed after the decimal
point, and a single zero digit appears before the decimal point if
the total field width will permit it.  If \emph{k} is positive,
then it must be strictly less than $\emph{d}+2$;  \emph{k} significant digits
are printed before the decimal point, and $\emph{d}-\emph{k}+1$
digits are printed after the decimal point.  If \emph{k} is negative,
then it must be strictly greater than $-\emph{d}$;
a single zero digit appears before the decimal point if
the total field width will permit it, and after the decimal point
are printed first
$-\emph{k}$ zeros and then $\emph{d}+\emph{k}$ significant digits.
The printed fraction must be properly rounded.
(When rounding up and rounding down would produce printed values
equidistant from the scaled value of \emph{arg}, then the implementation
is free to use either one.  For example, printing
\cd{637.5} using the format \cd{{\Xtilde}8,2E} may correctly produce
either \cd{6.37E+02} or \cd{6.38E+02}.)

Following the digit sequence, the exponent is printed.
First the character parameter \emph{exponentchar} is printed; if this
parameter is omitted, then the exponent marker that
\cd{prin1} would use is printed, as determined from the
type of the floating-point number and the current value of
\cdf{*read-default-float-format*}.
Next, either a plus sign or a minus sign
is printed, followed by \emph{e} digits representing the power of
10 by which the printed fraction must be multiplied
to properly represent the rounded value of \emph{arg}.

If it is impossible to print the value in the required format in a field
of width \emph{w}, possibly because \emph{k} is too large or too small
or because the exponent cannot be printed in \emph{e} character positions,
then one of two actions is taken.  If the
parameter \emph{overflowchar} is specified, then \emph{w} copies of that
parameter are printed instead of the scaled value of \emph{arg}.
If the \emph{overflowchar} parameter is omitted, then the scaled value
is printed using more than \emph{w} characters, as many more as may be
needed; if the problem is that \emph{d} is too small for the specified \emph{k}
or that \emph{e} is too small, then a larger value is used for \emph{d} or \emph{e}
as may be needed.

If the \emph{w} parameter is omitted, then the field is of variable width.
In effect a value is chosen
for \emph{w} in such a way that no leading pad characters need to be printed.

If the parameter \emph{d} is omitted, then there is no constraint
on the number of digits to appear.
A value is chosen for \emph{d} in such a way that as many digits
as possible may be printed subject to the width constraint
imposed by the parameter \emph{w}, the constraint of the scale factor \emph{k},
and the constraint that no trailing
zero digits may appear in the fraction, except that if the
fraction to be printed is zero, then a single zero digit should
appear after the decimal point if the width constraint allows it.

If the parameter \emph{e} is omitted, then the exponent is printed
using the smallest number of digits necessary to represent its value.

If all of \emph{w}, \emph{d}, and \emph{e} are omitted, then the effect is to print
the value using ordinary free-format exponential-notation output;
\cd{prin1} uses this format for any non-zero number whose magnitude
is less than $10^{-3}$ or greater than or equal to $10^7$.

\begin{new}
X3J13 voted in January 1989
\issue{FORMAT-E-EXPONENT-SIGN}
to amend the previous paragraph as follows:

If all of \emph{w}, \emph{d}, and \emph{e} are omitted, then the effect is to print
the value using ordinary free-format exponential-notation output;
\cd{prin1} uses a similar format for any non-zero number whose magnitude
is less than $10^{-3}$ or greater than or equal to $10^7$.
The only difference is that the \cd{{\Xtilde}E} directive always prints
a plus or minus sign before the exponent, while \cd{prin1} omits the plus sign
if the exponent is non-negative.

(The amendment reconciles this paragraph with the specification several
paragraphs above that \cd{{\Xtilde}E} always prints
a plus or minus sign before the exponent.)
\end{new}

If \emph{arg} is a rational number, then it is coerced to be a \cdf{single-float}
and then printed.  (Alternatively, an implementation is permitted to
process a rational number by any other method that has essentially the
same behavior but avoids such hazards as loss of precision or overflow
because of the coercion.  However, note that if \emph{w} and \emph{d} are
unspecified and the number has no exact decimal representation,
for example \cd{1/3}, some precision cutoff must be chosen
by the implementation: only a finite number of digits may be printed.)

If \emph{arg} is a complex number or some non-numeric
object, then it is printed using the format directive \cd{{\Xtilde}\emph{w}D},
thereby printing it in decimal radix and a minimum field width of \emph{w}.
(If it is desired to print each of the real part and imaginary part
of a complex number using a \cd{{\Xtilde}E} directive, then this must
be done explicitly with two \cd{{\Xtilde}E} directives and code to
extract the two parts of the complex number.)

\begin{new}
X3J13 voted in January 1989
\issue{FORMAT-PRETTY-PRINT}
to specify that \cdf{format} binds \cdf{*print-escape*} to \cdf{nil}
during the processing of the \cd{{\Xtilde}E} directive.
\end{new}

\begin{lisp}
(defun foo (x) \\
~~(format {\nil} \\
~~~~~~~~~~"{\Xtilde}9,2,1,,'*E|{\Xtilde}10,3,2,2,'?,,'\$E|{\Xtilde}9,3,2,-2,'\%{\Xatsign}E|{\Xtilde}9,2E" \\
~~~~~~~~~~x x x x)) \\
(foo 3.14159)~~\EV\ "~~3.14E+0|~31.42\$-01|+.003E+03|~~3.14E+0" \\
(foo -3.14159)~\EV\ "~-3.14E+0|-31.42\$-01|-.003E+03|~-3.14E+0" \\
(foo 1100.0) ~~\EV\ "~~1.10E+3|~11.00\$+02|+.001E+06|~~1.10E+3" \\
(foo 1100.0L0)~\EV\ "~~1.10L+3|~11.00\$+02|+.001L+06|~~1.10L+3" \\
(foo 1.1E13)~~~\EV\ "*********|~11.00\$+12|+.001E+16|~1.10E+13" \\
(foo 1.1L120)~~\EV\ "*********|??????????|\%\%\%\%\%\%\%\%\%|1.10L+120" \\
(foo 1.1L1200)~\EV\ "*********|??????????|\%\%\%\%\%\%\%\%\%|1.10L+1200"
\end{lisp}
Here is an example of the effects of varying the scale factor:
\begin{lisp}
(dotimes (k 13) \\
~~(format t "~\%Scale factor ~2D: |~13,6,2,VE|" \\
~~~~~~~~~~(- k 5) 3.14159))\`;\textrm{Prints 13 lines} \\
Scale factor -5: | 0.000003E+06| \\
Scale factor -4: | 0.000031E+05| \\
Scale factor -3: | 0.000314E+04| \\
Scale factor -2: | 0.003142E+03| \\
Scale factor -1: | 0.031416E+02| \\
Scale factor~~0: | 0.314159E+01| \\
Scale factor~~1: | 3.141590E+00| \\
Scale factor~~2: | 31.41590E-01| \\
Scale factor~~3: | 314.1590E-02| \\
Scale factor~~4: | 3141.590E-03| \\
Scale factor~~5: | 31415.90E-04| \\
Scale factor~~6: | 314159.0E-05| \\
Scale factor~~7: | 3141590.E-06|
\end{lisp}

\newpage%required

\item[\cd{{\Xtilde}G}]
\emph{General floating-point}.  The next \emph{arg} is printed as a floating-point
number in either fixed-format or exponential notation as appropriate.

The full form is \cd{{\Xtilde}\emph{w},\emph{d},\emph{e},\emph{k},\emph{overflowchar},\emph{padchar},\emph{exponentchar}G}.
The format in which to print \emph{arg} depends on the magnitude (absolute
value) of the \emph{arg}.  Let \emph{n} be an integer such that
$10^{\hbox{\scriptsize\it n}-1}\leq\hbox\emph{arg}<10^{\hbox{\scriptsize\it n}}$.
(If \emph{arg} is zero, let \emph{n} be 0.)
Let \emph{ee} equal $\emph{e}+2$, or 4 if \emph{e} is omitted.
Let \emph{ww} equal $\emph{w}-\hbox\emph{ee}$,
or {\nil} if \emph{w} is omitted.  If \emph{d} is omitted, first let \emph{q}
be the number of digits needed to print \emph{arg} with no loss
of information and without leading or trailing zeros;
then let \emph{d} equal \cd{(max \emph{q} (min \emph{n} 7))}.
Let \emph{dd} equal $\emph{d}-\emph{n}$.

If $0\leq\hbox\emph{dd}\leq \emph{d}$, then \emph{arg} is printed
as if by the format directives
\begin{lisp}
{\Xtilde}\emph{ww},\emph{dd},,\emph{overflowchar},\emph{padchar}F{\Xtilde}\emph{ee}{\Xatsign}T
\end{lisp}
Note that the scale factor \emph{k} is not passed to the \cd{{\Xtilde}F}
directive.  For all other values of \emph{dd}, \emph{arg} is printed as if
by the format directive
\begin{lisp}
{\Xtilde}\emph{w},\emph{d},\emph{e},\emph{k},\emph{overflowchar},\emph{padchar},\emph{exponentchar}E
\end{lisp}

In either case, an \cd{{\Xatsign}} modifier is specified to the \cd{{\Xtilde}F}
or \cd{{\Xtilde}E} directive if and only if one was specified to the
\cd{{\Xtilde}G} directive.

\cdf{format} binds \cdf{*print-escape*} to \cdf{nil}
during the processing of the \cd{{\Xtilde}G} directive.

Examples:
\begin{lisp}
(defun foo (x) \\
~~(format {\nil} \\
~~~~~~~~~~"{\Xtilde}9,2,1,,'*G|{\Xtilde}9,3,2,3,'?,,'\$G|{\Xtilde}9,3,2,0,'\%G|{\Xtilde}9,2G" \\
~~~~~~~~~~x x x)) \\[10pt]
(foo 0.0314159) \EV\ "~~3.14E-2|314.2\$-04|0.314E-01|~~3.14E-2" \\
(foo 0.314159)~~\EV\ "~~0.31~~~|0.314~~~~|0.314~~~~| 0.31~~~~" \\
(foo 3.14159)~~~\EV\ "~~~3.1~~~|~3.14~~~~|~3.14~~~~|~~3.1~~~~" \\
(foo 31.4159)~~~\EV\ "~~~31.~~~|~31.4~~~~|~31.4~~~~|~~31.~~~~" \\
(foo 314.159)~~~\EV\ "~~3.14E+2|~314.~~~~|~314.~~~~|~~3.14E+2" \\
(foo 3141.59)~~~\EV\ "~~3.14E+3|314.2\$+01|0.314E+04|~~3.14E+3" \\
(foo 3141.59L0)~\EV\ "~~3.14L+3|314.2\$+01|0.314L+04|~~3.14L+3" \\
(foo 3.14E12)~~~\EV\ "*********|314.0\$+10|0.314E+13|~3.14E+12" \\
(foo 3.14L120)~~\EV\ "*********|?????????|\%\%\%\%\%\%\%\%\%|3.14L+120" \\
(foo 3.14L1200)~\EV\ "*********|?????????|\%\%\%\%\%\%\%\%\%|3.14L+1200"
\end{lisp}
\newpage%manual

\item[\cd{{\Xtilde}\$}]
\emph{Dollars floating-point}.  The next \emph{arg} is printed as a floating-point
number in fixed-format notation.  This format is particularly
convenient for printing a value as dollars and cents.

The full form is \cd{{\Xtilde}\emph{d},\emph{n},\emph{w},\emph{padchar}\$}.
The parameter \emph{d} is the number
of digits to print after the decimal point (default value 2);
\emph{n} is the minimum number of digits to print before the decimal
point (default value 1);
\emph{w} is the minimum total width of the field to be printed (default
value 0).

First padding and the sign are output.
If the \emph{arg} is negative, then a minus sign is printed;
if the \emph{arg} is not negative, then a plus sign is printed
if and only if the \cd{{\Xatsign}} modifier was specified.  
If the \cd{:} modifier is used, the sign appears before any padding,
and otherwise after the padding.
If \emph{w} is specified and the number of other characters to be output
is less than \emph{w}, then copies of \emph{padchar} (which defaults
to a space) are output to
make the total field width equal \emph{w}.
Then \emph{n} digits are printed for the integer part of \emph{arg},
with leading zeros if necessary; then a decimal point;
then \emph{d} digits of fraction, properly rounded.

If the magnitude of \emph{arg} is so large that more than \emph{m} digits would
have to be printed, where \emph{m} is the larger of \emph{w} and 100, then an
implementation is free, at its discretion, to print the number using
exponential notation instead, as if by the directive
\cd{{\Xtilde}\emph{w},\emph{q},,,,\emph{padchar}E}, where \emph{w} and \emph{padchar} are
present or omitted according to whether they were present or omitted in
the \cd{{\Xtilde}\$} directive, and where $\emph{q}=\emph{d}+\emph{n}-1$,
where \emph{d} and \emph{n} are the (possibly default) values given to the
\cd{{\Xtilde}\$} directive.

If \emph{arg} is a rational number, then it is coerced to be a \cdf{single-float}
and then printed.  (Alternatively, an implementation is permitted to
process a rational number by any other method that has essentially the
same behavior but avoids such hazards as loss of precision or overflow
because of the coercion.)

If \emph{arg} is a complex number or some non-numeric
object, then it is printed using the format directive \cd{{\Xtilde}\emph{w}D},
thereby printing it in decimal radix and a minimum field width of \emph{w}.
(If it is desired to print each of the real part and imaginary part
of a complex number using a \cd{{\Xtilde}\$} directive, then this must
be done explicitly with two \cd{{\Xtilde}\$} directives and code to
extract the two parts of the complex number.)

\cdf{format} binds \cdf{*print-escape*} to \cdf{nil}
during the processing of the \cd{{\Xtilde}\$} directive.

\item[\cd{{\Xtilde}\%}]
This outputs a \cd{\#{\Xbackslash}Newline} character, thereby terminating the current
output line and beginning a new one
(see \cdf{terpri}).

\cd{{\Xtilde}\emph{n}\%} outputs \emph{n} newlines.

No \emph{arg} is used.  Simply putting a newline in the control string
would work, but \cd{{\Xtilde}\%} is often used because it makes the control string
look nicer in the middle of a Lisp program.

\item[\cd{{\Xtilde}\&}]
Unless it can be determined that the output stream
is already at the beginning of a line,
this outputs a newline (see \cdf{fresh-line}).

\cd{{\Xtilde}\emph{n}\&} calls \cdf{fresh-line}
and then outputs $\emph{n}-1$ newlines.
\cd{{\Xtilde}0\&} does nothing.

\item[\cd{{\Xtilde}|}]
This outputs a page separator character, if possible.
\cd{{\Xtilde}\emph{n}|} does this
\emph{n} times.  \cd{|} is vertical bar, not capital I.

\item[\cd{{\Xtilde}{\Xtilde}}]
\emph{Tilde}.
This outputs a tilde.  \cd{{\Xtilde}\emph{n}{\Xtilde}} outputs \emph{n} tildes.

\item[\cd{{\Xtilde}}$\langle$newline$\rangle$]
Tilde immediately followed by a newline ignores the newline
and any following non-newline whitespace characters.
With a \cd{:}, the newline
is ignored, but any following whitespace is left in place.
With an \cd{{\Xatsign}}, the newline
is left in place, but any following whitespace is ignored.
This directive is typically used when a format control string is too long
to fit nicely into one line of the program:
\begin{lisp}
(defun type-clash-error (fn nargs argnum right-type wrong-type) \\*
~~(format *error-output* \\*
~~~~~~~~~~"{\Xtilde}\&Function {\Xtilde}S requires its {\Xtilde}:{\Xlbracket}{\Xtilde}:R{\Xtilde};{\Xtilde}*{\Xtilde}{\Xrbracket} {\Xtilde} \\*
~~~~~~~~~~~argument to be of type {\Xtilde}S,{\Xtilde}\%but it was called {\Xtilde} \\*
~~~~~~~~~~~with an argument of type {\Xtilde}S.{\Xtilde}\%" \\*
~~~~~~~~~~fn (eql nargs 1) argnum right-type wrong-type)) \\
 \\
(type-clash-error 'aref nil 2 'integer 'vector)  \textrm{prints}: \\*
Function AREF requires its second argument to be of type INTEGER, \\*
but it was called with an argument of type VECTOR. \\
 \\
(type-clash-error 'car 1 1 'list 'short-float)  \textrm{prints}: \\
Function CAR requires its argument to be of type LIST, \\
but it was called with an argument of type SHORT-FLOAT.
\end{lisp}
Note that in this example newlines appear in the output only as specified
by the \cd{{\Xtilde}\&} and \cd{{\Xtilde}\%} directives; the actual newline characters
in the control string are suppressed because each is preceded by a tilde.

\item[\cd{{\Xtilde}T}]
\emph{Tabulate}.
This spaces over to a given column.
\cd{{\Xtilde}\emph{colnum},\emph{colinc}T} will output
sufficient spaces to move the cursor to column \emph{colnum}.  If the cursor
is already at or beyond column \emph{colnum}, it will output spaces to move it to
column \emph{colnum}+\emph{k}*\emph{colinc} for the smallest positive integer
\emph{k} possible, unless \emph{colinc} is zero, in which case no spaces
are output if the cursor is already at or beyond column \emph{colnum}.
\emph{colnum} and \emph{colinc} default to \cd{1}.

Ideally, the current column position is determined by examination of the
destination, whether a stream or string. (Although no user-level
operation for determining the column position of a stream is defined
by Common Lisp, such a facility may exist at the implementation level.)
If for some reason the current absolute column position cannot be determined
by direct inquiry,
\cdf{format} may be able to deduce the current column position by noting
that certain directives (such as \cd{{\Xtilde}\%}, or \cd{{\Xtilde}\&},
or \cd{{\Xtilde}A} with the argument being a string containing a newline) cause
the column position to be reset to zero, and counting the number of characters
emitted since that point.  If that fails, \cdf{format} may attempt a
similar deduction on the riskier assumption that the destination was
at column zero when \cdf{format} was invoked.  If even this heuristic fails
or is implementationally inconvenient, at worst
the \cd{{\Xtilde}T} operation will simply output two spaces.
(All this implies that code that uses \cdf{format} is
more likely to be portable if all format control strings that use 
the \cd{{\Xtilde}T} directive either begin with \cd{{\Xtilde}\%} or \cd{{\Xtilde}\&}
to force a newline
or are designed to be used only when the destination is known from other
considerations to be at column zero.)

\cd{{\Xtilde}{\Xatsign}T} performs \emph{relative} tabulation.
\cd{{\Xtilde}\emph{colrel},\emph{colinc}{\Xatsign}T} outputs \emph{colrel} spaces
and then outputs the smallest non-negative
number of additional spaces necessary to move the cursor
to a column that is a multiple
of \emph{colinc}.  For example, the directive \cd{{\Xtilde}3,8{\Xatsign}T} outputs
three spaces and then moves the cursor to a ``standard multiple-of-eight
tab stop'' if not at one already.
If the current output column cannot be determined, however,
then \emph{colinc} is ignored, and exactly \emph{colrel} spaces are output.

\begin{new}
X3J13 voted in June 1989 \issue{PRETTY-PRINT-INTERFACE} to define \cd{{\Xtilde}:T}
and \cd{{\Xtilde}:{\Xatsign}T} to perform tabulation relative to a point defined
by the pretty printing process (see section~\ref{PPRINT-FORMAT-DIRECTIVES-SECTION}).
\end{new}

\item[\cd{{\Xtilde}*}]
The next \emph{arg} is ignored.  \cd{{\Xtilde}\emph{n}*} ignores the next \emph{n} arguments.

\cd{{\Xtilde}:*} ``ignores backwards''; that is, it backs up in the list of
arguments so that the argument last processed will be processed again.
\cd{{\Xtilde}\emph{n}:*} backs up \emph{n} arguments.

When within a \cd{{\Xtilde}{\Xlbrace}} construct
(see below), the ignoring (in either direction) is relative to the list
of arguments being processed by the iteration.

\cd{{\Xtilde}\emph{n}{\Xatsign}*} is an ``absolute goto'' rather than a ``relative goto'':
it goes to the \emph{n}th \emph{arg}, where 0 means the first one;
\emph{n} defaults to 0, so \cd{{\Xtilde}{\Xatsign}*} goes back to the first \emph{arg}.
Directives after a \cd{{\Xtilde}\emph{n}{\Xatsign}*}
will take arguments in sequence beginning with the one gone to.
When within a \cd{{\Xtilde}{\Xlbrace}} construct, the ``goto''
is relative to the list of arguments being processed by the iteration.

\item[\cd{{\Xtilde}?}]
\emph{Indirection}.
The next \emph{arg} must be a string, and the one after it a list;
both are consumed by the \cd{{\Xtilde}?} directive.
The string is processed as a \cdf{format} control string, with the
elements of the list as the arguments.  Once the recursive processing
of the control string has been finished, then processing of the control
string containing the \cd{{\Xtilde}?} directive is resumed.
Example:
\begin{lisp}
(format nil "{\Xtilde}? {\Xtilde}D" "<{\Xtilde}A {\Xtilde}D>" '("Foo" 5) 7) \EV\ "<Foo 5> 7" \\
(format nil "{\Xtilde}? {\Xtilde}D" "<{\Xtilde}A {\Xtilde}D>" '("Foo" 5 14) 7) \EV\ "<Foo 5> 7"
\end{lisp}
Note that in the second example three arguments are supplied
to the control string \cd{"<{\Xtilde}A {\Xtilde}D>"}, but only two are processed
and the third is therefore ignored.

With the \cd{{\Xatsign}} modifier, only one \emph{arg} is directly consumed.
The \emph{arg} must be a string; it is processed as part of the control
string as if it had appeared in place of the \cd{{\Xtilde}{\Xatsign}?} construct,
and any directives in the recursively processed control string may
consume arguments of the control string containing the \cd{{\Xtilde}{\Xatsign}?}
directive.
Example:
\begin{lisp}
(format nil "{\Xtilde}{\Xatsign}? {\Xtilde}D" "<{\Xtilde}A {\Xtilde}D>" "Foo" 5 7) \EV\ "<Foo 5> 7" \\
(format nil "{\Xtilde}{\Xatsign}? {\Xtilde}D" "<{\Xtilde}A {\Xtilde}D>" "Foo" 5 14 7) \EV\ "<Foo 5> 14"
\end{lisp}

Here is a rather sophisticated example.
The \cdf{format} function itself,
as implemented at one time in Lisp Machine Lisp,
used a routine internal to the \cdf{format} package called \cdf{format-error} to
signal error messages; \cdf{format-error} in turn used \cdf{error}, which used
\cdf{format} recursively.  Now \cdf{format-error} took a string and
arguments, just like \cdf{format}, but also printed the control string
to \cdf{format} (which at this point was available
in the global variable \cd{*ctl-string*}) and a little
arrow showing where in the processing of the control string the error
occurred.  The variable \cd{*ctl-index*} pointed one character after the
place of the error.
\begin{lisp}
(defun format-error (string \&rest args)~~~~~;\textrm{Example} \\
~~(error {\false} "{\Xtilde}?{\Xtilde}\%{\Xtilde}V{\Xatsign}T{\Xarrowdown}{\Xtilde}\%{\Xtilde}3{\Xatsign}T{\Xbackslash}"{\Xtilde}A{\Xbackslash}"{\Xtilde}\%" \\
~~~~~~~~~string args (+ *ctl-index* 3) *ctl-string*))
\end{lisp}
(The character set used in the Lisp Machine Lisp implementation contains a
down-arrow character \cd{\Xarrowdown}, which is not a standard Common Lisp
character.)  This first processed the given string and arguments using
\cd{{\Xtilde}?}, then output a newline, tabbed a variable amount for
printing the down-arrow, and printed the control string between
double quotes (note the use of \cd{{\Xbackslash}"} to include double quotes within
the control string).  The effect was something like this:
\begin{lisp}
(format t "The item is a {\Xtilde}{\Xlbracket}Foo{\Xtilde};Bar{\Xtilde};Loser{\Xtilde}{\Xrbracket}." 'quux) \\
>>ERROR: The argument to the FORMAT "{\Xtilde}{\Xlbracket}" command  \\
~~~~~~~~~must be a number. \\
~~~~~~~~~~~~~~~~~~~{\Xarrowdown} \\
~~~"The item is a {\Xtilde}{\Xlbracket}Foo{\Xtilde};Bar{\Xtilde};Loser{\Xtilde}{\Xrbracket}."
\end{lisp}

\beforenoterule
\begin{implementation}
Implementors may wish to report errors occurring
within \cdf{format} control strings in the manner outlined here.
It looks pretty flashy when done properly.
\end{implementation}
\afternoterule
\end{flushdesc}

\begin{new}
X3J13 voted in June 1989 \issue{PRETTY-PRINT-INTERFACE} to introduce
certain \cdf{format} directives to support the user interface to the pretty
printer described in detail in chapter~\ref{PPRINT}.

\begin{flushdesc}
\item[\cd{{\Xtilde}{\Xunderscore}}]
\emph{Conditional newline.} Without any modifiers, the directive
\cd{{\Xtilde}{\Xunderscore}} is equivalent to
\cd{(pprint-newline :linear)}.  The directive
\cd{{\Xtilde}{\Xatsign}{\Xunderscore}} is
equivalent to \cd{(pprint-newline :miser)}.  The directive
\cd{{\Xtilde}:{\Xunderscore}}
is equivalent to \cd{(pprint-newline :fill)}.  The directive
\cd{{\Xtilde}:{\Xatsign}{\Xunderscore}} is
equivalent to \cd{(pprint-newline :mandatory)}.

\item[\cd{{\Xtilde}W}]
\emph{Write.}  An \emph{arg}, any Lisp object, is printed obeying \emph{every}
printer control variable (as by \cdf{write}).
See section~\ref{PPRINT-FORMAT-DIRECTIVES-SECTION} for details.

\item[\cd{{\Xtilde}I}]
\emph{Indent.} The directive \cd{{\Xtilde}\emph{n}I} is equivalent to
\cd{(pprint-indent~:block~\emph{n})}.  The directive \cd{{\Xtilde}:\emph{n}I} is equivalent to
\cd{(pprint-indent~:current~\emph{n})}.  In both cases, \emph{n} defaults to zero,
if it is omitted.
\end{flushdesc}
\end{new}

The format directives after this point are much more complicated than the
foregoing; they constitute control structures that can perform
case conversion,
conditional selection, iteration, justification, and non-local exits.
Used with restraint, they can perform powerful tasks.  Used with
abandon, they can produce completely unreadable and unmaintainable code.

The case-conversion, conditional, iteration, and justification
constructs can contain other formatting constructs by bracketing them.
These constructs must nest properly with respect to each other.
For example, it is not legitimate to put the start of a case-conversion
construct in each arm of a conditional and the
end of the case-conversion construct outside the conditional:
\begin{lisp}
(format {\false} "{\Xtilde}:{\Xlbracket}abc{\Xtilde}:{\Xatsign}(def{\Xtilde};ghi{\Xtilde}:{\Xatsign}(jkl{\Xtilde}{\Xrbracket}mno{\Xtilde})" x)~~~~~;\textrm{Illegal!}
\end{lisp}
One might expect this to produce either \cd{"abcDEFMNO"} or \cd{"ghiJKLMNO"},
depending on whether \cdf{x} is false or true; but in fact the construction
is illegal because the \cd{{\Xtilde}{\Xlbracket}...{\Xtilde};...{\Xtilde}{\Xrbracket}}
and \cd{{\Xtilde}(...{\Xtilde})} constructs are not properly nested.

The processing indirection caused by the \cd{{\Xtilde}?} directive
is also a kind of nesting for the purposes of this rule of proper nesting.
It is not permitted to
start a bracketing construct within a string processed
under control of a \cd{{\Xtilde}?}
directive and end the construct at some point after the \cd{{\Xtilde}?} construct
in the string containing that construct, or vice versa.
For example, this situation is illegal:
\begin{lisp}
(format {\false} "{\Xtilde}?ghi{\Xtilde})" "abc{\Xtilde}{\Xatsign}(def")~~~~~;\textrm{Illegal!}
\end{lisp}
One might expect it to produce \cd{"abcDEFGHI"}, but in fact the construction
is illegal because the \cd{{\Xtilde}?}
and \cd{{\Xtilde}(...{\Xtilde})} constructs are not properly nested.

\begin{flushdesc}
\item[\cd{{\Xtilde}(\emph{str}{\Xtilde})}]
\emph{Case conversion}.
The contained control string \emph{str} is processed, and what it produces
is subject to case conversion:
\cd{{\Xtilde}(} converts every uppercase character
to the corresponding lowercase character;
\cd{{\Xtilde}:(} capitalizes all words, as if by \cdf{string-capitalize};
\cd{{\Xtilde}{\Xatsign}(} capitalizes just the first word and forces the rest to lowercase;
\cd{{\Xtilde}:{\Xatsign}(} converts every lowercase character
to the corresponding uppercase character.
In this example, \cd{{\Xtilde}{\Xatsign}(} is used to cause the first word
produced by \cd{{\Xtilde}{\Xatsign}R} to be capitalized:
\begin{lisp}
(format nil "{\Xtilde}{\Xatsign}R {\Xtilde}({\Xtilde}{\Xatsign}R{\Xtilde})" 14 14) \EV\ "XIV xiv" \\
(defun f (n) (format nil "{\Xtilde}{\Xatsign}({\Xtilde}R{\Xtilde}) error{\Xtilde}:P detected." n)) \\
(f 0) \EV\ "Zero errors detected." \\
(f 1) \EV\ "One error detected." \\
(f 23) \EV\ "Twenty-three errors detected."
\end{lisp}

\item[\cd{{\Xtilde}{\Xlbracket}\emph{str0}{\Xtilde};\emph{str1}{\Xtilde};\emph{...}{\Xtilde};\emph{strn}{\Xtilde}{\Xrbracket}}]
\emph{Conditional expression}.
This is a set of control strings, called \emph{clauses}, one of which is
chosen and used.  The clauses are separated by \cd{{\Xtilde};} and the construct
is terminated by \cd{{\Xtilde}{\Xrbracket}}.  For example,
\begin{lisp}
"{\Xtilde}{\Xlbracket}Siamese{\Xtilde};Manx{\Xtilde};Persian{\Xtilde}{\Xrbracket} Cat"
\end{lisp}
The \emph{arg}th
clause is selected, where the first clause is number 0.
If a prefix parameter is given (as \cd{{\Xtilde}\emph{n}{\Xlbracket}}),
then the parameter is used instead of an argument.
(This is useful only if the parameter is specified by \cd{\#},
to dispatch on the number of arguments remaining to be processed.)
If \emph{arg} is out of range, then no clause is selected
(and no error is signaled).
After the selected alternative has been processed, the control string
continues after the \cd{{\Xtilde}{\Xrbracket}}.

\cd{{\Xtilde}{\Xlbracket}\emph{str0}{\Xtilde};\emph{str1}{\Xtilde};\emph{...}{\Xtilde};\emph{strn}{\Xtilde}:;\emph{default}{\Xtilde}{\Xrbracket}} has a default case.
If the \emph{last} \cd{{\Xtilde};} used to separate clauses
is \cd{{\Xtilde}:;} instead, then the last clause is an ``else'' clause
that is performed if no other clause is selected.
For example:
\begin{lisp}
"{\Xtilde}{\Xlbracket}Siamese{\Xtilde};Manx{\Xtilde};Persian{\Xtilde}:;Alley{\Xtilde}{\Xrbracket} Cat"
\end{lisp}

\cd{{\Xtilde}:{\Xlbracket}\emph{false}{\Xtilde};\emph{true}{\Xtilde}{\Xrbracket}} selects the \emph{false} control string
if \emph{arg} is {\false}, and selects the \emph{true} control string otherwise.

\cd{{\Xtilde}{\Xatsign}{\Xlbracket}\emph{true}{\Xtilde}{\Xrbracket}} tests the argument.  If it is not {\false},
then the argument is not used up by the \cd{{\Xtilde}{\Xatsign}{\Xlbracket}} command
but remains as the next one to be processed,
and the one clause \emph{true} is processed.
If the \emph{arg} is {\false}, then the argument is used up,
and the clause is not processed.
The clause therefore should normally use exactly one argument,
and may expect it to be non-{\false}.
For example:
\begin{lisp}
(setq *print-level* {\false} *print-length* 5) \\*
(format {\false} "{\Xtilde}{\Xatsign}{\Xlbracket} print level = {\Xtilde}D{\Xtilde}{\Xrbracket}{\Xtilde}{\Xatsign}{\Xlbracket} print length = {\Xtilde}D{\Xtilde}{\Xrbracket}" \\*
~~~~~~~~~~~~*print-level* *print-length*) \\*
~~~\EV\  " print length = 5"
\end{lisp}

The combination of \cd{{\Xtilde}{\Xlbracket}} and \cd{\#} is useful, for
example, for dealing with English conventions for printing lists:
\begin{lisp}
(setq foo "Items:{\Xtilde}\#{\Xlbracket} none{\Xtilde}; {\Xtilde}S{\Xtilde}; {\Xtilde}S and {\Xtilde}S{\Xtilde} \\
~~~~~~~~~~~{\Xtilde}:;{\Xtilde}{\Xatsign}{\Xlbrace}{\Xtilde}\#{\Xlbracket}{\Xtilde}; and{\Xtilde}{\Xrbracket}
{\Xtilde}S{\Xtilde}{\Xcircumflex},{\Xtilde}{\Xrbrace}{\Xtilde}{\Xrbracket}.") \\
(format {\false} foo) \\ ~~~~~~~~\EV\  "Items: none." \\
(format {\false} foo 'foo) \\
~~~~~~~~\EV\  "Items: FOO." \\
(format {\false} foo 'foo 'bar) \\
~~~~~~~~\EV\  "Items: FOO and BAR." \\
(format {\false} foo 'foo 'bar 'baz) \\
~~~~~~~~\EV\  "Items: FOO, BAR, and BAZ." \\
(format {\false} foo 'foo 'bar 'baz 'quux) \\
~~~~~~~~\EV\  "Items: FOO, BAR, BAZ, and QUUX."
\end{lisp}

\item[\cd{{\Xtilde};}]
This separates clauses in \cd{{\Xtilde}{\Xlbracket}} and \cd{{\Xtilde}<}
constructions.  It is an error elsewhere.

\item[\cd{{\Xtilde}{\Xrbracket}}]
This terminates a \cd{{\Xtilde}{\Xlbracket}}.  It is an error elsewhere.

\item[\cd{{\Xtilde}{\Xlbrace}\emph{str}{\Xtilde}{\Xrbrace}}]
\emph{Iteration}.
This is an iteration construct.  The argument should be a list,
which is used as a set of arguments as if for a recursive call to \cdf{format}.
The string \emph{str} is used repeatedly as the control string.
Each iteration can absorb as many elements of the list as it likes
as arguments;
if \emph{str} uses up two arguments by itself, then two elements of the
list will get used up each time around the loop.
If before any iteration step the list is empty, then the iteration is terminated.
Also, if a prefix parameter \emph{n} is given, then there will be at most \emph{n}
repetitions of processing of \emph{str}.  Finally, the
\cd{{\Xtilde}{\Xcircumflex}} directive can be used to terminate the iteration
prematurely.

Here are some simple examples:
\begin{lisp}
(format {\false} \\
~~~~~~~~"The winners are:{\Xtilde}{\Xlbrace} {\Xtilde}S{\Xtilde}{\Xrbrace}." \\
~~~~~~~~'(fred harry jill)) \\
~~~~~\EV\ "The winners are: FRED HARRY JILL." \\
\\
(format {\false} "Pairs:{\Xtilde}{\Xlbrace} <{\Xtilde}S,{\Xtilde}S>{\Xtilde}{\Xrbrace}." '(a 1 b 2 c 3)) \\
~~~~~\EV\ "Pairs: <A,1> <B,2> <C,3>."
\end{lisp}

\cd{{\Xtilde}:{\Xlbrace}\emph{str}{\Xtilde}{\Xrbrace}} is similar, but the argument should be a list of sublists.
At each repetition step, one sublist is used as the set of arguments for
processing \emph{str}; on the next repetition, a new sublist is used, whether
or not all of the last sublist had been processed.  Example:
\begin{lisp}
(format {\false} "Pairs:{\Xtilde}:{\Xlbrace} <{\Xtilde}S,{\Xtilde}S>{\Xtilde}{\Xrbrace}." \\
~~~~~~~~~~~~'((a 1) (b 2) (c 3))) \\
~~~~~\EV\ "Pairs: <A,1> <B,2> <C,3>."
\end{lisp}

\cd{{\Xtilde}{\Xatsign}{\Xlbrace}\emph{str}{\Xtilde}{\Xrbrace}} is similar to \cd{{\Xtilde}{\Xlbrace}\emph{str}{\Xtilde}{\Xrbrace}}, but instead of
using one argument that is a list, all the remaining arguments
are used as the list of arguments for the iteration.
Example:
\begin{lisp}
(format {\false} "Pairs:{\Xtilde}{\Xatsign}{\Xlbrace} <{\Xtilde}S,{\Xtilde}S>{\Xtilde}{\Xrbrace}." \\
~~~~~~~~~~~~'a 1 'b 2 'c 3) \\
~~~~~\EV\ "Pairs: <A,1> <B,2> <C,3>."
\end{lisp}
If the iteration is terminated before all the remaining arguments are
consumed, then any arguments not processed by the iteration remain to be
processed by any directives following the iteration construct.

\cd{{\Xtilde}:{\Xatsign}{\Xlbrace}\emph{str}{\Xtilde}{\Xrbrace}}
combines the features of \cd{{\Xtilde}:{\Xlbrace}\emph{str}{\Xtilde}{\Xrbrace}}
and \cd{{\Xtilde}{\Xatsign}{\Xlbrace}\emph{str}{\Xtilde}{\Xrbrace}}.
All the remaining arguments
are used, and each one must be a list.
On each iteration, the next argument is used as a list of arguments to \emph{str}.
Example:
\begin{lisp}
(format {\false} "Pairs:{\Xtilde}:{\Xatsign}{\Xlbrace} <{\Xtilde}S,{\Xtilde}S>{\Xtilde}{\Xrbrace}." \\
~~~~~~~~~~~~'(a 1) '(b 2) '(c 3)) \\
~~~~~\EV\ "Pairs: <A,1> <B,2> <C,3>."
\end{lisp}

Terminating the repetition construct with \cd{{\Xtilde}:{\Xrbrace}} instead of
\cd{{\Xtilde}{\Xrbrace}} forces \emph{str} to be processed at least once, even if
the initial list of arguments is null (however, it will not override an explicit
prefix parameter of zero).

If \emph{str} is empty, then an argument is used as \emph{str}.  It must be a string
and precede any arguments processed by the iteration.  As an example,
the following are equivalent:
\begin{lisp}
(apply \#'format stream string arguments) \\
(format stream "{\Xtilde}1{\Xlbrace}{\Xtilde}:{\Xrbrace}" string arguments)
\end{lisp}
This will use \cdf{string} as a formatting string.  The \cd{{\Xtilde}1{\Xlbrace}} says it will
be processed at most once, and the \cd{{\Xtilde}:{\Xrbrace}} says it will be processed at least once.
Therefore it is processed exactly once, using \cdf{arguments} as the arguments.
This case may be handled more clearly by the \cd{{\Xtilde}?} directive,
but this general feature of \cd{{\Xtilde}{\Xlbrace}}
is more powerful than \cd{{\Xtilde}?}.

\item[\cd{{\Xtilde}{\Xrbrace}}]
This terminates a \cd{{\Xtilde}{\Xlbrace}}.  It is an error elsewhere.

\item[\cd{{\Xtilde}\emph{mincol},\emph{colinc},\emph{minpad},\emph{padchar}<\emph{str}{\Xtilde}>}]
\emph{Justification}.
This justifies the text produced by processing \emph{str}
within a field at least \emph{mincol} columns wide.  \emph{str}
may be divided up into segments with \cd{{\Xtilde};}, in which case the
spacing is evenly divided between the text segments.

With no modifiers, the leftmost text segment is left-justified in the
field, and the rightmost text segment right-justified;  if there is
only one text element, as a special case, it is right-justified.
The \cd{:} modifier causes
spacing to be introduced before the first text segment;  the \cd{{\Xatsign}}
modifier causes spacing to be added after the last.
The \emph{minpad} parameter (default \cd{0}) is the minimum number of
padding characters to be output between each segment.
The padding character is specified by \emph{padchar},
which defaults to the space character.
If the total width needed to satisfy these constraints is greater
than \emph{mincol}, then the width used is \emph{mincol}+\emph{k}*\emph{colinc}
for the smallest possible non-negative integer value \emph{k};
\emph{colinc} defaults to \cd{1}, and \emph{mincol} defaults to \cd{0}.

\begin{lisp}
(format {\false} "{\Xtilde}10<foo{\Xtilde};bar{\Xtilde}>")~~~~~~~~~~\EV\  "foo~~~~bar" \\*
(format {\false} "{\Xtilde}10:<foo{\Xtilde};bar{\Xtilde}>")~~~~~~~~~\EV\  "~~foo~~bar" \\
(format {\false} "{\Xtilde}10:{\Xatsign}<foo{\Xtilde};bar{\Xtilde}>")~~~~~~~~\EV\  "~~foo~bar~" \\
(format {\false} "{\Xtilde}10<foobar{\Xtilde}>")~~~~~~~~~~~~\EV\  "~~~~foobar" \\
(format {\false} "{\Xtilde}10:<foobar{\Xtilde}>")~~~~~~~~~~~\EV\  "~~~~foobar" \\
(format {\false} "{\Xtilde}10{\Xatsign}<foobar{\Xtilde}>")~~~~~~~~~~~\EV\  "foobar~~~~" \\*
(format {\false} "{\Xtilde}10:{\Xatsign}<foobar{\Xtilde}>")~~~~~~~~~~\EV\  "~~foobar~~"
\end{lisp}

Note that \emph{str} may include \cdf{format} directives.
All the clauses in \emph{str} are processed in order;
it is the resulting pieces of text that are justified.

The \cd{{\Xtilde}{\Xcircumflex}} directive may be used to terminate processing
of the clauses prematurely, in which case only the completely processed clauses
are justified.

If the first clause of a \cd{{\Xtilde}<} is terminated with \cd{{\Xtilde}:;} instead of
\cd{{\Xtilde};}, then it is used in a special way.  All of the clauses are
processed (subject to \cd{{\Xtilde}{\Xcircumflex}}, of course), but the first one is not used
in performing the spacing and padding.  When the padded result has been
determined, then if it will fit on the current line of output, it is
output, and the text for the first clause is discarded.  If, however, the
padded text will not fit on the current line, then the text segment for
the first clause is output before the padded text.  The first clause
ought to contain a newline (such as a \cd{{\Xtilde}\%} directive).  The first
clause is always processed, and so any arguments it refers to will be
used; the decision is whether to use the resulting segment of text, not
whether to process the first clause.  If the \cd{{\Xtilde}:;} has a prefix
parameter \emph{n}, then the padded text must fit on the current line with
\emph{n} character positions to spare to avoid outputting the first clause's
text.  For example, the control string
\begin{lisp}
"{\Xtilde}\%;; {\Xtilde}{\Xlbrace}{\Xtilde}<{\Xtilde}\%;; {\Xtilde}1:; {\Xtilde}S{\Xtilde}>{\Xtilde}{\Xcircumflex},{\Xtilde}{\Xrbrace}.{\Xtilde}\%"
\end{lisp}
can be used to print a list of items separated by commas without
breaking items over line boundaries, beginning each line with
\cd{;; }.  The prefix parameter \cd{1} in \cd{{\Xtilde}1:;} accounts for the width of the
comma that will follow the justified item if it is not the last
element in the list, or the period if it is.  If \cd{{\Xtilde}:;} has a second
prefix parameter, then it is used as the width of the line,
thus overriding the natural line width of the output stream.  To make
the preceding example use a line width of 50, one would write
\begin{lisp}
"{\Xtilde}\%;; {\Xtilde}{\Xlbrace}{\Xtilde}<{\Xtilde}\%;; {\Xtilde}1,50:; {\Xtilde}S{\Xtilde}>{\Xtilde}{\Xcircumflex},{\Xtilde}{\Xrbrace}.{\Xtilde}\%"
\end{lisp}

If the second argument is not specified, then \cdf{format} uses the
line width of the output stream.
If this cannot be determined (for example, when producing a string result),
then \cdf{format} uses \cd{72} as the line length.

\item[\cd{{\Xtilde}>}]
Terminates a \cd{{\Xtilde}<}.  It is an error elsewhere.
\begin{new}
X3J13 voted in June 1989 \issue{PRETTY-PRINT-INTERFACE} to introduce
certain \cdf{format} directives to support the user interface to the pretty
printer.  If \cd{{\Xtilde}:>} is used to terminate a
\cd{{\Xtilde}<...} directive, the directive is equivalent to a call on
\cdf{pprint-logical-block}.
See section~\ref{PPRINT-FORMAT-DIRECTIVES-SECTION} for details.
\end{new}

\item[\cd{{\Xtilde}{\Xcircumflex}}]
\emph{Up and out}.
This is an escape construct.  If there are no more arguments remaining to
be processed, then the immediately enclosing \cd{{\Xtilde}{\Xlbrace}} or \cd{{\Xtilde}<} construct
is terminated.  If there is no such enclosing construct, then the entire
formatting operation is terminated.  In the \cd{{\Xtilde}<} case, the formatting
\emph{is} performed, but no more segments are processed before doing the
justification.  The \cd{{\Xtilde}{\Xcircumflex}} should appear only at the \emph{beginning} of a
\cd{{\Xtilde}<} clause, because it aborts the entire clause it appears in (as well
as all following clauses).
\cd{{\Xtilde}{\Xcircumflex}} may appear anywhere in a \cd{{\Xtilde}{\Xlbrace}}
construct.
\begin{lisp}
(setq donestr "Done.{\Xtilde}{\Xcircumflex}  {\Xtilde}D warning{\Xtilde}:P.{\Xtilde}{\Xcircumflex}  {\Xtilde}D error{\Xtilde}:P.") \\
(format {\false} donestr) \EV\ "Done." \\
(format {\false} donestr 3) \EV\ "Done.  3 warnings." \\
(format {\false} donestr 1 5) \EV\ "Done.  1 warning.  5 errors."
\end{lisp}

If a prefix parameter is given, then termination occurs if the parameter
is zero.  (Hence \cd{{\Xtilde}{\Xcircumflex}} is equivalent to \cd{{\Xtilde}\#{\Xcircumflex}}.)  If two
parameters are given, termination occurs if they are equal.  If three
parameters are given, termination occurs if the first is less than or
equal to the second and the second is less than or equal to the third.
Of course, this is useless if all the prefix parameters are constants; at
least one of them should be a \cd{\#} or a \cdf{V} parameter.

If \cd{{\Xtilde}{\Xcircumflex}} is used within a \cd{{\Xtilde}:{\Xlbrace}} construct, then it merely terminates
the current iteration step (because in the standard case it tests for
remaining arguments of the current step only); the next iteration step
commences immediately.  To terminate the entire iteration process,
use \cd{{\Xtilde}:{\Xcircumflex}}.

\begin{new}
X3J13 voted in March 1988
\issue{FORMAT-COLON-UPARROW-SCOPE}
to clarify the behavior of \cd{{\Xtilde}:{\Xcircumflex}} as follows.
It may be used only if the command it would terminate is \cd{{\Xtilde}:{\Xlbrace}}
or \cd{{\Xtilde}:{\Xatsign}{\Xlbrace}}.  The entire iteration process is terminated
if and only if the sublist that is supplying the arguments for the current iteration step
is the last sublist (in the case of terminating a \cd{{\Xtilde}:{\Xlbrace}} command)
or the last argument to that call to \cdf{format} (in the
case of terminating a \cd{{\Xtilde}:{\Xatsign}{\Xlbrace}} command).
Note furthermore that while \cd{{\Xtilde}{\Xcircumflex}} is equivalent
to \cd{{\Xtilde}\#{\Xcircumflex}} in all circumstances,
\cd{{\Xtilde}:{\Xcircumflex}} is \emph{not} equivalent
to \cd{{\Xtilde}:\#{\Xcircumflex}} because the latter terminates the entire iteration
if and only if no arguments remain for \emph{the current iteration step}
(as opposed to no arguments remaining for the entire iteration process).

Here are some examples of the differences in the
behaviors of \cd{{\Xtilde}{\Xcircumflex}}, \cd{{\Xtilde}:{\Xcircumflex}},
and \cd{{\Xtilde}:\#{\Xcircumflex}}.
\begin{lisp}
(format nil \\*
~~~~~~~~"{\Xtilde}:{\Xlbrace}/{\Xtilde}S{\Xtilde}{\Xcircumflex} ...{\Xtilde}{\Xrbrace}" \\*
~~~~~~~~'((hot dog) (hamburger) (ice cream) (french fries))) \\*
~\EV~"/HOT .../HAMBURGER/ICE .../FRENCH ..."
\end{lisp}
For each sublist, ``\cd{ ...}'' appears after the first word unless there are no
additional words.
\begin{lisp}
(format nil \\*
~~~~~~~~"{\Xtilde}:{\Xlbrace}/{\Xtilde}S{\Xtilde}:{\Xcircumflex} ...{\Xtilde}{\Xrbrace}" \\*
~~~~~~~~'((hot dog) (hamburger) (ice cream) (french fries))) \\*
~\EV~"/HOT .../HAMBURGER .../ICE .../FRENCH"
\end{lisp}
For each sublist, ``\cd{ ...}'' always appears after the first word, unless it is the
last sublist, in which case the entire iteration is terminated.
\begin{lisp}
(format nil \\*
~~~~~~~~"{\Xtilde}:{\Xlbrace}/{\Xtilde}S{\Xtilde}:\#{\Xcircumflex} ...{\Xtilde}{\Xrbrace}" \\*
~~~~~~~~'((hot dog) (hamburger) (ice cream) (french fries))) \\*
~\EV~"/HOT .../HAMBURGER"
\end{lisp}
For each sublist, ``\cd{ ...}'' appears after the first word, but if the sublist
has only one word then the entire iteration is terminated.
\end{new}

If \cd{{\Xtilde}{\Xcircumflex}} appears within a control string being processed
under the control of a \cd{{\Xtilde}?} directive, but not within
any \cd{{\Xtilde}{\Xlbrace}} or \cd{{\Xtilde}<} construct within that string,
then the string being
processed will be terminated, thereby ending processing
of the \cd{{\Xtilde}?} directive.  Processing then
continues within the string
containing the \cd{{\Xtilde}?} directive at the point following that directive.

If \cd{{\Xtilde}{\Xcircumflex}} appears within a \cd{{\Xtilde}{\Xlbracket}} or \cd{{\Xtilde}(} construct,
then all the commands up to the \cd{{\Xtilde}{\Xcircumflex}} are properly selected
or case-converted, the \cd{{\Xtilde}{\Xlbracket}} or \cd{{\Xtilde}(} processing is terminated,
and the outward search continues for a \cd{{\Xtilde}{\Xlbrace}} or \cd{{\Xtilde}<} construct
to be terminated.  For example:
\begin{lisp}
(setq tellstr "{\Xtilde}{\Xatsign}({\Xtilde}{\Xatsign}{\Xlbracket}{\Xtilde}R{\Xtilde}{\Xrbracket}{\Xtilde}{\Xcircumflex} {\Xtilde}A.{\Xtilde})") \\
(format {\false} tellstr 23) \EV\ "Twenty-three." \\
(format {\false} tellstr nil "losers") \EV\ "Losers." \\
(format {\false} tellstr 23 "losers") \EV\ "Twenty-three losers."
\end{lisp}

Here are some examples of the use of \cd{{\Xtilde}{\Xcircumflex}} within a \cd{{\Xtilde}<} construct.
\begin{lisp}
(format {\false} "{\Xtilde}15<{\Xtilde}S{\Xtilde};{\Xtilde}{\Xcircumflex}{\Xtilde}S{\Xtilde};{\Xtilde}{\Xcircumflex}{\Xtilde}S{\Xtilde}>" 'foo) \\
~~~~~~~~\EV\  "~~~~~~~~~~~~FOO" \\
(format {\false} "{\Xtilde}15<{\Xtilde}S{\Xtilde};{\Xtilde}{\Xcircumflex}{\Xtilde}S{\Xtilde};{\Xtilde}{\Xcircumflex}{\Xtilde}S{\Xtilde}>" 'foo 'bar) \\
~~~~~~~~\EV\  "FOO~~~~~~~~~BAR" \\
(format {\false} "{\Xtilde}15<{\Xtilde}S{\Xtilde};{\Xtilde}{\Xcircumflex}{\Xtilde}S{\Xtilde};{\Xtilde}{\Xcircumflex}{\Xtilde}S{\Xtilde}>" 'foo 'bar 'baz) \\
~~~~~~~~\EV\  "FOO~~~BAR~~~BAZ"
\end{lisp}
\end{flushdesc}

\begin{new}
X3J13 voted in June 1989 \issue{PRETTY-PRINT-INTERFACE}
to introduce user-defined directives in the form of the
\cd{{\Xtilde}/.../} directive.
See section~\ref{PPRINT-FORMAT-DIRECTIVES-SECTION} for details.
\end{new}

\begin{new}
The hairiest \cdf{format} control string I have ever seen in shown
in table~\ref{XAPPING-FORMAT-TABLE}.
It started innocently enough as part of the simulator for Connection Machine Lisp
\cite{CONNECTION-MACHINE-LISP,CMLISP-IMPLEMENTATION}; the \emph{xapping} data type,
defined by \cdf{defstruct}, needed a \cd{:print-function} option so that
xappings would print properly.  As this data type became more complicated, step by step,
so did the \cdf{format} control string.
\end{new}
\begin{table}[t]
\caption{Print Function for the Xapping Data Type}
\label{XAPPING-FORMAT-TABLE}
\begingroup
\small
\begin{lisp}
(defun print-xapping (xapping stream depth) \\
~~(declare (ignore depth)) \\
~~(format stream \\
~~~~~~~~~~;; Are you ready for this one? \\
~~~~~~~~~~"{\Xtilde}:[{\Xlbrace}{\Xtilde};[{\Xtilde}]{\Xtilde}:{\Xlbrace}{\Xtilde}S{\Xtilde}:[{\Xarrowright}{\Xtilde}S{\Xtilde};{\Xtilde}*{\Xtilde}]{\Xtilde}:{\Xcircumflex} {\Xtilde}{\Xrbrace}{\Xtilde}:[{\Xtilde}; {\Xtilde}]{\Xtilde} \\
~~~~~~~~~~~{\Xtilde}{\Xlbrace}{\Xtilde}S{\Xarrowright}{\Xtilde}{\Xcircumflex} {\Xtilde}{\Xrbrace}{\Xtilde}:[{\Xtilde}; {\Xtilde}]{\Xtilde}[{\Xtilde}*{\Xtilde};{\Xarrowright}{\Xtilde}S{\Xtilde};{\Xarrowright}{\Xtilde}*{\Xtilde}]{\Xtilde}:[{\Xrbrace}{\Xtilde};]{\Xtilde}]" \\
~~~~~~~~~~;; Is that clear? \\
~~~~~~~~~~(xectorp xapping) \\
~~~~~~~~~~(do ((vp (xectorp xapping)) \\
~~~~~~~~~~~~~~~(sp (finite-part-is-xetp xapping)) \\
~~~~~~~~~~~~~~~(d (xapping-domain xapping) (cdr d)) \\
~~~~~~~~~~~~~~~(r (xapping-range xapping) (cdr r)) \\
~~~~~~~~~~~~~~~(z '() (cons (list (if vp (car r) (car d)) \\
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~(or vp sp) \\
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~(car r)) \\
~~~~~~~~~~~~~~~~~~~~~~~~~~~~z))) \\
~~~~~~~~~~~~~~((null d) (reverse z))) \\
~~~~~~~~~~(and (xapping-domain xapping) \\
~~~~~~~~~~~~~~~(or (xapping-exceptions xapping) \\
~~~~~~~~~~~~~~~~~~~(xapping-infinite xapping))) \\
~~~~~~~~~~(xapping-exceptions xapping) \\
~~~~~~~~~~(and (xapping-exceptions xapping) \\
~~~~~~~~~~~~~~~(xapping-infinite xapping)) \\
~~~~~~~~~~(ecase (xapping-infinite xapping) \\
~~~~~~~~~~~~((nil) 0) \\
~~~~~~~~~~~~(:constant 1) \\
~~~~~~~~~~~~(:universal 2)) \\
~~~~~~~~~~(xapping-default xapping) \\
~~~~~~~~~~(xectorp xapping)))
\end{lisp}
\endgroup
See section~\ref{READTABLE-SECTION} for the \cdf{defstruct} definition of the \cdf{xapping} data
type, whose accessor functions are used in this code.
\end{table}

\begin{new}
See the description of \cdf{set-macro-character} for a discussion of xappings
and the \cdf{defstruct} definition.  Assume that the predicate \cdf{xectorp}
is true of a xapping if it is a xector, and that the predicate \cdf{finite-part-is-xetp}
is true if every value in the range is the same as its corresponding index.

Here is a blow-by-blow description of the parts of this format string:
\end{new}

\begin{flushleft}
\begin{tabular*}{\textwidth}{@{}l@{\extracolsep{\fill}}p{17pc}@{}}
\cd{{\Xtilde}:[{\Xlbrace}{\Xtilde};[{\Xtilde}]}&
Print ``\cd{[}'' for a xector, and ``\cd{{\Xlbrace}}'' otherwise. \\
\cd{{\Xtilde}:{\Xlbrace}{\Xtilde}S{\Xtilde}:[{\Xarrowright}{\Xtilde}S{\Xtilde};{\Xtilde}*{\Xtilde}]{\Xtilde}:{\Xcircumflex} {\Xtilde}{\Xrbrace}}& 
Given a list of lists, print the pairs.  Each sublist has three elements:
the index (or the value if we're printing a xector); a flag that is true for
either a xector or xet (in which case no arrow is printed);
and the value.  Note the use of \cd{{\Xtilde}:{\Xlbrace}} to iterate, and the use
of \cd{{\Xtilde}:{\Xcircumflex}} to avoid printing a separating space after the
final pair (or at all, if there are no pairs). \\
\cd{{\Xtilde}:[{\Xtilde}; {\Xtilde}]}&
If there were pairs and there are exceptions or an infinite part, print a separating space. \\
\cd{{\Xtilde}$\langle$\textrm{newline}$\rangle$}&
Do nothing.  This merely allows the format control string to be broken across two lines. \\
\cd{{\Xtilde}{\Xlbrace}{\Xtilde}S{\Xarrowright}{\Xtilde}{\Xcircumflex} {\Xtilde}{\Xrbrace}}&
Given a list of exception indices, print them.
Note the use of \cd{{\Xtilde}{\Xlbrace}} to iterate, and the use
of \cd{{\Xtilde}{\Xcircumflex}} to avoid printing a separating space after the
final exception (or at all, if there are no exceptions). \\
\cd{{\Xtilde}:[{\Xtilde}; {\Xtilde}]}&
If there were exceptions and there is an infinite part, print a separating space. \\
\cd{{\Xtilde}[{\Xtilde}*{\Xtilde};{\Xarrowright}{\Xtilde}S{\Xtilde};{\Xarrowright}{\Xtilde}*{\Xtilde}]}&
Use \cd{{\Xtilde}[} to choose one of three cases for printing the infinite part. \\
\cd{{\Xtilde}:[{\Xrbrace}{\Xtilde};]{\Xtilde}]}&
Print ``\cd{]}'' for a xector, and ``\cd{{\Xrbrace}}'' otherwise.
\end{tabular*}
\end{flushleft}

\section{Querying the User}
%\indexterm{querying the user}
%\indexterm{yes-or-no functions}

The following functions provide a convenient and consistent interface for
asking questions of the user.  Questions are printed and the answers are
read using the stream \cdf{*query-io*}, which normally is synonymous with
\cdf{*terminal-io*} but can be rebound to another stream for special
applications.

\begin{defun}[Function]
y-or-n-p &optional format-string &rest arguments

This predicate is for asking the user a question whose answer is either
``yes'' or ``no.''  It types out a message (if supplied), reads an answer
in some implementation-dependent manner (intended to be short and simple,
like reading a single character such as \cdf{Y} or \cdf{N}), and is
true if the answer was ``yes'' or false if the answer was ``no.''

If the \emph{format-string} argument is supplied and not {\false},
then a \cdf{fresh-line} operation is performed; then
a message is printed as if the \emph{format-string} and \emph{arguments}
were given to \cdf{format}.
Otherwise it is assumed that any message has already been printed
by other means.
If you want a question mark at the end of the message,
you must put it there yourself; \cdf{y-or-n-p} will not add it.
However, the message should not contain an explanatory note such
as \cd{(Y or N)}, because the nature of the interface provided for
\cdf{y-or-n-p} by a given implementation might not involve typing a
character on a keyboard; \cdf{y-or-n-p} will provide such a note
if appropriate.

All input and output are performed using the stream in the global
variable \cdf{*query-io*}.

Here are some examples of the use of \cdf{y-or-n-p}:
\begin{lisp}
(y-or-n-p "Produce listing file?") \\
(y-or-n-p "Cannot connect to network host {\Xtilde}S.  Retry?" host)
\end{lisp}

\cdf{y-or-n-p} should only be used for questions that the user knows
are coming or in situations where the user is known to be waiting for
a response of some kind.
If the user is unlikely to anticipate the question,
or if the consequences of the answer might be grave and irreparable,
then \cdf{y-or-n-p} should not be used because the user might type ahead
and thereby accidentally answer the question.
For such questions as ``Shall I delete all of your files?'' it is better to use
\cdf{yes-or-no-p}.
\end{defun}

\begin{defun}[Function]
yes-or-no-p &optional format-string &rest arguments

This predicate, like \cdf{y-or-n-p}, is for asking the user a question
whose answer is either ``yes'' or ``no.''  It types out a message (if
supplied), attracts the user's attention (for example, by ringing
the terminal's bell), and reads a reply in some
implementation-dependent manner.  It is intended that the reply require
the user to take more action than just a single keystroke, such as typing
the full word \cdf{yes} or \cdf{no} followed by a newline.

If the \emph{format-string} argument is supplied and not {\false},
then a \cdf{fresh-line} operation is performed; then
a message is printed as if the \emph{format-string} and \emph{arguments}
were given to \cdf{format}.
Otherwise it is assumed that any message has already been printed
by other means.
If you want a question mark at the end of the message,
you must put it there yourself; \cdf{yes-or-no-p} will not add it.
However, the message should not contain an explanatory note such
as \cd{(Yes or No)} because the nature of the interface provided for
\cdf{yes-or-no-p} by a given implementation might not involve typing the
reply on a keyboard; \cdf{yes-or-no-p} will provide such a note
if appropriate.

All input and output are performed using the stream in the global
variable \cdf{*query-io*}.

To allow the user to answer a yes-or-no question with a single
character, use \cdf{y-or-n-p}.  \cdf{yes-or-no-p} should be
used for unanticipated or momentous questions;
this is why it attracts attention
and why it requires a multiple-action sequence to answer it.
\end{defun}

%\else %RUSSIAN


% \begin{table}[t]
% \caption{Синтаксис чисел}
% \label{NUMBER-SYNTAX-TABLE}
% \tabbingsep=0pt
% \normalsize
% \begin{tabbing}
% \emph{number} ::= \emph{integer} {\Mor} \emph{ratio} {\Mor} \emph{floating-point-number} \\
% \emph{integer} ::= \Mopt{\emph{sign}} \Mplus{\emph{digit}} \Mopt{\emph{decimal-point}} \\
% \emph{ratio} ::= \Mopt{\emph{sign}} \Mplus{\emph{digit}} \cdf{/} \Mplus{\emph{digit}} \\
% \emph{floating-point-number} ::=\= \Mopt{\emph{sign}} \Mstar{\emph{digit}} \emph{decimal-point} \Mplus{\emph{digit}} \Mopt{\emph{exponent}} \\
% \>{\Mor} \'\Mopt{\emph{sign}} \Mplus{\emph{digit}} \Mopt{\emph{decimal-point}
% \Mstar{\emph{digit}}} \emph{exponent} \\ \emph{sign} ::= \cdf{+} {\Mor} \cdf{-} \\
% \emph{decimal-point} ::= \cd{.} \\
% \emph{digit} ::= \cd{0} {\Mor} \cd{1} {\Mor} \cd{2} {\Mor} \cd{3} {\Mor} \cd{4}
%          {\Mor} \cd{5} {\Mor} \cd{6} {\Mor} \cd{7} {\Mor} \cd{8} {\Mor} \cd{9} \\
% \emph{exponent} ::= \emph{exponent-marker} \Mopt{\emph{sign}} \Mplus{\emph{digit}} \\
% \emph{exponent-marker} ::= \cdf{e} {\Mor} \cdf{s} {\Mor} \cdf{f} {\Mor} \cdf{d} {\Mor} \cdf{l}
%                    {\Mor} \cdf{E} {\Mor} \cdf{S} {\Mor} \cdf{F} {\Mor} \cdf{D} {\Mor} \cdf{L}
% \end{tabbing}
% \end{table}

% \begin{table}
% \caption{Свойства стандартных символов}
% \label{Standard-Readtable-Attributes-Table}

% \begin{tabular*}{\textwidth}{@{\extracolsep{\fill}}l@{\extracolsep{\fill}}lllll@{}}
% \cd{!}&\emph{алфавитный}&$\langle$page$\rangle$&\emph{недопустимый}&$\langle$backspace$\rangle$&\emph{недопустимый} \\
% \cd{"}&\emph{алфавитный} *&$\langle$return$\rangle$&\emph{недопустимый} *&$\langle$tab$\rangle$&\emph{недопустимый} * \\
% \cd{\#}&\emph{алфавитный} *&$\langle$space$\rangle$&\emph{недопустимый} *&$\langle$newline$\rangle$&\emph{недопустимый} * \\
% \cd{\$}&\emph{алфавитный}&$\langle$rubout$\rangle$&\emph{недопустимый}&$\langle$linefeed$\rangle$&\emph{недопустимый} * \\
% \cd{\%}&\emph{алфавитный}&\cd{.}&\multicolumn{3}{l}{\emph{алфавитный},
%   \emph{точка}, \emph{разделитель десятичной части}}\\
% \cd{\&}&\emph{алфавитный}&\cdf{+}&\multicolumn{3}{l}{\emph{алфавитный},
%   \emph{знак плюс}} \\
% \cd{'}&\emph{алфавитный} *&\cdf{-}&\multicolumn{3}{l}{\emph{алфавитный},
%   \emph{знак минус}} \\
% \cd{(}&\emph{алфавитный} *&\cdf{*}&\emph{алфавитный} \\
% \cd{)}&\emph{алфавитный} *&\cdf{/}&\multicolumn{3}{l}{\emph{алфавитный},
%   \emph{маркер дроби}} \\
% \cd{,}&\emph{алфавитный} *&\cd{{\Xatsign}}&\emph{алфавитный} \\
% \cd{0}&\emph{алфавитно-цифровой}&\cdf{A}, \cdf{a}&\emph{алфавитно-цифровой} \\
% \cd{1}&\emph{алфавитно-цифровой}&\cdf{B}, \cdf{b}&\emph{алфавитно-цифровой} \\
% \cd{2}&\emph{алфавитно-цифровой}&\cdf{C}, \cdf{c}&\emph{алфавитно-цифровой} \\
% \cd{3}&\emph{алфавитно-цифровой}&\cdf{D}, \cdf{d}&\multicolumn{3}{l}{\emph{алфавитно-цифровой}, \emph{маркер экспоненты
%     для двойного с плавающей точкой}} \\
% \cd{4}&\emph{алфавитно-цифровой}&\cdf{E}, \cdf{e}&\multicolumn{3}{l}{\emph{алфавитно-цифровой}, \emph{маркер экспоненты
%     для числа с плавающей точкой}} \\
% \cd{5}&\emph{алфавитно-цифровой}&\cdf{F}, \cdf{f}&\multicolumn{3}{l}{\emph{алфавитно-цифровой}, \emph{маркер экспоненты
%     для одинарного с плавающей точкой}} \\
% \cd{6}&\emph{алфавитно-цифровой}&\cdf{G}, \cdf{g}&\emph{алфавитно-цифровой} \\
% \cd{7}&\emph{алфавитно-цифровой}&\cdf{H}, \cdf{h}&\emph{алфавитно-цифровой} \\
% \cd{8}&\emph{алфавитно-цифровой}&\cdf{I}, \cdf{i}&\emph{алфавитно-цифровой} \\
% \cd{9}&\emph{алфавитно-цифровой}&\cdf{J}, \cdf{j}&\emph{алфавитно-цифровой} \\
% \cd{:}&\emph{package marker}~~~~~~&\cdf{K}, \cdf{k}&\emph{алфавитно-цифровой} \\
% \cd{;}&\emph{алфавитный} *&\cdf{L}, \cdf{l}&\multicolumn{3}{l}{\emph{алфавитно-цифровой}, \emph{маркер экспоненты
%     для длинного с плавающей точкой}} \\
% \cdf{<}&\emph{алфавитный}&\cdf{M}, \cdf{m}&\emph{алфавитно-цифровой} \\
% \cdf{=}&\emph{алфавитный}&\cdf{N}, \cdf{n}&\emph{алфавитно-цифровой} \\
% \cdf{>}&\emph{алфавитный}&\cdf{O}, \cdf{o}&\emph{алфавитно-цифровой} \\
% \cd{?}&\emph{алфавитный}&\cdf{P}, \cdf{p}&\emph{алфавитно-цифровой} \\
% \cd{{\Xlbracket}}&\emph{алфавитный}&\cdf{Q}, \cdf{q}&\emph{алфавитно-цифровой} \\
% \cd{{\Xbackslash}}&\emph{алфавитный} *&\cdf{R}, \cdf{r}&\emph{алфавитно-цифровой} \\
% \cd{{\Xrbracket}}&\emph{алфавитный}&\cdf{S},
% \cdf{s}&\multicolumn{3}{l}{\emph{алфавитно-цифровой}, \emph{маркер экспоненты
%     для короткого с плавающей точкой}} \\
% \cd{{\Xcircumflex}}&\emph{алфавитный}&\cdf{T}, \cdf{t}&\emph{алфавитно-цифровой} \\
% \cd{{\Xunderscore}}&\emph{алфавитный}&\cdf{U}, \cdf{u}&\emph{алфавитно-цифровой} \\
% \cd{{\Xbq}}&\emph{алфавитный} *&\cdf{V}, \cdf{v}&\emph{алфавитно-цифровой} \\
% \cd{{\Xlbrace}}&\emph{алфавитный}&\cdf{W}, \cdf{w}&\emph{алфавитно-цифровой} \\
% \cd{|}&\emph{алфавитный} *&\cdf{X}, \cdf{x}&\emph{алфавитно-цифровой} \\
% \cd{{\Xrbrace}}&\emph{алфавитный}&\cdf{Y}, \cdf{y}&\emph{алфавитно-цифровой} \\
% \cd{{\Xtilde}}&\emph{алфавитный}&\cdf{Z}, \cdf{z}&\emph{алфавитно-цифровой} \\
% \end{tabular*}

% \vfill
% \begin{footnotesize}
% \noindent
% These interpretations apply only to characters whose
% syntactic type is \emph{constituent}.  Entries marked
% with an asterisk are normally shadowed because the characters
% are of syntactic type
% \emph{whitespace}, \emph{macro}, \emph{single escape}, or \emph{multiple escape}.
% An \emph{alphadigit} character is interpreted as a
% digit if it is a valid digit in the radix specified by {\small \cd{*read-base*}};
% otherwise it is alphabetic.
% Characters with an \emph{illegal} attribute can never appear in
% a token except under the control of an escape character.
% \end{footnotesize}
% \end{table}

% \begin{table}
% \caption{Стандартный синтаксис для макросимвола \#}
% \label{Standard-Sharp-Macro-Definitions-Table}

% \begin{tabular*}{\textwidth}{@{\extracolsep{\fill}}l@{\extracolsep{\fill}}lll@{}}
% \cd{\#!}&\emph{неопределен} *&\cd{\#}$\langle$backspace$\rangle$&\emph{сигнализирует ошибку} \\
% \cd{\#"}&\emph{неопределен}&\cd{\#}$\langle$tab$\rangle$&\emph{сигнализирует ошибку} \\
% \cd{\#\#}&\emph{ссылка на \cd{\#=} метку}&\cd{\#}$\langle$newline$\rangle$&\emph{сигнализирует ошибку} \\
% \cd{\#\$}&\emph{неопределен}&\cd{\#}$\langle$linefeed$\rangle$&\emph{сигнализирует ошибку} \\
% \cd{\#\%}&\emph{неопределен}&\cd{\#}$\langle$page$\rangle$&\emph{сигнализирует ошибку} \\
% \cd{\#\&}&\emph{неопределен}&\cd{\#}$\langle$return$\rangle$&\emph{сигнализирует ошибку} \\
% \cd{\#'}&\emph{аббревиатуры для \cdf{function}}&\cd{\#}$\langle$space$\rangle$&\emph{сигнализирует ошибку} \\
% \cd{\#(}&\emph{простой вектор}&\cd{\#+}&\emph{условное вычисление во время чтения} \\
% \cd{\#)}&\emph{сигнализирует ошибку}&\cd{\#-}&\emph{условное вычисление во время чтения} \\
% \cd{\#*}&\emph{битовый вектор}&\cd{\#.}&\emph{вычисление во время чтения} \\
% \cd{\#,}&\emph{вычисление во время загрузки}&\cd{\#/}&\emph{неопределен} \\
% \cd{\#0}&\emph{используется для инфиксных аргументов}~~~~~~&\cd{\#A}, \cd{\#a}&\emph{массив} \\
% \cd{\#1}&\emph{используется для инфиксных аргументов}&\cd{\#B}, \cd{\#b}&\emph{двоичное число} \\
% \cd{\#2}&\emph{используется для инфиксных аргументов}&\cd{\#C}, \cd{\#c}&\emph{комплексное число} \\
% \cd{\#3}&\emph{используется для инфиксных аргументов}&\cd{\#D}, \cd{\#d}&\emph{неопределен} \\
% \cd{\#4}&\emph{используется для инфиксных аргументов}&\cd{\#E}, \cd{\#e}&\emph{неопределен} \\
% \cd{\#5}&\emph{используется для инфиксных аргументов}&\cd{\#F}, \cd{\#f}&\emph{неопределен} \\
% \cd{\#6}&\emph{используется для инфиксных аргументов}&\cd{\#G}, \cd{\#g}&\emph{неопределен} \\
% \cd{\#7}&\emph{используется для инфиксных аргументов}&\cd{\#H}, \cd{\#h}&\emph{неопределен} \\
% \cd{\#8}&\emph{используется для инфиксных аргументов}&\cd{\#I}, \cd{\#i}&\emph{неопределен} \\
% \cd{\#9}&\emph{используется для инфиксных аргументов}&\cd{\#J}, \cd{\#j}&\emph{неопределен} \\
% \cd{\#:}&\emph{uninterned symbol}&\cd{\#K}, \cd{\#k}&\emph{неопределен} \\
% \cd{\#;}&\emph{неопределен}&\cd{\#L}, \cd{\#l}&\emph{неопределен} \\
% \cd{\#<}&\emph{сигнализирует ошибку}&\cd{\#M}, \cd{\#m}&\emph{неопределен} \\
% \cd{\#=}&\emph{метка следующего объекта}&\cd{\#N}, \cd{\#n}&\emph{неопределен} \\
% \cd{\#>}&\emph{неопределен}&\cd{\#O}, \cd{\#o}&\emph{восьмеричное число} \\
% \cd{\#?}&\emph{неопределен} *&\cd{\#P}, \cd{\#p}&\emph{имя файла} \\
% \cd{\#{\Xatsign}}&\emph{неопределен}&\cd{\#Q}, \cd{\#q}&\emph{неопределен} \\
% \cd{\#{\Xlbracket}}&\emph{неопределен} *&\cd{\#R}, \cd{\#r}&\emph{число с основанием} \\
% \cd{\#{\Xbackslash}}&\emph{символьный объект}&\cd{\#S}, \cd{\#s}&\emph{структура} \\
% \cd{\#{\Xrbracket}}&\emph{неопределен} *&\cd{\#T}, \cd{\#t}&\emph{неопределен} \\
% \cd{\#{\Xcircumflex}}&\emph{неопределен}&\cd{\#U}, \cd{\#u}&\emph{неопределен} \\
% \cd{\#{\Xunderscore}}&\emph{неопределен}&\cd{\#V}, \cd{\#v}&\emph{неопределен} \\
% \cd{\#{\Xbq}}&\emph{неопределен}&\cd{\#W}, \cd{\#w}&\emph{неопределен} \\
% \cd{\#{\Xlbrace}}&\emph{неопределен} *&\cd{\#X},
% \cd{\#x}&\emph{шестнадцатиричное число} \\
% \cd{\#|}&\emph{многострочный комментарий}&\cd{\#Y}, \cd{\#y}&\emph{неопределен} \\
% \cd{\#{\Xrbrace}}&\emph{неопределен} *&\cd{\#Z}, \cd{\#z}&\emph{неопределен} \\
% \cd{\#{\Xtilde}}&\emph{неопределен}&\cd{\#}$\langle$rubout$\rangle$&\emph{неопределен}
% \end{tabular*}

% \vfill
% \begin{small}
% \noindent
% Комбинации обозначенные звёздочкой зарезервированы для использования
% пользователем. Такие комбинации никогда не будут использованы стандартом Common
% Lisp'а. 
% \end{small}
% \end{table}

% \begin{table}[t]
% \caption{Основные связывания для переменных для ввода/вывода}
% \label{WITH-STANDARD-IO-SYNTAX-TABLE}
% \begin{flushleft}
% \cf
% \begin{tabular}{@{}ll@{}}
% \textrm{Переменная}&\textrm{Значение} \\
% \hlinesp
%       {*package*}                      &     \textrm{пакет \cdf{common-lisp-user}} \\
%       {*print-array*}                  &     t \\
%       {*print-base*}                   &     10 \\
%       {*print-case*}                   &     :upcase \\
%       {*print-circle*}                 &     nil \\
%       {*print-escape*}                 &     t \\
%       {*print-gensym*}                 &     t \\
%       {*print-length*}                 &     nil \\
%       {*print-level*}                  &     nil \\
%       {*print-lines*}                  &     nil \textrm{*} \\
%       {*print-miser-width*}            &     nil \textrm{*} \\
%       {*print-pprint-dispatch*}        &     nil \textrm{*} \\
%       {*print-pretty*}                 &     nil \\
%       {*print-radix*}                  &     nil \\
%       {*print-readably*}               &     t \\
%       {*print-right-margin*}           &     nil \textrm{*} \\
%       {*read-base*}                    &     10 \\
%       {*read-default-float-format*}    &     single-float \\
%       {*read-eval*}                    &     t \\
%       {*read-suppress*}                &     nil \\
%       {*readtable*}                    &     \textrm{стандартная таблица с макросимволами}
% \end{tabular}
% \end{flushleft}
% * X3J13 voted in June 1989 \issue{PRETTY-PRINT-INTERFACE}
% to introduce the printer control variables
% \cdf{*print-right-margin*},
% \cdf{*print-miser-width*},
% \cdf{*print-lines*},
% and \cdf{*print-pprint-dispatch*}
% (see section~\ref{PPRINT-VARIABLES-SECTION})
% but did not specify the values to which \cdf{with-standard-io-syntax}
% should bind them.  I recommend that all four should be bound to \cdf{nil}.
% \end{table}