cosmetic surgery on loop figure; a few minor changes elsewhere

[clqr.git] / clqr-input-output.tex

% Copyright (C) 2008 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} \OPn{\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}} \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}}}
    \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 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}}})}
  {
  Return \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 \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}}
  {
  Current readtable.
  }

  \IT{\V*{\A read-base\A}\DF{\LIT{10}}}
  {
  Radix for reading \kwd{integer}s and \kwd{ratio}s.
  }

  \IT{\V*{\A read-default-float-format\A}\DF{\kwd{single-float}}}
  {
  Floating point format to use when not indicated in the number read. 
  }

  \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[Macro Chars]{Macro Characters and Escapes}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\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}}
    {Short title for a block of code.}

    \IT{\KWD{;;;} \VAR{intro}}
    {Description before a block of code.}

    \IT{\KWD{;;} \VAR{state}}
    {State of program or of following code.}

    \IT{\KWD{;} \VAR{explanation}}
    {Regarding line on which it appears.}

  \end{LIST}

  \IT{\KWD*{(}}
  {
  Initiate reading of a list.
  }

  \IT{\KWD{"}}\index{""}
  {
  Begin and end of a string.
  }

  \IT{\KWD*{'}\VAR{foo}}
  {
  (\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}, \KWD*{\#o}, \KWD*{\#x}, \KWD{\#}\VAR{n}\KWD{R}}
  {
  \index{\#R}%
  Binary, octal or hexadecimal number, or number of radix \VAR{n}. 
  }

  \IT{\KWD*{\#C(}\VAR{a b}\kwd{)}}
  {
    (\FU{complex} \VAR{a} \VAR{b}), the complex number $\VAR{a}+\VAR{b}\text{i}$.
  }

  \IT{\KWD*{\#'}\VAR{foo}}
  {
  (\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*{\#:}\VAR{foo}}
  {
  Uninterned Symbol \VAR{foo}.
  }

  \IT{\KWD*{\#.}\VAR{form}}
  {
  Read-time value of \VAR{form}.
  }

  \IT{\V*{\A read-eval\A}\DF{\T}}
  {
  If \NIL, a \kwd{reader-error} is signalled by \kwd{\#.}.
  }

  \IT{\KWD{\#}\VAR{label}\kwd{=} \VAR{foo}}
  {
  \index{\#=}%
  Give value of \VAR{foo} a \VAR{label}.
  }

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

  \IT{\KWD*{\#P}\VAR{foo}}
  {
  A pathname.
  }

  \IT{\KWD{\#\boldmath$<$}}
  {
  \index{\#<@\#$<$}%
  Have the reader signal an error.
  }

  \IT{\KWD*{\#+}\VAR{feature-expression} \VAR{form}}
  {
  Means \VAR{form} if \VAR{feature-expression} returns \T, means whitespace
  otherwise. 
  }

  \IT{\KWD*{\#--}\VAR{feature-expression} \VAR{form}}
  {
  Means whitespace if \VAR{feature-expression} returns \T, means \VAR{form} 
  otherwise. 
  }

  \IT{\arrGOO{%
      \kwd{\boldmath$|$}\OPn{\VAR{c}}\kwd{\boldmath$|$}\\
      \kwd{\boldmath$\backslash$}\VAR{c}%
    }{.}}
  {
    Treat arbitrary character(s) \VAR{c} as alphabetic preserving case.
  }
    \index{\@{$\backslash$}}%
    \index{\textbar\textbar@{$"|$}{$"|$}}%

\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 \retval{\VAR{foo}} to \VAR{stream} \FU{read}ably,
  \FU{read}ably after a newline and followed by a space,
  \FU{read}ably after a newline, or human-readably without any extra
  characters, respectively. 
  }

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

  \IT{(\MC*{PRINT-UNREADABLE-OBJECT} (\VAR{foo} \DES{\VAR{stream}}
    \orGOO{\kwd{:type } \VAR{bool}\\
      \kwd{:identity } \VAR{bool}}{\}})
    \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}}}
    \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 \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} \VAR{ int}\\
      \kwd{:level} \VAR{ int}\\
      \kwd{:lines} \VAR{ int}\\
      \kwd{:miser-width} \VAR{ int}\\
      \kwd{:pprint-dispatch} \VAR{ dispatch-table}\\
      \kwd{:pretty} \VAR{ bool}\\
      \kwd{:radix} \VAR{ bool}\\
      \kwd{:readably} \VAR{ bool}\\
      \kwd{:right-margin} \VAR{ int}\\
      \kwd{:stream } \DES{\VAR{stream}}\DF{\V{\A standard-output\A}}%
    }{\}})}
  {
  Print 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{(\xorGOO{\FU*{PPRINT-FILL}\\
      \FU*{PPRINT-LINEAR}}{\}}
    \DES{\VAR{stream}} \VAR{foo} \OP{\VAR{parenthesis}\DF{\T}
      \Op{\VAR{noop}}})}
  {
  Print \VAR{foo} to \VAR{stream}. If \VAR{foo} is a list, print as
  many elements per line as possible; or print either all elements on
  one line or each on its own line, respectively. Return \retval{\NIL}.
  }

  \IT{(\FU*{PPRINT-TABULAR} \DES{\VAR{stream}} \VAR{foo}
    \OP{\VAR{parenthesis}\DF{\T} \Op{\VAR{noop}
        \Op{\VAR{n}\DF{\LIT{16}}}}})}
  {
  Print \VAR{foo} to \VAR{stream}. If \VAR{foo} is a list, print
  elements in a table with column width \VAR{n} ems.  Return \retval{\NIL}.
  }

  \IT{(\MC*{PPRINT-LOGICAL-BLOCK} (\DES{\VAR{stream}} \VAR{list}
    \orGOO{\xorGOO{\kwd{:prefix} \VAR{ prefix}\\
        \kwd{:per-line-prefix} \VAR{ per-line-prefix}}{\}}\\
      \kwd{:suffix} \VAR{ suffix}\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
    list in \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}}
  {
  If \T, print arrays \FU{read}ably.
  }

  \IT{\V*{\A print-base\A}\DF{\LIT{10}}}
  {
  Radix for printing rationals, between 2 and 36.
  }

  \IT{\V*{\A print-case\A}\DF{\kwd{:upcase}}}
  {
  Print symbol names all uppercase (\kwd{:upcase}), all lowercase
  (\kwd{:downcase}), capitalized (\kwd{:capitalize}).
  }

  \IT{\V*{\A print-circle\A}\DF{\NIL}}
  {
  If \T, avoid indefinite recursion while printing circular
  structure. 
  }

  \IT{\V*{\A print-escape\A}\DF{\T}}
  {
  If \NIL, do not print escape characters and package prefixes.
  }

  \IT{\V*{\A print-gensym\A}\DF{\T}}
  {
  If \T, print \kwd{:\#} before uninterned symbols.
  }

  \IT{\arrGOO{\V*{\A print-length\A}\DF{\NIL}\\
      \V*{\A print-level\A}\DF{\NIL}}{.}}
  {
  If integer, restrict printing of objects to that number per
  level/to that depth.
  }

  \IT{\V*{\A print-lines\A}\DF{\NIL}}
  {
  Number of lines to pretty-print.
  }

  \IT{\V*{\A print-miser-width\A}}
  {
  Width below which a compact pretty-printing style is used.
  }

  \IT{\V*{\A print-pretty\A}}
  {
  If \T, print pretty.
  }

  \IT{\V*{\A print-radix\A}\DF{\NIL}}
  {
  If \T, print rationals with a radix indicator.
  }

  \IT{\V*{\A print-readably\A}\DF{\NIL}}
  {
  If \T, print \FU{read}ably or signal error
  \kwd{print-not-readable}. 
  }

  \IT{\V*{\A print-right-margin\A}\DF{\NIL}}
  {
  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}}})}
  {
  Highest priority \retval{\VAR{function}} associated with type of
  \VAR{foo}. 
  }

  \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}}
  {
  Current pretty print dispatch table.
  }

  \IT{\V*{\A read-suppress\A}\DF{\NIL}}
  {
  If \T, reader is syntactically more tolerant.
  }

\end{LIST}



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Format}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{section:Format}

\begin{LIST}{1cm}

  \IT{(\MC*{FORMATTER} \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}
    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}
    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}}}
    {
    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}
    Print integer argument as number (decimal, binary, octal, or
    hexadecimal, respectively). 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}
    Print argument as floating-point number. With \kwd{@}, always prepend 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}
    Print argument as floating-point number with \VAR{int-digits}
    before decimal point and \VAR{exp-digits} in the
    exponent. With \KWD{\TLD G}, chose either \KWD{\TLD E} or \KWD{\TLD F}. 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}
    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$()}
    Convert 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}
    If argument \kwd{eql} \LIT{1} print nothing, otherwise print \LIT{s};
    do the same after backing up one argument; if argument \kwd{eql} \LIT{1}
    print \LIT{y}, otherwise print \LIT{ies}; do the same after
    backing up one argument, respectively. 
  }

    \IT{\Goo{\KWD{\TLD\%}\XOR\KWD{\TLD}\VAR{n}\KWD{\%}}}
    {\index{~\%@$\sim$\%}
    Print one or \VAR{n} newline(s).
  }

    \IT{\Goo{\KWD{\TLD\&}\XOR\KWD{\TLD}\VAR{n}\KWD{\&}}}
    {\index{~\&@$\sim$\&}
    Print one or \VAR{n} newline(s) unless output stream is at the
    beginning of a line.
  }

    \IT{\Goo{\KWD{\TLD\_}\XOR\KWD{\TLD:\_}\XOR\KWD{\TLD@\_}\XOR\KWD{\TLD:@\_}}}
    {\index{~\_{}@$\sim$\_{}}
    Print 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$}
    {
    (Tilde-newline) Ignore newline and following
    whitespace. With \kwd{:}, ignore only newline; with \kwd{@},
    ignore only following whitespace.
  }

    \IT{\Goo{\KWD{\TLD\boldmath$|$}\XOR\KWD{\TLD}\VAR{n}\KWD{\boldmath$|$}}}
    {\index{~\textbar@$\sim${$"|$}}
    Print one or \VAR{n} page separator(s).
  }

    \IT{\Goo{\KWD{\TLD\TLD}\XOR\KWD{\TLD}\VAR{n}\KWD{\TLD}}}
    {\index{~~@$\sim$$\sim$}
    Print one or \VAR{n} tilde(s).
  }

    \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{text}\KWD{\TLD}\VAR{a},\VAR{b}\kwd{:;}}
      \Goos{\VAR{text}\KWD{\TLD;}}\VAR{text} \KWD{\TLD\boldmath{$>$}}}
    {\index{~< >@$\sim$$< >$}
    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.
  }

    \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}
    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{n}\DF{\LIT{0}}}\kwd{I}\XOR\KWD{\TLD}\Op{\VAR{n}\DF{\LIT{0}}}\kwd{:I}}}
    {\index{~ I@$\sim$I}
    Same as (\kwd{pprint-indent} \kwd{:block} \VAR{n}) or
    (\kwd{pprint-indent} \kwd{:current} \VAR{n}), respectively.
  }

    \IT{\KWD{\TLD}\Op{\VAR{n}\DF{\LIT{0}}}\Op{\KWD{:}}\Op{\KWD{@}}\KWD{\A}}
    {\index{~ *@$\sim$\A}
    Jump \VAR{n} arguments forward, or, with \kwd{:}, backward. With
    \kwd{@}, jump to argument \VAR{n}.
  }

    \IT{\KWD{\TLD}\Op{\VAR{limit}}\Op{\KWD{{:}}\Op{\kwd{@}}}%
      \KWD{\boldmath{$\{$}}\VAR{text}\KWD{\TLD\boldmath{$\}$}}}
    {\index{~\{\}@$\sim$$\{\}$}
    \VAR{text} is used repeatedly, up to \VAR{limit}, as control
    string for every element of argument, which should be a list. With
    \kwd{@}, take all remaining arguments. With \kwd{:}, argument should be
    a list of sublists. At each iteration step the elements of a new
    sublist are used by \VAR{text}. 
  }

    \IT{\KWD{\TLD\^{}}}
    {\index{~\^{}@$\sim$\^{}}
    Leave immediately \kwd{\TLD\boldmath{$<$} \TLD\boldmath{$>$}} or
    \kwd{\TLD\boldmath{$\{$} \TLD\boldmath{$\}$}}.
  }

    \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$[ ]}
    The \VAR{text}s are format control subclauses the zero-indexed argumenth (or the
    \VAR{i}th if given) of which is chosen. With \kwd{:}, the argument
    is boolean and takes first \VAR{text} for \NIL\ and second
    \VAR{text} for \T. With \kwd{@}, the argument is boolean and if \T, takes
    the only \VAR{text} and remains to be read; no \VAR{text} is
    chosen and the argument isu sed up if it is \NIL.
  }

    \IT{\KWD{\TLD\Op{@}?}}
    {\index{~ ?@$\sim$?}
    Process two arguments as format string and argument list. With
    \kwd{@}, take one argument as format string and use then the
    original argument list.
  }

    \IT{\KWD{\TLD}\OP{\VAR{prefix}\Goos{\kwd{,} \VAR{prefix}}}\Op{\kwd{:}}\Op{\kwd{@}}\KWD{/}\VAR{function}\KWD{/}}
    {\index{~//@$\sim$//}
    Call \VAR{function} with the arguments stream, format-ar\-gu\-ment,
    bool-colon, bool-at and \VAR{prefix}es for printing format-argument.
  }

    \IT{\KWD{\TLD\Op{:}\Op{@}W}}
    {\index{~ W@$\sim$W}
    Print 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}
    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} \VAR{ type}\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}{.}\\
      \kwd{:if-does-not exist} \xorGOO{\kwd{:error}\\
        \kwd{:create}\\
        \NIL}{.}\\
      \kwd{:external-format } \VAR{format}\DF{\kwd{:default}}%
    }{\}})}
  {
  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}
    \orGOO{\kwd{:start}\VAR{ start}\DF{\LIT{0}}\\
      \kwd{:end} \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}/\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*{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-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}\\
      \kwd{:end} \VAR{ end}}{\}}) \OPn{(\kwd{declare}
      \OPn{\NEV{\VAR{decl}}})} \PROGN{\VAR{form}})}
  {
  Evaluate \VAR{form}s with \VAR{foo} locally bound to input stream
  from \VAR{string}. \VAR{index} contains the reading position in
  \VAR{string} after leaving. Return \retval{values of \VAR{form}s}. 
  }

  \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 output
  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}}
  {
  Bidirectional stream to user terminal.
  }

  \IT{\arrGOO{\V*{\A standard-input\A}\\
      \V*{\A standard-output\A}\\
      \V*{\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}}{.}}
  {
  Streams for debugging and user interaction.
  }

\end{LIST}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Files} 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{LIST}{1cm}

  \IT{(\FU*{MAKE-PATHNAME} 
    \orGOO{\kwd{:host} \VAR{ host}\\
      \kwd{:device} \VAR{ dev}\\
      \kwd{:directory} \VAR{ dir}\\
      \kwd{:name} \VAR{ name}\\
      \kwd{:type} \VAR{ type}\\
      \kwd{:version} \VAR{ ver}\\
      \kwd{:defaults} \VAR{ path}\\
      \kwd{:case
        \Goo{\kwd{:local}\XOR\kwd{:common}}\DF{\kwd{:local}}}}{\}})}
  {
  Construct \retval{pathname}.
  }

  \IT{(\FU*{MERGE-PATHNAMES} \VAR{pathname}
    \OP{\VAR{default-pathname}\DF{\V{\A default-pathname-defaults\A}}
      \Op{\VAR{version}\DF{\kwd{:newest}}}})}
  {
  Return \retval{\VAR{pathname}} after filling in missing parts from defaults.
  }

  \IT{\V*{\A default-pathname-defaults\A}}
  {
  Pathname to use if one is needed but none supplied.
  }

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

  \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*{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{(\xorGOO{\FU*{PATHNAME-HOST}\\
      \FU*{PATHNAME-DEVICE}\\
      \FU*{PATHNAME-DIRECTORY}\\
      \FU*{PATHNAME-NAME}\\
      \FU*{PATHNAME-TYPE}\\
      \FU*{PATHNAME-VERSION}}{\}}
    \VAR{path}
    \Op{\kwd{:case} \xorGOO{\kwd{:local}\\
        \kwd{:common}}{\}}\DF{\kwd{:local}}})}
  {
  Return \retval{pathname component}.
  }

  \IT{(\FU*{LOGICAL-PATHNAME} \VAR{path})}
  {
  \retval{Logical name} of \VAR{path}.
  }

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

  \IT{(\FU*{LOGICAL-PATHNAME-TRANSLATIONS} \VAR{host})}
  {
  \retval{\VAR{host}'s list of translations}. \kwd{setf}able.
  }

  \IT{(\FU*{LOAD-LOGICAL-PATHNAME-TRANSLATIONS} \VAR{host})}
  {
  Load \VAR{host}'s translations. Return \retval{\NIL} if already
  loaded, return \retval{\T} if successful.
  }

  \IT{(\FU*{TRANSLATE-LOGICAL-PATHNAME} \VAR{path})}
  {
  Physical \retval{pathname} of \VAR{path}. 
  }

  \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 error, respectively.
  }

  \IT{(\FU*{FILE-WRITE-DATE} \VAR{file})}
  {
  \retval{Time} at which \VAR{file} was last written.
  }

  \IT{(\FU*{FILE-AUTHOR} \VAR{file})}
  {
  Return \retval{name of \VAR{file} owner}.
  }

  \IT{(\FU*{FILE-LENGTH} \VAR{stream})}
  {
  Return \retval{length of \VAR{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*{RENAME-FILE} \VAR{foo} \VAR{bar})}
  {
  Rename file  \VAR{foo} to \VAR{bar}. Unspecified parts of path
  \VAR{bar} default to those of \VAR{foo}. Return \retval{new
    pathname}, \retvalii{old file name}, and \retvaliii{new file name}.
  }

  \IT{(\FU*{DELETE-FILE} \VAR{file})}
  {
  Delete \VAR{file}, return \retval{\T}.
  }

  \IT{(\FU*{DIRECTORY} \VAR{path})}
  {
  Return \retval{list of pathnames}.
  }

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

  \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{(\FU*{USER-HOMEDIR-PATHNAME} \Op{\VAR{host}})}
  {
  User's \retval{home directory}.
  }


\end{LIST}



% LocalWords:  ies argumenth ar gu ment