clqr-input-output.tex

% Copyright (C) 2008, 2009, 2010 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 or any later version published by the Free Software
% Foundation; 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 p.\ \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}. 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} a dispatch function of \VAR{char} 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 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{\KWD{;} \VAR{explanation}}
    {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{int}\kwd{=} \VAR{foo}\qquad\quad}
  {\index{\#=}%
    Give \VAR{foo} the label \VAR{int}.
  }

  \IT{\KWD{\#}\VAR{int}\kwd{\#}\qquad\qquad}
  {\index{\#\#}%
    Object labelled \VAR{int}.
  }

  \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 pretty.
  }

  \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 stream and a \kwd{\&rest} argument applying \FU{format} to
    stream, \VAR{control}, and the \kwd{\&rest} argument
    returning \NIL\ or any excess arguments. 
  }

  \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{\kwd{'}\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{\VAR{pad-char}\DF{\kwd{'}\textvisiblespace}}
          \OP{\KWD{,}\Op{\VAR{comma-char}\DF{\kwd{'}\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{\VAR{pad-char}\DF{\kwd{'}\textvisiblespace}}
        \OP{\KWD{,}\Op{\VAR{comma-char}\DF{\kwd{'}\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{\VAR{overflow-char}}
            \OP{\KWD{,}\VAR{pad-char}\DF{\kwd{'}\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{int-digits}}
        \OP{\KWD{,}\Op{\VAR{exp-digits}}
          \OP{\KWD{,}\Op{\VAR{scale-factor}\DF{\LIT{1}}}
            \OP{\KWD{,}\Op{\VAR{overflow-char}}
              \OP{\KWD{,}\Op{\VAR{pad-char}\DF{\kwd{'}\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{int-digits}
      before 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{\kwd{'}\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{\KWD{\TLD} \Op{\KWD{:}} \Op{\KWD{@}} $\hookleftarrow$}
    {
      \EM{Ignored Newline. } Ignore newline and following
      whitespace. With \kwd{:}, ignore only newline; with \kwd{@},
      ignore only following whitespace.
    }

    \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{\kwd{'}\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{\KWD{\TLD} \Op{\KWD{@}} \KWD{?}}
    {\index{\~?@$\sim$?}%
      \EM{Recursive Processing. }
      Process two arguments as control string and argument list. With
      \kwd{@}, 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{/}\VAR{function}\KWD{/}}
    {\index{\~/ /@$\sim$/ /}%
      \EM{Call Function. }
      Call \VAR{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 \retval{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 }
      \Op{\kwd{:case } \xorGOO{\kwd{:local}\\
          \kwd{:common}}{\}}\DF{\kwd{:local}}})\\
      (\FU*{PATHNAME-VERSION } \VAR{path})}{.}}
  {
    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{pathname}
    \OP{\VAR{default-pathname}\DF{\V{\A default-pathname-defaults\A}}
      \Op{\VAR{default-version}\DF{\kwd{:newest}}}})}
  {
    Return \retval{\VAR{pathname}} after filling in missing components
    from \VAR{default-pathname}.
  }

  \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}
    \Op{\VAR{root-path}\DF{\V{\A default-pathname-defaults\A}}})}
  {
    Return \retval{minimal path string} to sufficiently describe
    \VAR{path} relative to \VAR{root-path.} 
  }

  \IT{\arrGOO{(\FU*{NAMESTRING}\VAR{ path})\\
      (\FU*{FILE-NAMESTRING}\VAR{ path})\\
      (\FU*{DIRECTORY-NAMESTRING}\VAR{ path})\\
      (\FU*{HOST-NAMESTRING}\VAR{ path})}{.}}
  {
    Return string representing \retval{full pathname}; \retval{name,
    type, and version}; \retval{directory name}; or \retval{host
    name}, respectively, of \VAR{path}.
  }

  \IT{(\FU*{TRANSLATE-PATHNAME} \VAR{path} \VAR{wildcard-path-a}
    \VAR{wildcard-path-b})}
  {
    Translate \VAR{path} from \VAR{wildcard-path-a} into 
    \VAR{wildcard-path-b}. Return \retval{new path}.
  }

  \IT{(\FU*{PATHNAME} \VAR{path})}
  {
    \retval{Pathname} of \VAR{path}.
  }

  \IT{(\FU*{LOGICAL-PATHNAME} \VAR{logical-path})}
  {
    \retval{Logical pathname} of \VAR{logical-path}.
    Logical pathnames are represented as all-uppercase
    \LIT{\#P"}%
    \Op{\VAR{host}\LIT{:}}\Op{\LIT{:}}%
    \Goos{\xorGOO{%
        \Goop{\VAR{dir}\XOR\LIT{*}}\\
        \LIT{**}}{\}}\LIT{;}}%
    \penalty-5
    \Goos{\VAR{name}\XOR\LIT{*}}%
    \OP{\LIT{.}%
      \xorGOO{%
        \Goop{\VAR{type}\XOR\LIT{*}}\\
        \LIT{LISP}}{\}}%
      \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{pathname})}
  {
    \retval{Physical pathname} corresponding to (possibly logical)
    \VAR{pathname}. 
  }

  \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: