Permalink
Fetching contributors…
Cannot retrieve contributors at this time
1440 lines (1238 sloc) 46.5 KB
% Copyright (C) 2008, 2009, 2010, 2011, 2012, 2013, 2014 Bert Burgemeister
%
% Permission is granted to copy, distribute and/or modify this
% document under the terms of the GNU Free Documentation License,
% Version 1.2; with no Invariant Sections, no Front-Cover Texts and
% no Back-Cover Texts. For details see file COPYING.
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Input/Output}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Predicates}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{LIST}{1cm}
\IT{\arrGOO{(\FU*{STREAMP} \VAR{ foo})\\
(\FU*{PATHNAMEP} \VAR{ foo})\\
(\FU*{READTABLEP} \VAR{ foo})}{.}}
{
\retval{\T} if \VAR{foo} is of indicated type.
}
\IT{\arrGOO{(\FU*{INPUT-STREAM-P} \VAR{ stream})\\
(\FU*{OUTPUT-STREAM-P} \VAR{ stream})\\
(\FU*{INTERACTIVE-STREAM-P} \VAR{ stream})\\
(\FU*{OPEN-STREAM-P} \VAR{ stream})}{.}}
{
Return \retval{\T} if \VAR{stream} is for input, for output,
interactive, or open, respectively.
}
\IT{(\FU*{PATHNAME-MATCH-P} \VAR{path} \VAR{wildcard})}
{
\retval{\T} if \VAR{path} matches \VAR{wildcard}.
}
\IT{(\FU*{WILD-PATHNAME-P} \VAR{path}
\OP{\Goo{\kwd{:host}\XOR
\kwd{:device}\XOR
\kwd{:directory}\XOR
\kwd{:name}\XOR
\kwd{:type}\XOR
\kwd{:version}\XOR\NIL}})}
{
Return \retval{\T} if indicated component in \VAR{path} is
wildcard. (\NIL\ indicates any component.)
}
\end{LIST}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Reader}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{LIST}{1cm}
\IT{(\xorGOO{\FU*{Y-OR-N-P}\\
\FU*{YES-OR-NO-P}}{\}} \Op{\VAR{control} \OPn{\VAR{arg}}})}
{
Ask user a question and return \retval{\T} or \retval{\NIL}
depending on their answer. See page \pageref{section:Format},
\FU{format}, for \VAR{control} and \VAR{arg}s.
}
\IT{(\MC*{WITH-STANDARD-IO-SYNTAX} \PROGN{\VAR{form}})}
{
Evaluate \VAR{form}s with standard behaviour of reader and
printer. Return \retval{values of \VAR{form}s}.
}
\IT{(\xorGOO{\FU*{READ}\\
\FU*{READ-PRESERVING-WHITESPACE}}{\}}
\OP{\DES{\VAR{stream}}\DF{\V{\A standard-input\A}} % standard-input not explicitly in standard
\OP{\VAR{eof-err}\DF{\T}
\Op{\VAR{eof-val}\DF{\NIL} \Op{\VAR{recursive}\DF{\NIL}}}}})}
{
Read printed representation of \retval{object}.
}
\IT{(\FU*{READ-FROM-STRING} \VAR{string}
\OP{\VAR{eof-error}\DF{\T}
\OP{\VAR{eof-val}\DF{\NIL}
\OP{\orGOO{%
\kwd{:start}\VAR{ start}\DF{\LIT{0}}\\
\kwd{:end}\VAR{ end}\DF{\NIL}\\
\kwd{:preserve-whitespace}\VAR{ bool}\DF{\NIL}}{\}}}}})}
{
Return \retval{object} read from string and zero-indexed \retvalii{position} of
next character.
}
\IT{(\FU*{READ-DELIMITED-LIST} \VAR{char}
\OP{\DES{\VAR{stream}}\DF{\V{\A standard-input\A}}
\Op{\VAR{recursive}\DF{\NIL}}})}
{
Continue reading until encountering \VAR{char}. Return \retval{list}
of objects read. Signal error if no \VAR{char} is found in stream.
}
\IT{(\FU*{READ-CHAR} \OP{\DES{\VAR{stream}}\DF{\V{\A standard-input\A}}
\OP{\VAR{eof-err}\DF{\T} \Op{\VAR{eof-val}\DF{\NIL}
\Op{\VAR{recursive}\DF{\NIL}}}}})}
{
Return \retval{next character} from \VAR{stream}.
}
\IT{(\FU*{READ-CHAR-NO-HANG}
\OP{\DES{\VAR{stream}}\DF{\V{\A standard-input\A}}
\OP{\VAR{eof-error}\DF{\T} \Op{\VAR{eof-val}\DF{\NIL}
\Op{\VAR{recursive}\DF{\NIL}}}}})}
{
\retval{Next character} from \VAR{stream} or \retval{\NIL} if none
is available.
}
\IT{(\FU*{PEEK-CHAR}
\OP{\VAR{mode}\DF{\NIL} \OP{\DES{\VAR{stream}}\DF{\V{\A standard-input\A}}
\OP{\VAR{eof-error}\DF{\T} \Op{\VAR{eof-val}\DF{\NIL}
\Op{\VAR{recursive}\DF{\NIL}}}}}})}
{
Next, or if \VAR{mode} is \T, next non-whitespace
\retval{character}, or if \VAR{mode} is a character, \retval{next instance}
of it, from \VAR{stream} without removing it there.
}
\IT{(\FU*{UNREAD-CHAR} \VAR{character}
\Op{\DES{\VAR{stream}}\DF{\V{\A standard-input\A}}})}
{
Put last \FU{read-char}ed \VAR{character} back into \VAR{stream}; return
\retval{\NIL}.
}
\IT{(\FU*{READ-BYTE} \DES{\VAR{stream}} \OP{\VAR{eof-err}\DF{\T}
\Op{\VAR{eof-val}\DF{\NIL}}})}
{
Read \retval{next byte} from binary \VAR{stream}.
}
\IT{(\FU*{READ-LINE} \OP{\DES{\VAR{stream}}\DF{\V{\A standard-input\A}}
\OP{\VAR{eof-err}\DF{\T} \Op{\VAR{eof-val}\DF{\NIL}
\Op{\VAR{recursive}\DF{\NIL}}}}})}
{
Return a \retval{line of text} from \VAR{stream} and
\retvalii{\T} if line has been ended by end of file.
}
\IT{(\FU*{READ-SEQUENCE} \DES{\VAR{sequence}} \DES{\VAR{stream}}
\Op{\kwd{:start} \VAR{start}\DF{\LIT{0}}}\Op{\kwd{:end}
\VAR{end}\DF{\NIL}})}
{
Replace elements of \VAR{sequence} between \VAR{start} and \VAR{end}
with elements from binary or character \VAR{stream}. Return
\retval{index} of \VAR{sequence}'s first unmodified element.
}
\IT{(\FU*{READTABLE-CASE} \VAR{readtable})\DF{\kwd{:upcase}}}
{
\retval{Case sensitivity attribute} (one of \kwd{:upcase},
\kwd{:downcase}, \kwd{:preserve}, \kwd{:invert}) of
\VAR{readtable}. \kwd{setf}able.
}
\IT{(\FU*{COPY-READTABLE} \OP{\VAR{from-readtable}\DF{\V{\A readtable\A}}
\Op{\DES{\VAR{to-readtable}}\DF{\NIL}}})}
{
Return \retval{copy of \VAR{from-readtable}}.
}
\IT{(\FU*{SET-SYNTAX-FROM-CHAR} \VAR{to-char} \VAR{from-char}
\OP{\DES{\VAR{to-readtable}}\DF{\V{\A readtable\A}}
\Op{\VAR{from-readtable}\DF{standard readtable}}})}
{
Copy syntax of \VAR{from-char} to \VAR{to-readtable}. Return \retval{\T}.
}
\IT{\V{\A readtable\A}}
{\index{*READTABLE*@\A READTABLE\A}
Current readtable.
}
\IT{\V{\A read-base\A}\DF{\LIT{10}}}
{\index{*READ-BASE*@\A READ-BASE\A}
Radix for reading \kwd{integer}s and \kwd{ratio}s.
}
\IT{\V{\A read-default-float-format\A}\DF{\kwd{single-float}}}
{\index{*READ-DEFAULT-FLOAT-FORMAT*@\A READ-DEFAULT-FLOAT-FORMAT\A}
Floating point format to use when not indicated in the number read.
}
\IT{\V{\A read-suppress\A}\DF{\NIL}}
{\index{*READ-SUPPRESS*@\A READ-SUPPRESS\A}
If \T, reader is syntactically more tolerant.
}
\IT{(\FU*{SET-MACRO-CHARACTER} \VAR{char} \VAR{function}
\OP{\VAR{non-term-p}\DF{\NIL}
\Op{\DES{\VAR{rt}}\DF{\V{\A readtable\A}}}})}
{
Make \VAR{char} a macro character associated with
\VAR{function} of stream and \VAR{char}. Return \retval{\T}.
}
\IT{(\FU*{GET-MACRO-CHARACTER} \VAR{char}
\Op{\VAR{rt}\DF{\V{\A readtable\A}}})}
{
\retval{Reader macro function} associated with \VAR{char}, and
\retvalii{\T} if \VAR{char} is a non-terminating macro character.
}
\IT{(\FU*{MAKE-DISPATCH-MACRO-CHARACTER} \VAR{char}
\OP{\VAR{non-term-p}\DF{\NIL}
\Op{\VAR{rt}\DF{\V{\A readtable\A}}}})}
{
Make \VAR{char} a dispatching macro character. Return \retval{\T}.
}
\IT{(\FU*{SET-DISPATCH-MACRO-CHARACTER} \VAR{char} \VAR{sub-char}
\VAR{function}
\Op{\DES{\VAR{rt}}\DF{\V{\A readtable\A}}})}
{
Make \VAR{function} of stream, \VAR{n}, \VAR{sub-char} a dispatch
function of \VAR{char} followed by \VAR{n}, followed by
\VAR{sub-char}. Return \retval{\T}.
}
\IT{(\FU*{GET-DISPATCH-MACRO-CHARACTER} \VAR{char} \VAR{sub-char}
\Op{\VAR{rt}\DF{\V{\A readtable\A}}})}
{
\retval{Dispatch function} associated with \VAR{char} followed by
\VAR{sub-char}.
}
\end{LIST}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Character Syntax}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{LIST}{1cm}
\IT{\arrGOO{%
\KWD{\#\boldmath$|$ }\OPn{\VAR{multi-line-comment}}\KWD{ \boldmath$|$\#}\\
\KWD*{; }\OPn{\VAR{one-line-comment}}}{.}}
{\index{\#{$"|$} {$"|$}\#}
Comments. There are stylistic conventions:
}
\begin{LIST}{.5cm}
\IT{\KWD{;;;;} \VAR{title}\qquad\qquad}
{Short title for a block of code.}
\IT{\KWD{;;;} \VAR{intro}\qquad\qquad}
{Description before a block of code.}
\IT{\KWD{;;} \VAR{state}\qquad\qquad}
{State of program or of following code.}
\IT{\arrGOO{%
\KWD{;}\VAR{explanation}\\
\KWD{;}\VAR{ continuation}}{.}}
{Regarding line on which it appears.}
\end{LIST}
\IT{\KWD*{(}\OPn{\VAR{foo}}\Op{ \KWD*{.} \VAR{bar}\DF{\NIL}}\KWD*{)}}
{
List of \VAR{foo}s with the terminating cdr \VAR{bar}.
}
\IT{\KWD{"}\qquad\qquad}
{\index{""}
Begin and end of a string.
}
\IT{\KWD*{'}\VAR{foo}\quad\qquad}
{
(\SO*{quote} \VAR{foo}); \VAR{foo} unevaluated.
}
\IT{\KWD{\char18}(\Op{\VAR{foo}} \Op{\KWD*{,}\VAR{bar}} \Op{\KWD{,@}\VAR{baz}}
\Op{\KWD*{,.}\DES{\VAR{quux}}} \Op{\VAR{bing}})}
{\index{,"@}\index{`@\char18}
Backquote. \SO{quote} \VAR{foo} and \VAR{bing}; evaluate \VAR{bar}
and splice the lists \VAR{baz} and \VAR{quux} into their
elements. When nested, outermost commas inside the innermost
backquote expression belong to this backquote.
}
\IT{\KWD{\#\boldmath{$\backslash$}}\VAR{c}}
{
(\FU*{character} \LIT{"}\VAR{c}\LIT{"}), the character \VAR{c}.
}
\index{\#@\#$\backslash$}%
\IT{\KWD*{\#b}\VAR{n}; \KWD*{\#o}\VAR{n}; \VAR{n}\kwd{.};
\KWD*{\#x}\VAR{n}; \KWD{\#}\VAR{r}\KWD{R}\VAR{n}}
{\index{\#R}%
Integer of radix 2, 8, 10, 16, or \VAR{r}; $2\le r \le 36$.
}
\IT{\VAR{n}\kwd*{/}\VAR{d}\quad\qquad}
{
The \kwd*{ratio} $\frac{n}{d}$.
}
\IT{\GOO{\Op{\VAR{m}}\kwd{.}\VAR{n}%
\OP{\Goo{\KWD{S}\XOR\KWD{F}\XOR\KWD{D}\XOR\KWD{L}\XOR\KWD{E}}%
\VAR{x}\DF{\KWD{E}\LIT{0}}}%
\XOR%
\VAR{m}\OP{\kwd{.}\Op{\VAR{n}}}%
\Goo{\KWD{S}\XOR\KWD{F}\XOR\KWD{D}\XOR\KWD{L}\XOR\KWD{E}}\VAR{x}}}
{
$m.n\cdot10^x$ as \kwd*{short-float}, \kwd*{single-float},
\kwd*{double-float}, \kwd*{long-float}, or the type from \kwd{\A
read-default-float-format\A}.
}
\IT{\KWD*{\#C(}\VAR{a b}\kwd{)}\qquad\qquad}
{
(\FU*{complex} \VAR{a} \VAR{b}), the complex number
$\VAR{a}+\VAR{b}\text{i}$.
}
\IT{\KWD*{\#'}\VAR{foo}\qquad\qquad\qquad}
{
(\SO*{function} \VAR{foo}); the function named \VAR{foo}.
}
\IT{\KWD{\#}\VAR{n}\KWD{A}\VAR{sequence}}
{\index{\#A}%
\VAR{n}-dimensional array.
}
\IT{\KWD{\#}\Op{\VAR{n}}\kwd{(}\OPn{\VAR{foo}}\kwd{)}}
{\index{\#(}%
Vector of some (or \VAR{n})
\VAR{foo}s filled with last \VAR{foo} if necessary.
}
\IT{\KWD{\#}\Op{\VAR{n}}\kwd{\A}\OPn{\VAR{b}}}
{\index{\#*@\#\A}%
Bit vector of some (or \VAR{n})
\VAR{b}s filled with last \VAR{b} if necessary.
}
\IT{\KWD*{\#S(}\VAR{type} \Goos{\VAR{slot} \VAR{value}}\kwd{)}}
{
Structure of \VAR{type}.
}
\IT{\KWD*{\#P}\VAR{string}\qquad\qquad}
{
A pathname.
}
\IT{\KWD*{\#:}\VAR{foo}\qquad\qquad\qquad}
{
Uninterned symbol \VAR{foo}.
}
\IT{\KWD*{\#.}\VAR{form}\qquad\qquad}
{
Read-time value of \VAR{form}.
}
\IT{\V{\A read-eval\A}\DF{\T}}
{\index{*READ-EVAL*@\A READ-EVAL\A}
If \NIL, a \kwd{reader-error} is signalled at \kwd{\#.}.
}
\IT{\KWD{\#}\VAR{integer}\kwd{=} \VAR{foo}\qquad}
{\index{\#=}%
Give \VAR{foo} the label \VAR{integer}.
}
\IT{\KWD{\#}\VAR{integer}\kwd{\#}\qquad\qquad}
{\index{\#\#}%
Object labelled \VAR{integer}.
}
\IT{\KWD{\#\boldmath$<$}\qquad\qquad\qquad}
{\index{\#<@\#$<$}%
Have the reader signal \kwd{reader-error}.
}
\IT{\arrGOO{\KWD*{\#+}\VAR{feature } \VAR{when-feature}\\
\KWD*{\#--}\VAR{feature } \VAR{unless-feature}}{.}}
{
Means \VAR{when-feature} if \VAR{feature} is \T; means
\VAR{unless-feature} if \VAR{feature} is \NIL. \VAR{feature} is a
symbol from \V{\A features\A}, or (\Goo{\kwd*{AND}\XOR\kwd*{OR}}
\OPn{\VAR{feature}}), or (\kwd*{NOT} \VAR{feature}).
}
\IT{\V{\A features\A}}
{\index{*FEATURES*@\A FEATURES\A}
List of symbols denoting implementation-dependent features.
}
\IT{\kwd{\boldmath$|$}\OPn{\VAR{c}}\kwd{\boldmath$|$};
\kwd{\boldmath$\backslash$}\VAR{c}}
{
\index{{$"|$} {$"|$}}%
Treat arbitrary character(s) \VAR{c} as alphabetic preserving case.
}
\index{\@{$\backslash$}}%
\end{LIST}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Printer}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{LIST}{1cm}
\IT{(\xorGOO{\FU*{PRIN1}\\
\FU*{PRINT}\\
\FU*{PPRINT}\\
\FU*{PRINC}}{\}}
\VAR{foo} \Op{\DES{\VAR{stream}}\DF{\V{\A standard-output\A}}})}
{
Print \VAR{foo} to \VAR{stream} \FU{read}ably,
\FU{read}ably between a newline and a space,
\FU{read}ably after a newline, or human-readably without any extra
characters, respectively. \FU{prin1}, \FU{print} and \FU{princ}
return \retval{\VAR{foo}}.
}
\IT{\arrGOO{(\FU*{PRIN1-TO-STRING} \VAR{ foo})\\
(\FU*{PRINC-TO-STRING} \VAR{ foo})}{.}}
{
Print \VAR{foo} to \retval{\VAR{string}} \FU{read}ably or
human-readably, respectively.
}
\IT{(\GFU*{PRINT-OBJECT} \VAR{object} \DES{\VAR{stream}})}
{
Print \retval{\VAR{object}} to \VAR{stream}. Called by the Lisp
printer.
}
\IT{(\MC*{PRINT-UNREADABLE-OBJECT} (\VAR{foo} \DES{\VAR{stream}}
\orGOO{\kwd{:type } \VAR{bool}\DF{\NIL}\\
\kwd{:identity } \VAR{bool}\DF{\NIL}}{\}})
\PROGN{\VAR{form}})}
{
Enclosed in \kwd{\#\boldmath$<$} and \kwd{\boldmath$>$}, print
\VAR{foo} by means of \VAR{form}s to \VAR{stream}. Return \retval{\NIL}.
}
\IT{(\FU*{TERPRI} \Op{\DES{\VAR{stream}}\DF{\V{\A standard-output\A}}})}
{
Output a newline to \VAR{stream}. Return \retval{\NIL}.
}
\IT{(\FU*{FRESH-LINE}
\Op{\DES{\VAR{stream}}\DF{\V{\A standard-output\A}}})}
{
Output a newline to \VAR{stream} and return \retval{\T} unless
\VAR{stream} is already at the start of a line.
}
\IT{(\FU*{WRITE-CHAR} \VAR{char}
\Op{\DES{\VAR{stream}}\DF{\V{\A standard-output\A}}})}
{
Output \retval{\VAR{char}} to \VAR{stream}.
}
\IT{(\xorGOO{\FU*{WRITE-STRING}\\
\FU*{WRITE-LINE}}{\}} \VAR{string}
\OP{\DES{\VAR{stream}}\DF{\V{\A standard-output\A}}
\OP{\orGOO{\kwd{:start} \VAR{ start}\DF{\LIT{0}}\\\kwd{:end} \VAR{
end}\DF{\NIL}}{\}}}})}
{
Write \retval{\VAR{string}} to \VAR{stream} without/with a
trailing newline.
}
\IT{(\FU*{WRITE-BYTE} \VAR{byte} \DES{\VAR{stream}})}
{
Write \retval{\VAR{byte}} to binary \VAR{stream}.
}
\IT{(\FU*{WRITE-SEQUENCE} \VAR{sequence}
\DES{\VAR{stream}} \orGOO{\kwd{:start}\VAR{ start}\DF{\LIT{0}}\\
\kwd{:end} \VAR{ end}\DF{\NIL}}{\}})}
{
Write elements of \retval{\VAR{sequence}} to binary or character
\VAR{stream}.
}
\IT{(\xorGOO{\FU*{WRITE}\\
\FU*{WRITE-TO-STRING}}{\}} \VAR{foo} \orGOO{%
\kwd{:array} \VAR{ bool}\\
\kwd{:base} \VAR{ radix}\\
\kwd{:case } \xorGOO{\kwd{:upcase}\\
\kwd{:downcase}\\
\kwd{:capitalize}}{.}\\
\kwd{:circle} \VAR{ bool}\\
\kwd{:escape} \VAR{ bool}\\
\kwd{:gensym} \VAR{ bool}\\
\kwd{:length } \Goo{\VAR{int}\XOR\NIL}\\
\kwd{:level } \Goo{\VAR{int}\XOR\NIL}\\
\kwd{:lines } \Goo{\VAR{int}\XOR\NIL}\\
\kwd{:miser-width } \Goo{\VAR{int}\XOR\NIL}\\
\kwd{:pprint-dispatch} \VAR{ dispatch-table}\\
\kwd{:pretty} \VAR{ bool}\\
\kwd{:radix} \VAR{ bool}\\
\kwd{:readably} \VAR{ bool}\\
\kwd{:right-margin } \Goo{\VAR{int}\XOR\NIL}\\
\kwd{:stream } \DES{\VAR{stream}}\DF{\V{\A standard-output\A}}%
}{\}})}
{
Print \VAR{foo} to \VAR{stream} and return \retval{\VAR{foo}}, or
print \VAR{foo} into \retval{string}, respectively, after
dynamically setting printer variables corresponding to keyword
parameters (\kwd{\A print-}\VAR{bar}\kwd{\A} becoming
\kwd{:}\VAR{bar}). (\kwd{:stream} keyword with \FU{write} only.)
}
\IT{\arrGOO{%
(\FU*{PPRINT-FILL } \DES{\VAR{stream}} \VAR{ foo }
\OP{\VAR{parenthesis}\DF{\T} \text{ } \Op{\VAR{noop}}})\\
(\FU*{PPRINT-TABULAR } \DES{\VAR{stream}} \VAR{ foo }
\OP{\VAR{parenthesis}\DF{\T} \text{ } \Op{\VAR{noop} \text{ }
\Op{\VAR{n}\DF{\LIT{16}}}}})\\
(\FU*{PPRINT-LINEAR } \DES{\VAR{stream}} \VAR{ foo }
\OP{\VAR{parenthesis}\DF{\T} \text{ } \Op{\VAR{noop}}})\\
}{.}}
{
Print \VAR{foo} to \VAR{stream}. If \VAR{foo} is a list, print as
many elements per line as possible; do the same in a table with
a column width of \VAR{n} ems; or print either all elements on
one line or each on its own line, respectively. Return
\retval{\NIL}. Usable with \FU{format} directive \KWD{\TLD//}.
}
\IT{(\MC*{PPRINT-LOGICAL-BLOCK} (\DES{\VAR{stream}} \VAR{list}
\orGOO{\xorGOO{\kwd{:prefix} \VAR{ string}\\
\kwd{:per-line-prefix} \VAR{ string}}{\}}\\
\kwd{:suffix} \VAR{ string}\DF{\LIT{""}}}{\}})
\OPn{(\kwd{declare} \OPn{\NEV{\VAR{decl}}})} \PROGN{\VAR{form}})}
{
Evaluate \VAR{form}s, which should print \VAR{list}, with
\VAR{stream} locally bound to a pretty
printing stream which outputs to the original \VAR{stream}. If
\VAR{list} is in fact not a list, it is printed by
\FU{write}. Return \retval{\NIL}.
}
\begin{LIST}{.5cm}
\IT{(\MC*{PPRINT-POP})}
{
Take \retval{next element} off \VAR{list}. If there is no remaining
tail of \VAR{list}, or \V{\A print-length\A} or \V{\A print-circle\A} indicate
printing should end, send element together with an appropriate
indicator to \VAR{stream}.
}
\IT{(\FU*{PPRINT-TAB} \xorGOO{\kwd{:line}\\
\kwd{:line-relative}\\
\kwd{:section}\\
\kwd{:section-relative}}{\}} \VAR{c}
\VAR{i} \Op{\DES{\VAR{stream}}\DF{\V{\A standard-output\A}}})}
{
Move cursor forward to column number $c + ki$, $k \geq 0$ being as small
as possible.
}
\IT{(\FU*{PPRINT-INDENT} \xorGOO{%
\kwd{:block}\\
\kwd{:current}}{\}} \VAR{n}
\OP{\DES{\VAR{stream}}\DF{\V{\A standard-output\A}}})}
{
Specify indentation for innermost logical block relative to
leftmost position/to current position. Return \retval{\NIL}.
}
\IT{(\MC*{PPRINT-EXIT-IF-LIST-EXHAUSTED})}
{
If \VAR{list} is empty, terminate logical block. Return
\retval{\NIL} otherwise.
}
\end{LIST}
\IT{(\FU*{PPRINT-NEWLINE} \xorGOO{%
\kwd{:linear}\\
\kwd{:fill}\\
\kwd{:miser}\\
\kwd{:mandatory}}{\}}
\OP{\DES{\VAR{stream}}\DF{\V{\A standard-output\A}}})}
{
Print a conditional newline if \VAR{stream} is a pretty printing
stream. Return \retval{\NIL}.
}
\IT{\V{\A print-array\A}}
{\index{*PRINT-ARRAY*@\A PRINT-ARRAY\A}
If \T, print arrays \FU{read}ably.
}
\IT{\V{\A print-base\A}\DF{\LIT{10}}}
{\index{*PRINT-BASE*@\A PRINT-BASE\A}
Radix for printing rationals, from 2 to 36.
}
\IT{\V{\A print-case\A}\DF{\kwd{:upcase}}}
{\index{*PRINT-CASE*@\A PRINT-CASE\A}
Print symbol names all uppercase (\kwd{:upcase}), all lowercase
(\kwd{:downcase}), capitalized (\kwd{:capitalize}).
}
\IT{\V{\A print-circle\A}\DF{\NIL}}
{\index{*PRINT-CIRCLE*@\A PRINT-CIRCLE\A}
If \T, avoid indefinite recursion while printing circular
structure.
}
\IT{\V{\A print-escape\A}\DF{\T}}
{\index{*PRINT-ESCAPE*@\A PRINT-ESCAPE\A}
If \NIL, do not print escape characters and package prefixes.
}
\IT{\V{\A print-gensym\A}\DF{\T}}
{\index{*PRINT-GENSYM*@\A PRINT-GENSYM\A}
If \T, print \kwd{\#:} before uninterned symbols.
}
\IT{\arrGOO{\V{\A print-length\A}\DF{\NIL}\\
\V{\A print-level\A}\DF{\NIL}\\
\V{\A print-lines\A}\DF{\NIL}
}{.}}
{\index{*PRINT-LENGTH*@\A PRINT-LENGTH\A}\index{*PRINT-LEVEL*@\A PRINT-LEVEL\A}\index{*PRINT-LINES*@\A PRINT-LINES\A}
If integer, restrict printing of objects to that number of
elements per level/to that depth/to that number of lines.
}
\IT{\V{\A print-miser-width\A}}
{\index{*PRINT-MISER-WIDTH*@\A PRINT-MISER-WIDTH\A}
If integer and greater than the width available for printing a
substructure, switch to the more compact miser style.
}
\IT{\V{\A print-pretty\A}}
{\index{*PRINT-PRETTY*@\A PRINT-PRETTY\A}
If \T, print prettily.
}
\IT{\V{\A print-radix\A}\DF{\NIL}}
{\index{*PRINT-RADIX*@\A PRINT-RADIX\A}
If \T, print rationals with a radix indicator.
}
\IT{\V{\A print-readably\A}\DF{\NIL}}
{\index{*PRINT-READABLY*@\A PRINT-READABLY\A}
If \T, print \FU{read}ably or signal error
\kwd{print-not-readable}.
}
\IT{\V{\A print-right-margin\A}\DF{\NIL}}
{\index{*PRINT-RIGHT-MARGIN*@\A PRINT-RIGHT-MARGIN\A}
Right margin width in ems while pretty-printing.
}
\IT{(\FU*{SET-PPRINT-DISPATCH} \VAR{type} \VAR{function}
\OP{\VAR{priority}\DF{\LIT{0}}
\Op{\VAR{table}\DF{\V{\A print-pprint-dispatch\A}}}})}
{
Install entry comprising \VAR{function} of arguments stream and
object to print; and \VAR{priority} as
\VAR{type} into \VAR{table}. If \VAR{function}
is \NIL, remove \VAR{type} from \VAR{table}. Return \retval{\NIL}.
}
\IT{(\FU*{PPRINT-DISPATCH} \VAR{foo}
\Op{\VAR{table}\DF{\V{\A print-pprint-dispatch\A}}})}
{
Return highest priority \retval{\VAR{function}} associated with
type of \VAR{foo} and \retvalii{\T} if there was a matching type
specifier in \VAR{table}.
}
\IT{(\FU*{COPY-PPRINT-DISPATCH}
\Op{\VAR{table}\DF{\V{\A print-pprint-dispatch\A}}})}
{
Return \retval{copy of \VAR{table}} or, if \VAR{table} is \NIL,
initial value of \V{\A print-pprint-dispatch\A}.
}
\IT{\V{\A print-pprint-dispatch\A}}
{\index{*PRINT-PPRINT-DISPATCH*@\A PRINT-PPRINT-DISPATCH\A}
Current pretty print dispatch table.
}
\end{LIST}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Format}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{section:Format}
\begin{LIST}{1cm}
\IT{(\MC*{FORMATTER} \NEV{\VAR{control}})}
{
Return \retval{function} of \VAR{stream} and \OPn{\VAR{arg}}
applying \FU{format} to \VAR{stream}, \VAR{control}, and
\OPn{\VAR{arg}} returning \NIL\ or any excess \VAR{arg}s.
}
\IT{(\FU*{FORMAT} \Goo{\T\XOR\NIL\XOR\VAR{out-string}\XOR\VAR{out-stream}}
\VAR{control} \OPn{\VAR{arg}})}
{
Output string \VAR{control} which may
contain \kwd{\TLD} directives possibly taking some
\VAR{arg}s. Alternatively, \VAR{control} can be a function returned
by \MC{formatter} which is then applied to \VAR{out-stream} and
\OPn{\VAR{arg}}. Output to \VAR{out-string}, \VAR{out-stream} or,
if first argument is \T, to \V{\A standard-output\A}. Return
\retval{\NIL}. If first argument is \NIL, return
\retval{formatted output}.
}
\begin{LIST}{.5cm}
\IT{\KWD{\TLD} \Op{\VAR{min-col}\DF{\LIT{0}}} \OP{\KWD{,}\Op{\VAR{col-inc}\DF{\LIT{1}}}
\OP{\KWD{,}\Op{\VAR{min-pad}\DF{\LIT{0}}}
\OP{\KWD{,'}\VAR{pad-char}\DF{\textvisiblespace}}}}
\KWD{\Op{:} \Op{@} \Goo{A\XOR S}}}
{\index{\~S@$\sim$S}\index{\~A@$\sim$A}%
\EM{Aesthetic/Standard. }
Print argument of any type for consumption by humans/by the
reader, respectively. With \kwd{:}, print \NIL\ as \LIT{()} rather
than \LIT{nil}; with \kwd{@}, add \VAR{pad-char}s on the left
rather than on the right.
}
\IT{\KWD{\TLD} \Op{\VAR{radix}\DF{\LIT{10}}} \OP{\KWD{,}\Op{\VAR{width}}
\OP{\KWD{,}\Op{\kwd{'}\VAR{pad-char}\DF{\textvisiblespace}}
\OP{\KWD{,}\Op{\kwd{'}\VAR{comma-char}\DF{\LIT{,}}}
\OP{\KWD{,}\VAR{comma-interval}\DF{\LIT{3}}}}}}
\KWD{\Op{:} \Op{@} R}}
{\index{\~R@$\sim$R}%
\EM{Radix. }
(With one or more prefix arguments.) Print argument as number; with
\KWD{:}, group digits \VAR{comma-interval} each; with \kwd{@},
always prepend a sign.
}
\IT{\Goo{\KWD{\TLD R}\XOR\KWD{\TLD :R}\XOR\KWD{\TLD
@R}\XOR\KWD{\TLD @:R}}}
{
\EM{Roman. }
Take argument as number and print it as English cardinal number,
as English ordinal number, as Roman numeral, or as old Roman
numeral, respectively.
}
\IT{\KWD{\TLD} \Op{\VAR{width}}
\OP{\KWD{,}\Op{\kwd{'}\VAR{pad-char}\DF{\textvisiblespace}}
\OP{\KWD{,}\Op{\kwd{'}\VAR{comma-char}\DF{\LIT{,}}}
\OP{\KWD{,}\VAR{comma-interval}\DF{\LIT{3}}}}}
\KWD{\Op{:} \Op{@} \Goo{D\XOR B\XOR O\XOR X}}}
{\index{\~D@$\sim$D}\index{\~B@$\sim$B}\index{\~O@$\sim$O}\index{\~X@$\sim$X}%
\EM{Decimal/Binary/Octal/Hexadecimal. }
Print integer argument as number. With \kwd{:}, group digits
\VAR{comma-interval} each; with \kwd{@}, always prepend a sign.
}
\IT{\KWD{\TLD} \Op{\VAR{width}} \OP{\KWD{,}\Op{\VAR{dec-digits}}
\OP{\KWD{,}\Op{\VAR{shift}\DF{\LIT{0}}}
\OP{\KWD{,}\Op{\kwd{'}\VAR{overflow-char}}
\OP{\KWD{,'}\VAR{pad-char}\DF{\textvisiblespace}}}}}
\KWD{\Op{@} F}}
{\index{\~F@$\sim$F}%
\EM{Fixed-Format Floating-Point. } With
\kwd{@}, always pre\-pend a sign.
}
\IT{\KWD{\TLD} \Op{\VAR{width}} \OP{\KWD{,}\Op{\VAR{dec-digits}}
\OP{\KWD{,}\Op{\VAR{exp-digits}}
\OP{\KWD{,}\Op{\VAR{scale-factor}\DF{\LIT{1}}}
\OP{\KWD{,}\Op{\kwd{'}\VAR{overflow-char}}
\OP{\KWD{,}\Op{\kwd{'}\VAR{pad-char}\DF{\textvisiblespace}}
\OP{\KWD{,'}\VAR{exp-char}}}}}}}
\KWD{\Op{@} \Goo{E\XOR G}}}
{\index{\~E@$\sim$E}\index{\~G@$\sim$G}%
\EM{Exponential/General Floating-Point. }
Print argument as floating-point number with \VAR{dec-digits}
after decimal point and \VAR{exp-digits} in the signed
exponent. With \KWD{\TLD G}, choose either \KWD{\TLD E} or
\KWD{\TLD F}. With \KWD{@}, always prepend a sign.
}
\IT{\KWD{\TLD} \Op{\VAR{dec-digits}\DF{\LIT{2}}}
\OP{\KWD{,}\Op{\VAR{int-digits}\DF{\LIT{1}}}
\OP{\KWD{,}\Op{\VAR{width}\DF{\LIT{0}}}
\OP{\KWD{,'}\VAR{pad-char}\DF{\textvisiblespace}}}}
\Op{\KWD{:}} \Op{\kwd{@}} \KWD{\$}}
{\index{\~\$@$\sim$\$}%
\EM{Monetary Floating-Point. }
Print argument as fixed-format floating-point number. With \KWD{:},
put sign before any padding; with \KWD{@}, always prepend a
sign.
}
\IT{\Goo{\KWD{\TLD C}\XOR\KWD{\TLD :C}\XOR\KWD{\TLD
@C}\XOR\KWD{\TLD @:C}}}
{\index{\~C@$\sim$C}%
\EM{Character. }
Print, spell out, print in \kwd{\#$\backslash$} syntax, or tell
how to type, respectively, argument as (possibly non-printing)
character.
}
\IT{\Goo{%
\KWD{\TLD(} \VAR{text} \KWD{\TLD)}\XOR
\KWD{\TLD:(} \VAR{text} \KWD{\TLD)}\XOR
\KWD{\TLD @(} \VAR{text} \KWD{\TLD)}\XOR
\KWD{\TLD @:(} \VAR{text} \KWD{\TLD)}}}
{\index{\~(\~)@$\sim$( $\sim$)}%
\EM{Case-Conversion. }
Convert \VAR{text} to lowercase, convert first letter of each word
to uppercase, capitalize first word and convert the rest to
lowercase, or convert to uppercase, respectively.
}
\IT{\Goo{\KWD{\TLD P}\XOR\KWD{\TLD:P}
\XOR\KWD{\TLD @P}\XOR\KWD{\TLD @:P}}}
{\index{\~P@$\sim$P}%
\EM{Plural. }
If argument \kwd{eql} \LIT{1} print nothing, otherwise print \LIT{s};
do the same for the previous argument; if argument \kwd{eql} \LIT{1}
print \LIT{y}, otherwise print \LIT{ies}; do the same for the
previous argument, respectively.
}
\IT{\KWD{\TLD} \Op{\VAR{n}\DF{\LIT{1}}} \KWD{\%}}
{\index{\~\%@$\sim$\%}%
\EM{Newline. }
Print \VAR{n} newlines.
}
\IT{\KWD{\TLD} \Op{\VAR{n}\DF{\LIT{1}}} \KWD{\&}}
{\index{\~\&@$\sim$\&}%
\EM{Fresh-Line. }
Print $n-1$ newlines if output stream is at the
beginning of a line, or \VAR{n} newlines otherwise.
}
\IT{\Goo{%
\KWD{\TLD\_}\XOR
\KWD{\TLD:\_}\XOR
\KWD{\TLD@\_}\XOR
\KWD{\TLD @:\_}}}
{\index{\~\_{}@$\sim$\_{}}%
\EM{Conditional Newline. }
Print a newline like \kwd{pprint-newline} with argument
\kwd{:linear}, \kwd{:fill}, \kwd{:miser}, or \kwd{:mandatory}, respectively.
}
\IT{\Goo{\KWD{\TLD:$\hookleftarrow$}\XOR\KWD{\TLD@$\hookleftarrow$}\XOR\KWD{\TLD$\hookleftarrow$}}}
{\index{\~\~bogus-ordering{}@$\sim\hookleftarrow$}%
\EM{Ignored Newline. } Ignore newline, or whitespace following
newline, or both, respectively.
}
\IT{\KWD{\TLD} \Op{\VAR{n}\DF{\LIT{1}}} \KWD{\boldmath$|$}}
{\index{\~\textbar@$\sim${$"|$}}%
\EM{Page. }
Print \VAR{n} page separators.
}
\IT{\KWD{\TLD} \Op{\VAR{n}\DF{\LIT{1}}} \KWD{\TLD}}
{\index{\~\~@$\sim$$\sim$}%
\EM{Tilde. }
Print \VAR{n} tildes.
}
\IT{\KWD{\TLD} \Op{\VAR{min-col}\DF{\LIT{0}}}
\OP{\KWD{,}\Op{\VAR{col-inc}\DF{\LIT{1}}}
\OP{\KWD{,}\Op{\VAR{min-pad}\DF{\LIT{0}}}
\OP{\KWD{,'}\VAR{pad-char}\DF{\textvisiblespace}}}}
\KWD{\Op{:} \Op{@} \boldmath{$<$}}
\OP{\VAR{nl-text} \KWD{\TLD}\Op{\VAR{spare}\DF{\LIT{0}} \Op{\KWD{,}\VAR{width}}}\kwd{:;}}
\Goos{\VAR{text} \KWD{\TLD;}} \VAR{text} \KWD{\TLD\boldmath{$>$}}}
{\index{\~<\~>@$\sim$$<$ $\sim$$>$}%
\EM{Justification. }
Justify text produced by \VAR{text}s in a field of at least
\VAR{min-col} columns. With \kwd{:}, right justify; with \kwd{@},
left justify. If this would leave less than \VAR{spare} characters
on the current line, output \VAR{nl-text} first.
}
\IT{\KWD{\TLD} \Op{\KWD{:}} \Op{\KWD{@}} \KWD{\boldmath{$<$}}
\GOo{\Op{\VAR{prefix}\DF{\LIT{""}}
\KWD{\TLD;}}\XOR\Op{\VAR{per-line-prefix}
\KWD{\TLD@;}}}
\VAR{body} \OP{\KWD{\TLD;} \VAR{suffix}\DF{\LIT{""}}}
\KWD{\TLD:} \Op{\KWD{@}} \KWD{\boldmath{$>$}}}
{\index{\~<\~:>@$\sim$$<$ $\sim$:$>$}%
\EM{Logical Block. }
Act like \kwd{pprint-logical-block} using \VAR{body} as \FU{format}
control string on the elements of the list argument or, with \KWD{@},
on the remaining arguments, which are extracted by
\kwd{pprint-pop}. With \KWD{:}, \VAR{prefix} and \VAR{suffix}
default to \LIT{(} and \LIT{)}. When closed by
\KWD{\TLD @:\boldmath{$>$}}, spaces in \VAR{body} are replaced with
conditional newlines.
}
\IT{\Goo{\KWD{\TLD} \Op{\VAR{n}\DF{\LIT{0}}}
\kwd{I}\XOR\KWD{\TLD} \Op{\VAR{n}\DF{\LIT{0}}} \kwd{:I}}}
{\index{\~I@$\sim$I}%
\EM{Indent. }
Set indentation to \VAR{n} relative to leftmost/to current
position.
}
\IT{\KWD{\TLD} \Op{\VAR{c}\DF{\LIT{1}}}
\Op{\KWD{,}\VAR{i}\DF{\LIT{1}}} \Op{\KWD{:}} \Op{\KWD{@}} \KWD{T}}
{\index{\~T@$\sim$T}%
\EM{Tabulate. }
Move cursor forward to column number $c + ki$, $k \geq 0$ being as small
as possible. With \kwd{:}, calculate column numbers relative to
the immediately enclosing section. With \kwd{@}, move to column
number $c_0 + c + ki$ where $c_0$ is the current position.
}
\IT{\Goo{%
\KWD{\TLD} \Op{\VAR{m}\DF{\LIT{1}}} \KWD{\A}\XOR
\KWD{\TLD} \Op{\VAR{m}\DF{\LIT{1}}} \KWD{:}\KWD{\A}\XOR
\KWD{\TLD} \Op{\VAR{n}\DF{\LIT{0}}} \KWD{@}\KWD{\A}}}
{\index{\~*@$\sim$\A}%
\EM{Go-To. }
Jump \VAR{m} arguments forward, or backward, or to argument \VAR{n}.
}
\IT{\KWD{\TLD} \Op{\VAR{limit}} \Op{\KWD{{:}}} \Op{\kwd{@}}
\KWD{\boldmath{$\{$}} \VAR{text} \KWD{\TLD\boldmath{$\}$}}}
{\index{\~\{\~\}@$\sim$$\{$ $\sim\}$}%
\EM{Iteration. }
Use \VAR{text} repeatedly, up to \VAR{limit}, as control
string for the elements of the list argument or (with
\kwd{@}) for the remaining arguments. With \kwd{:} or \kwd{@:},
list elements or remaining arguments should be
lists of which a new one is used at each iteration step.
}
\IT{\KWD{\TLD} \OP{\VAR{x} \OP{\kwd{,}\VAR{y} \Op{\kwd{,}\VAR{z}}}}
\KWD{\^{}}}
{\index{\~\^{}@$\sim$\^{}}%
\EM{Escape Upward. }
Leave immediately \kwd{\TLD\boldmath{$<$} \TLD\boldmath{$>$}},
\kwd{\TLD\boldmath{$<$} \TLD:\boldmath{$>$}},
\kwd{\TLD\boldmath{$\{$} \TLD\boldmath{$\}$}}, \kwd{\TLD?}, or the
entire \FU{format} operation. With one to three prefixes, act only
if $x=0$, $x=y$, or $x\leq y \leq z$, respectively.
}
\IT{\KWD{\TLD} \Op{\VAR{i}} \Op{\KWD{:}} \Op{\KWD{@}}
\KWD{[} \Op{\Goos{\VAR{text} \KWD{\TLD;}} \VAR{text}}
\Op{\kwd{\TLD:;} \VAR{default}} \KWD{\TLD]}}
{\index{\~[\~]@$\sim$[ $\sim$]}%
\EM{Conditional Expression. }
Use the zero-indexed argumenth (or
\VAR{i}th if given) \VAR{text} as a \FU{format} control subclause.
With \kwd{:}, use the first \VAR{text} if the argument value is
\NIL, or the second \VAR{text} if it is \T. With \kwd{@}, do nothing
for an argument value of \NIL. Use the only \VAR{text} and leave
the argument to be read again if it is \T.
}
\IT{\Goo{%
\KWD{\TLD?}\XOR
\KWD{\TLD @?}}
}
{\index{\~?@$\sim$?}%
\EM{Recursive Processing. }
Process two arguments as control string and argument list, or
take one argument as control string and use then the rest of the
original arguments.
}
\IT{\KWD{\TLD} \OP{\VAR{prefix} \Goos{\kwd{,}%
\VAR{prefix}}}
\Op{\kwd{:}} \Op{\kwd{@}}
\KWD{/}\OP{\VAR{package}
\Op{\LIT{:}}\LIT{:}\DF{\LIT{cl-user:}}}\VAR{function}\KWD{/}}
{\index{\~/ /@$\sim$/ /}%
\EM{Call Function. }
Call all-uppercase \VAR{package\KWD{::}function} with the
arguments stream, format-ar\-gu\-ment, colon-p, at-sign-p and
\VAR{prefix}es for printing format-argument.
}
\IT{\KWD{\TLD} \Op{\KWD{:}} \Op{\KWD{@}} \KWD{W}}
{\index{\~W@$\sim$W}%
\EM{Write. }
Print argument of any type obeying every printer control
variable. With \kwd{:}, pretty-print. With \kwd{@}, print
without limits on length or depth.
}
\IT{\Goo{\KWD{V}\XOR\KWD{\#}}}
{\index{V}\index{\#}
In place of the comma-separated prefix parameters: use next
argument or number of remaining unprocessed arguments, respectively.
}
\end{LIST}
\end{LIST}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Streams}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{LIST}{1cm}
\IT{(\FU*{OPEN} \VAR{path}
\orGOO{\kwd{:direction }
\xorGOO{\kwd{:input}\\
\kwd{:output}\\
\kwd{:io}\\
\kwd{:probe}}{\}}\DF{\kwd{:input}}\\
\kwd{:element-type }
\xorGOO{\VAR{type}\\
\kwd{:default}}{\}}\DF{\kwd{character}}\\
\kwd{:if-exists }
\xorGOO{\kwd{:new-version}\\
\kwd{:error}\\
\kwd{:rename}\\
\kwd{:rename-and-delete}\\
\kwd{:overwrite}\\
\kwd{:append}\\
\kwd{:supersede}\\
\NIL}{\}}\DF{\parbox{20mm}{%
\kwd{:new-version} if \VAR{path} specifies \kwd{:newest};\\
\NIL\ otherwise}}\\
\kwd{:if-does-not-exist }
\xorGOO{\kwd{:error}\\
\kwd{:create}\\
\NIL}{\}}\DF{\parbox{27mm}{%
\NIL\ for \kwd{:direction :probe};\\
\mbox{\Goo{\kwd{:create}\XOR\kwd{:error}} otherwise}}}\\
\kwd{:external-format } \VAR{format}\DF{\kwd{:default}}%
}{\}})}
{\label{open}
Open \retval{\kwd{file-stream} to \VAR{path}}.
}
\IT{\arrGOO{%
(\FU*{MAKE-CONCATENATED-STREAM } \OPn{\VAR{input-stream}})\\
(\FU*{MAKE-BROADCAST-STREAM } \OPn{\VAR{output-stream}})\\
(\FU*{MAKE-TWO-WAY-STREAM } \VAR{input-stream-part } \VAR{output-stream-part})\\
(\FU*{MAKE-ECHO-STREAM } \VAR{from-input-stream } \VAR{to-output-stream})\\
(\FU*{MAKE-SYNONYM-STREAM } \VAR{variable-bound-to-stream})}{.}}
{
Return \retval{stream} of indicated type.
}
\IT{(\FU*{MAKE-STRING-INPUT-STREAM} \VAR{string}
\OP{\VAR{start}\DF{\LIT{0}}
\Op{\VAR{end}\DF{\NIL}}})}
{
Return a \retval{\kwd{string-stream}} supplying the characters from \VAR{string}.
}
\IT{(\FU*{MAKE-STRING-OUTPUT-STREAM} \Op{\kwd{:element-type}
\VAR{type}\DF{\kwd{character}}})}
{
Return a \retval{\kwd{string-stream}} accepting characters
(available via \FU{get-output-stream-string}).
}
\IT{\arrGOO{(\FU*{CONCATENATED-STREAM-STREAMS } \VAR{concatenated-stream})\\
(\FU*{BROADCAST-STREAM-STREAMS } \VAR{broadcast-stream})}{.}}
{
Return \retval{list of streams} \VAR{concatenated-stream} still
has to read from/\VAR{broadcast-stream} is
broadcasting to.
}
\IT{\arrGOO{%
(\FU*{TWO-WAY-STREAM-INPUT-STREAM} \VAR{ two-way-stream})\\
(\FU*{TWO-WAY-STREAM-OUTPUT-STREAM} \VAR{ two-way-stream})\\
(\FU*{ECHO-STREAM-INPUT-STREAM} \VAR{ echo-stream})\\
(\FU*{ECHO-STREAM-OUTPUT-STREAM} \VAR{ echo-stream})}{.}}
{
Return \retval{source stream} or \retval{sink stream} of
\VAR{two-way-stream}\slash\VAR{echo-stream}, respectively.
}
\IT{(\FU*{SYNONYM-STREAM-SYMBOL} \VAR{synonym-stream})}
{
Return \retval{symbol} of \VAR{synonym-stream}.
}
\IT{(\FU*{GET-OUTPUT-STREAM-STRING} \DES{\VAR{string-stream}})}
{
Clear and return as a \retval{string} characters on
\VAR{string-stream}.
}
\IT{(\FU*{FILE-POSITION} \VAR{stream} \Op{\xorGOO{\kwd{:start}\\
\kwd{:end}\\
\VAR{position}}{\}}})}
{
Return \retval{position within stream}, or set it to
\retval{\VAR{position}} and return \retval{\T} on success.
}
\IT{(\FU*{FILE-STRING-LENGTH} \VAR{stream} \VAR{foo})}
{
\retval{Length} \VAR{foo} would have in \VAR{stream}.
}
\IT{(\FU*{LISTEN} \Op{\VAR{stream}\DF{\V{\A standard-input\A}}})}
{
\retval{\T} if there is a character in input \VAR{stream}.
}
\IT{(\FU*{CLEAR-INPUT}
\Op{\DES{\VAR{stream}}\DF{\V{\A standard-input\A}}})}
{
Clear input from \VAR{stream}, return \retval{\NIL}.
}
\IT{(\xorGOO{\FU*{CLEAR-OUTPUT}\\
\FU*{FORCE-OUTPUT}\\
\FU*{FINISH-OUTPUT}}{\}}
\Op{\DES{\VAR{stream}}\DF{\V{\A standard-output\A}}})}
{
End output to \VAR{stream} and return \retval{\NIL} immediately,
after initiating flushing of buffers, or after flushing of
buffers, respectively.
}
\IT{(\FU*{CLOSE} \DES{\VAR{stream}} \Op{\kwd{:abort}
\VAR{bool}\DF{\NIL}})}
{
Close \VAR{stream}. Return \retval{\T} if \VAR{stream} had been
open. If \kwd{:abort} is \T, delete associated file.
}
\IT{(\MC*{WITH-OPEN-FILE} (\VAR{stream} \VAR{path}
\OPn{\VAR{open-arg}}) \OPn{(\kwd{declare} \OPn{\NEV{\VAR{decl}}})}
\PROGN{\VAR{form}})}
{
Use \FU{OPEN} with \VAR{open-arg}s to temporarily create
\VAR{stream} to \VAR{path}; return \retval{values of
\VAR{form}s}.
}
\IT{(\MC*{WITH-OPEN-STREAM} (\VAR{foo} \DES{\VAR{stream}})
\OPn{(\kwd{declare} \OPn{\NEV{\VAR{decl}}})} \PROGN{\VAR{form}})}
{
Evaluate \VAR{form}s with \VAR{foo} locally bound to
\VAR{stream}. Return \retval{values of \VAR{form}s}.
}
\IT{(\MC*{WITH-INPUT-FROM-STRING} (\VAR{foo} \VAR{string}
\orGOO{\kwd{:index } \DES{\VAR{index}}\\
\kwd{:start} \VAR{ start}\DF{\LIT{0}}\\
\kwd{:end} \VAR{ end}\DF{\NIL}}{\}}) \OPn{(\kwd{declare}
\OPn{\NEV{\VAR{decl}}})} \PROGN{\VAR{form}})}
{
Evaluate \VAR{form}s with \VAR{foo} locally bound to input
\kwd{string-stream} from \VAR{string}. Return \retval{values of
\VAR{form}s}; store next reading position into \VAR{index}.
}
\IT{(\MC*{WITH-OUTPUT-TO-STRING} (\VAR{foo}
\OP{\DES{\VAR{string}}\DF{\NIL}
\Op{\kwd{:element-type}
\VAR{type}\DF{\kwd{character}}}})
\OPn{(\kwd{declare}
\OPn{\NEV{\VAR{decl}}})} \PROGN{\VAR{form}})}
{
Evaluate \VAR{form}s with \VAR{foo} locally bound to an output
\kwd{string-stream}. Append output to \VAR{string} and return
\retval{values of \VAR{form}s} if \VAR{string} is given. Return
\retval{string containing output} otherwise.
}
\IT{(\FU*{STREAM-EXTERNAL-FORMAT} \VAR{stream})}
{
\retval{External file format designator}.
}
\IT{\V{\A terminal-io\A}}
{\index{*TERMINAL-IO*@\A TERMINAL-IO\A}
Bidirectional stream to user terminal.
}
\IT{\arrGOO{\V{\A standard-input\A}\\
\V{\A standard-output\A}\\
\V{\A error-output\A}}{.}}
{\index{*STANDARD-INPUT*@\A STANDARD-INPUT\A}%
\index{*STANDARD-OUTPUT*@\A STANDARD-OUTPUT\A}%
\index{*ERROR-OUTPUT*@\A ERROR-OUTPUT\A}
Standard input stream, standard output stream,
or standard error output stream, respectively.
}
\IT{\arrGOO{\V{\A debug-io\A}\\
\V{\A query-io\A}}{.}}
{\index{*DEBUG-IO*@\A DEBUG-IO\A}\index{*QUERY-IO*@\A QUERY-IO\A}
Bidirectional streams for debugging and user interaction.
}
\end{LIST}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection[Paths and Files]{Pathnames and Files}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{LIST}{1cm}
\IT{(\FU*{MAKE-PATHNAME}
\orGOO{\kwd{:host } \Goo{\VAR{host}\XOR\NIL\XOR\kwd{:unspecific}}\\
\kwd{:device } \Goo{\VAR{device}\XOR\NIL\XOR\kwd{:unspecific}}\\
\kwd{:directory } \xorGOO{%
\Goo{\VAR{directory}\XOR\kwd{:wild}\XOR\NIL\XOR\kwd{:unspecific}}\\
(\xorGOO{%
\kwd{:absolute}\\
\kwd{:relative}
}{\}}\text{ }%
\xorGOO{%
\VAR{directory}\\
\kwd{:wild}\\
\kwd{:wild-inferiors}\\
\kwd{:up}\\
\kwd{:back}
}{\}^{\!\!*}})
}{.}\\
\kwd{:name }
\Goo{\VAR{file-name}\XOR\kwd{:wild}\XOR\NIL\XOR\kwd{:unspecific}}\\
\kwd{:type }
\Goo{\VAR{file-type}\XOR\kwd{:wild}\XOR\NIL\XOR\kwd{:unspecific}}\\
\kwd{:version }
\Goo{\kwd{:newest}\XOR\VAR{version}\XOR\kwd{:wild}\XOR\NIL\XOR\kwd{:unspecific}}\\
\kwd{:defaults }
\VAR{path}\DF{host from \V{\A default-pathname-defaults\A}}\\
\kwd{:case
\Goo{\kwd{:local}\XOR\kwd{:common}}\DF{\kwd{:local}}}}{\}})}
{
Construct a \retval{logical pathname} if there is a logical
pathname translation for \VAR{host}, otherwise construct a
\retval{physical pathname}. For \kwd{:case :local}, leave case of
components unchanged. For \kwd{:case :common}, leave mixed-case
components unchanged; convert all-uppercase components into local
customary case; do the opposite with all-lowercase components.
}
\IT{\arrGOO{%
(\xorGOO{\FU*{PATHNAME-HOST}\\
\FU*{PATHNAME-DEVICE}\\
\FU*{PATHNAME-DIRECTORY}\\
\FU*{PATHNAME-NAME}\\
\FU*{PATHNAME-TYPE}}{\}}
\VAR{ path-or-stream }
\Op{\kwd{:case } \xorGOO{\kwd{:local}\\
\kwd{:common}}{\}}\DF{\kwd{:local}}})\\
(\FU*{PATHNAME-VERSION } \VAR{path-or-stream})}{.}}
{
Return \retval{pathname component}.
}
\IT{(\FU*{PARSE-NAMESTRING} \VAR{foo}
\OP{\VAR{host}
\OP{\VAR{default-pathname}\DF{\V{\A default-pathname-defaults\A}}
\orGOO{\kwd{:start} \VAR{ start}\DF{\LIT{0}}\\
\kwd{:end} \VAR{ end}\DF{\NIL}\\
\kwd{:junk-allowed} \VAR{ bool}\DF{\NIL}}{\}}}})}
{
Return \retval{pathname} converted from
string, pathname, or stream \VAR{foo}; and \retvalii{position}
where parsing stopped.
}
\IT{(\FU*{MERGE-PATHNAMES} \VAR{path-or-stream}
\OP{\VAR{default-path-or-stream}\DF{\V{\A default-pathname-defaults\A}}
\Op{\VAR{default-version}\DF{\kwd{:newest}}}})}
{
Return \retval{pathname} made by filling in components missing in
\VAR{path-or-stream} from \VAR{default-path-or-stream}.
}
\IT{\V{\A default-pathname-defaults\A}}
{\index{*DEFAULT-PATHNAME-DEFAULTS*@\A DEFAULT-PATHNAME-DEFAULTS\A}
Pathname to use if one is needed and none supplied.
}
\IT{(\FU*{USER-HOMEDIR-PATHNAME} \Op{\VAR{host}})}
{
User's \retval{home directory}.
}
\IT{(\FU*{ENOUGH-NAMESTRING} \VAR{path-or-stream}
\Op{\VAR{root-path}\DF{\V{\A default-pathname-defaults\A}}})}
{
Return \retval{minimal path string} that sufficiently describes
the path of \VAR{path-or-stream} relative to \VAR{root-path.}
}
\IT{\arrGOO{(\FU*{NAMESTRING}\VAR{ path-or-stream})\\
(\FU*{FILE-NAMESTRING}\VAR{ path-or-stream})\\
(\FU*{DIRECTORY-NAMESTRING}\VAR{ path-or-stream})\\
(\FU*{HOST-NAMESTRING}\VAR{ path-or-stream})}{.}}
{
Return string representing \retval{full pathname}; \retval{name,
type, and version}; \retval{directory name}; or \retval{host
name}, respectively, of \VAR{path-or-stream}.
}
\IT{(\FU*{TRANSLATE-PATHNAME} \VAR{path-or-stream} \VAR{wildcard-path-a}
\VAR{wildcard-path-b})}
{
Translate the path of \VAR{path-or-stream} from
\VAR{wildcard-path-a} into \VAR{wildcard-path-b}. Return
\retval{new path}.
}
\IT{(\FU*{PATHNAME} \VAR{path-or-stream})}
{
\retval{Pathname} of \VAR{path-or-stream}.
}
\IT{(\FU*{LOGICAL-PATHNAME} \VAR{logical-path-or-stream})}
{
\retval{Logical pathname} of \VAR{logical-path-or-stream}.
Logical pathnames are represented as all-uppercase
\LIT{"}%
\Op{\VAR{host}\LIT{:}}%
\Op{\LIT{;}}%
\Goos{\xorGOO{%
\Goop{\VAR{dir}\XOR\LIT{*}}\\
\LIT{**}}{\}}\LIT{;}}%
\Goos{\VAR{name}\XOR\LIT{*}}%
\OP{\LIT{.}%
\xorGOO{%
\Goop{\VAR{type}\XOR\LIT{*}}\\
\LIT{LISP}}{\}}%
\penalty-5
\Op{\LIT{.}%
\Goo{%
\VAR{version}\XOR\LIT{*}\XOR\LIT{newest}\XOR\LIT{NEWEST}}}}%
\LIT{"}.
\index{*@\A}\index{**@\A\A}%
}
\IT{(\FU*{LOGICAL-PATHNAME-TRANSLATIONS} \VAR{logical-host})}
{
\retval{List of (\VAR{from-wildcard to-wildcard}) translations}
for \VAR{logical-host}. \kwd{setf}able.
}
\IT{(\FU*{LOAD-LOGICAL-PATHNAME-TRANSLATIONS} \VAR{logical-host})}
{
Load \VAR{logical-host}'s translations. Return \retval{\NIL} if already
loaded; return \retval{\T} if successful.
}
\IT{(\FU*{TRANSLATE-LOGICAL-PATHNAME} \VAR{path-or-stream})}
{
\retval{Physical pathname} corresponding to (possibly logical)
pathname of \VAR{path-or-stream}.
}
\IT{\arrGOO{(\FU*{PROBE-FILE} \VAR{ file})\\
(\FU*{TRUENAME} \VAR{ file})}{.}}
{
\retval{Canonical name} of \VAR{file}. If \VAR{file} does not exist,
return \retval{\NIL}/signal \kwd{file-error}, respectively.
}
\IT{(\FU*{FILE-WRITE-DATE} \VAR{file})}
{
\retval{Time} at which \VAR{file} was last written.
}
\IT{(\FU*{FILE-AUTHOR} \VAR{file})\qquad\qquad}
{
Return \retval{name of \VAR{file} owner}.
}
\IT{(\FU*{FILE-LENGTH} \VAR{stream})}
{
Return \retval{length of \VAR{stream}}.
}
\IT{(\FU*{RENAME-FILE} \VAR{foo} \VAR{bar})}
{
Rename file \VAR{foo} to \VAR{bar}. Unspecified components of path
\VAR{bar} default to those of \VAR{foo}. Return \retval{new
pathname}, \retvalii{old physical file name}, and \retvaliii{new
physical file name}.
}
\IT{(\FU*{DELETE-FILE} \VAR{file})}
{
Delete \VAR{file}. Return \retval{\T}.
}
\IT{(\FU*{DIRECTORY} \VAR{path})}
{
\retval{List of pathnames} matching \VAR{path}.
}
\IT{(\FU*{ENSURE-DIRECTORIES-EXIST} \VAR{path} \Op{\kwd{:verbose}
\VAR{bool}})}
{
Create parts of \retval{\VAR{path}} if necessary. Second return value is
\retvalii{\T} if something has been created.
}
\end{LIST}
% LocalWords: ies argumenth ar gu ment
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "clqr"
%%% End: