changed define-symbol-macro entry

[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{*standard-input*}} \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 \retvalii{position} of
  next character.
  }

  \IT{(\FU*{READ-DELIMITED-LIST} \VAR{char}
    \OP{\DES{\VAR{stream}}\DF{\V{*standard-input*}}
      \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{*standard-input*}}
      \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{*standard-input*}}
      \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{*standard-input*}} 
      \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{*standard-input*}}})}
  {
  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{*standard-input*}}
      \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})}
  {
  \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{*readtable*}}
    \Op{\VAR{to}\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{*readtable*}}
      \Op{\VAR{from-readtable}\DF{standard readtable}}})}
  {
  Copy syntax of \VAR{from-char} to \VAR{to-readtable}. Return \retval{\T}.
  }

  \IT{\V*{*readtable*}}
  {
  Current readtable.
  }

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

  \IT{\V*{*read-default-float-format*}\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{*readtable*}}}})}
  {
  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{*readtable*}}})}
  {
  \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{*readtable*}}}})}
  {
  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{*readtable*}}})}
  {
  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{*readtable*}}})}
  {
  \retval{Dispatch function} associated with \VAR{char} followed by \VAR{sub-char}.
  }

\end{LIST}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection[Macro Chars]{Macro Characters}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{LIST}{1cm}

  \IT{\arrGOO{\KWD*{; }\OPn{\VAR{comment}}\\
      \KWD{\#\boldmath$|$ }\OPn{\VAR{comment}}\KWD{ \boldmath$|$\#}}{.}}
  {
  Comments.
  }

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

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

  \IT{\KWD*{'}\VAR{foo}}
  {
  \retval{(\SO{quote} \NEV{\VAR{foo}})}.
  }

  \IT{\KWD*{`}(\Op{\VAR{foo}} \Op{\KWD*{,}\VAR{bar}} \Op{\KWD*{,@}\VAR{baz}}
    \Op{\KWD*{,.}\DES{\VAR{quux}}} \Op{\VAR{bing}})}
  {
  \SO{quote} \VAR{foo} and \VAR{bing}; evaluate \VAR{bar} and splice
  the lists \VAR{baz} and \VAR{quux} into their elements. 
  }

  \IT{\KWD{\#\boldmath{$\backslash$}}\VAR{c}}
  {
  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 base \VAR{n}. 
  }

  \IT{\KWD*{\#C(}\VAR{a b}\kwd{)}}
  {Complex number \VAR{a}$+$\VAR{b}i.
  }

  \IT{\KWD*{\#'}\VAR{foo}}
  {
  Return \retval{function named \VAR{foo}}.
  }

  \IT{\KWD{\#}\VAR{n}\KWD{A}\OPn{\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{*}\OPn{\VAR{b}}}
  {
  \index{\#*}%
  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*{*read-eval*}\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{\#\#}%
  \retval{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 \VAR{form} if \VAR{feature-expression} returns \NIL, means whitespace
  otherwise. 
  }

\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{*standard-output*}}})}
  {
  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{(\FU*{PRINT-UNREADABLE-OBJECT} (\VAR{foo} \DES{\VAR{stream}}
    \Op{\kwd{:type} \VAR{bool}} \Op{\kwd{:identity} \VAR{bool}})
    \OPn{\VAR{form}})}
  {
  Enclosed in \kwd{\#\boldmath$<$} and \kwd{\boldmath$>$}, print
  \VAR{foo} by means of \VAR{form}s. Return \retval{\NIL}. 
  }

  \IT{(\FU*{TERPRI} \Op{\DES{\VAR{stream}}\DF{\V{*standard-output*}}})}
  {
  Output a newline to \VAR{stream}. Return \retval{\NIL}.
  }

  \IT{(\FU*{FRESH-LINE})
    \Op{\DES{\VAR{stream}}\DF{\V{*standard-output*}}}}
  {
  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{*standard-output*}}})}
  {
  Output \retval{\VAR{char}} to \VAR{stream}.
  }

  \IT{(\xorGOO{\FU*{WRITE-STRING}\\
      \FU*{WRITE-LINE}}{\}} \VAR{string}
    \OP{\DES{\VAR{stream}}\DF{\V{*standard-output*}}}
    \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,
  respectively. 
  }

  \IT{(\FU*{WRITE-BYTE} \VAR{byte} \DES{\VAR{stream}})}
  {
  Write one \retval{\VAR{byte}} to \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{*standard-output*}}%
    }{\}})}
  {
  Print and return \retval{\VAR{foo}}, or print \VAR{foo} into
  \retval{string}, respectively, after dynamically setting printer variables
  corresponding to keyword parameters (\kwd{:}\VAR{bar} becoming
  \kwd{*print-}\VAR{bar}\kwd{*}). (\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}}})} \OPn{\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}.
  }

  \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{*print-length*} or \V{*print-circle*} indicate
    printing should end, send element together with an appropriate
    indicator to \VAR{stream}. 
  }

    \IT{(\FU*{PPRINT-TAB} \Goo{\kwd{:line}\XOR\kwd{:line-relative}%
        \XOR\kwd{:section}\XOR\kwd{:section-relative}} \VAR{c}
      \VAR{i} \Op{\DES{\VAR{stream}}\DF{\V{*standard-output*}}})}
    {
    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{*standard-output*}}})}
    {
    Specify indentation for innermost logical block. Return \retval{\NIL}.
  }

    \IT{(\kwd*{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{*standard-output*}}})}
  {
  Print a conditional newline. Return \retval{\NIL}.
  }

  \IT{(\FU*{SET-PPRINT-DISPATCH} \VAR{type} \VAR{function}
    \OP{\VAR{priority}\DF{\LIT{0}}
      \Op{\VAR{table}\DF{\V{*print-pprint-dispatch*}}}})}
  {
  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{*print-pprint-dispatch*}}})}
  {
  Highest priority \retval{\VAR{function}} associated with type of
  \VAR{foo}. 
  }

  \IT{(\FU*{COPY-PPRINT-DISPATCH}
    \Op{\VAR{table}\DF{\V{*print-pprint-dispatch*}}})}
  {
  Return \retval{copy of \VAR{table}}.
  }

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

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

  \IT{\V*{*print-right-margin*}\DF{\NIL}}
  {
  Right margin width in ems while pretty-printing.
  }

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

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

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

  \IT{\V*{*print-array*}}
  {
  If \T, print array \FU{read}ably.
  }

  \IT{\V*{*print-level*}\DF{\NIL}}
  {
  If integer, restrict printing of nested object to that depth.
  }

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

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

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

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

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

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

  \IT{\V*{*print-pprint-dispatch*}}
  {
  Current pretty print dispatch table.
  }

  \IT{\V*{*read-suppress*}\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{*standard-output*}. 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{,}\VAR{col-inc}\DF{\LIT{1}}
          \Op{\KWD{,}\VAR{min-pad}\DF{\LIT{0}}
            \Op{\KWD{,}\VAR{pad-char}\DF{\LIT{\#$\backslash$Space}}}}}}
      \KWD{\Op{:}\Op{@}\Goo{A\XOR S}}}
    {
    Print argument of any type for consumption by humans/by the
    reader, respectively. With \kwd{@}, add \VAR{pad-char}s on the left
    rather than on the right. With \kwd{:} print \NIL\ as \LIT{()} rather
    than \LIT{nil}.
  }

    \IT{\KWD{\TLD}\Op{\VAR{radix}\DF{\LIT{10}} \Op{\KWD{,}\VAR{width}
          \Op{\KWD{,}\VAR{pad-char}\DF{\LIT{\#$\backslash$Space}}
            \Op{\KWD{,}\VAR{comma-char}\DF{\KWD{,}}
              \Op{\KWD{,}\VAR{comma-interval}\DF{\LIT{3}}}}}}}
      \KWD{\Op{:}\Op{@}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{,}\VAR{pad-char}\DF{\LIT{\#$\backslash$Space}}
          \Op{\KWD{,}\VAR{comma-char}\DF{\KWD{,}}
            \Op{\KWD{,}\VAR{comma-interval}\DF{\LIT{3}}}}}} \KWD{\Op{:}\Op{@}\Goo{D\XOR
          B\XOR O\XOR 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{,}\VAR{dec-digits} \Op{\KWD{,}\VAR{shift}\DF{\LIT{0}}
            \Op{\KWD{,}\VAR{overflow-char}
              \Op{\KWD{,}\VAR{pad-char}\DF{\LIT{\#$\backslash$Space}}}}}}}
      \KWD{\Op{@}F}}
    {
    Print argument as floating-point number. With \kwd{@}, always prepend a sign.
  }

    \IT{\KWD{\TLD}\Op{\VAR{width} \Op{\KWD{,}\VAR{int-digits} \Op{\KWD{,}\VAR{exp-digits}
            \Op{\KWD{,}\VAR{scale-factor}\DF{\LIT{1}} \Op{\KWD{,}\VAR{overflow-char}
                \Op{\KWD{,}\VAR{pad-char}\DF{\LIT{\#$\backslash$Space}}
                  \Op{\KWD{,}\VAR{exp-char}}}}}}}}
      \KWD{\Op{@}\Goo{E\XOR  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}}}
    {
    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)}}}
    {
    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}}}
    {
    If argument \kwd{eql} 1 print nothing, otherwise print \LIT{s};
    do the same after backing up one argument; if argument \kwd{eql} 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{\%}}}
    {
    Print one or \VAR{n} newline(s).
  }

    \IT{\Goo{\KWD{\TLD\&}\XOR\KWD{\TLD}\VAR{n}\KWD{\&}}}
    {
    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}:@\_}}
    {
    Print newline like \kwd{pprint-newline} with argument
    \kwd{:linear}, \kwd{:fill}, \kwd{:miser}, or \kwd{:mandatory}, respectively.
  }

    \IT{\KWD{\TLD}\Op{\KWD{@}}$\hookleftarrow$}
    {
    (Tilde-newline) Ignore newline and following
    whitespace. With \kwd{@}, ignore only newline.
  }

    \IT{\Goo{\KWD{\TLD\boldmath$|$}\XOR\KWD{\TLD}\VAR{n}\KWD{\boldmath$|$}}}
    {
    Print one or \VAR{n} page separator(s).
  }

    \IT{\Goo{\KWD{\TLD\TLD}\XOR\KWD{\TLD}\VAR{n}\KWD{\TLD}}}
    {
    Print one or \VAR{n} tilde(s).
  }

    \IT{\KWD{\TLD}\Op{\VAR{min-col}\DF{\LIT{0}}
        \Op{\KWD{,}\VAR{col-inc}\DF{\LIT{1}}
          \Op{\KWD{,}\VAR{min-pad}\DF{\LIT{0}}
            \Op{\KWD{,}\VAR{pad-char}\DF{\LIT{\#$\backslash$Space}}}}}}
      \KWD{\Op{:}\Op{@}\boldmath{$<$}} 
      \Op{\VAR{text}\KWD{\TLD}\VAR{a},\VAR{b}\kwd{:;}}
      \Goos{\VAR{text}\KWD{\TLD;}} \KWD{\TLD\boldmath{$>$}}}
    {
    Justify text produced by \VAR{text}s in a field of at least
    \VAR{min-col} columns.
  }

    \IT{\KWD{\TLD}\Op{\VAR{c}\Op{\KWD{,}\VAR{i}}}\Op{\KWD{:}}\Op{\KWD{@}}\KWD{T}}
    {
    Move cursor forward to column number $c + ki$, $k \geq 0$ being as small
    as possible.
  }

    \IT{\Goo{\KWD{\TLD}\Op{\VAR{n}\DF{\LIT{0}}}\kwd{I}\XOR\KWD{\TLD}\Op{\VAR{n}\DF{\LIT{0}}}\kwd{: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{*}}
    {
    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{$\}$}}}
    {
    \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
    sublist can be used by \VAR{str}. 
  }

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

    \IT{\KWD{\TLD}\Op{\VAR{i}}\Op{\KWD{:}}\Op{\KWD{@}}\KWD{[}\Goos{\VAR{text}\KWD{\TLD;}}\KWD{\TLD]}}
    {
    The \VAR{text}s are clauses the 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.
  }

    \IT{\KWD{\TLD\Op{@}?}}
    {
    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{:}\Op{@}/}\VAR{function}\KWD{/}}
    {
    Call \VAR{function} with arguments stream, format-ar\-gu\-ment,
    bool-colon, and bool-at for printing format-argument.
  }

    \IT{\KWD{\TLD\Op{:}\Op{@}W}}
    {
    Print obeying every printer control variable. With \kwd{:},
    pretty-print. With \kwd{@}, print without limits on length or depth.
  }

    \IT{\KWD{V}}
    {
    (Replacing one of the comma-separated prefix parameters) Take next
    argument as prefix parameter.
  }

    \IT{\KWD{\#}}
    {
    (Replacing one of the comma-separated prefix parameters) Take as
    prefix parameter the number of remaining unprocessed arguments.
  }

  \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{stream to \VAR{path}}.
  }

  \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{(\FU*{MAKE-STRING-OUTPUT-STREAM} \Op{\kwd{:element-type}
      \VAR{type}\DF{\kwd{character}}})}
  {
  Return a \retval{string stream} accepting characters.
  }

  \IT{(\FU*{GET-OUTPUT-STREAM-STRING} \DES{\VAR{string-stream}})}
  {
  Clear and return as a \retval{string} characters on \VAR{string-stream}.
  }

  \IT{(\FU*{MAKE-CONCATENATED-STREAM} \OPn{\VAR{stream}})}
  {
  Return \retval{concatenated stream}.
  }

  \IT{(\FU*{CONCATENATED-STREAM-STREAMS} \VAR{concatenated-stream})}
  {
  Return \retval{list of streams} \VAR{concatenated-stream} still
  has to read from. 
  }

  \IT{(\FU*{MAKE-BROADCAST-STREAM} \OPn{\VAR{stream}})}
  {
  Return \retval{broadcast stream}.
  }

  \IT{(\FU*{BROADCAST-STREAM-STREAMS} \VAR{broadcast-stream})}
  {
  Return \retval{list of streams} \VAR{broadcast-stream} is
  broadcasting to. 
  }

  \IT{(\FU*{MAKE-ECHO-STREAM} \VAR{input-stream} \VAR{output-stream})}
  {
  Place \retval{echo stream} between \VAR{input-stream} and
  \VAR{output-stream}. 
  }

  \IT{\arrGOO{(\FU*{ECHO-STREAM-INPUT-STREAM}\VAR{ echo-stream})\\
      (\FU*{ECHO-STREAM-OUTPUT-STREAM}\VAR{ echo-stream})}{.}}
  {
  Return \retval{stream} \VAR{echo-stream} receives from or sends
  to, respectively.
  }

  \IT{(\FU*{MAKE-STRING-INPUT-STREAM} \VAR{string}
    \orGOO{\kwd{:start}\VAR{ start}\\
      \kwd{:end} \VAR{ end}}{\}})}
  {
  Return \retval{stream} supplying the characters from \VAR{string}.
  }

  \IT{(\FU*{MAKE-SYNONYM-STREAM} \VAR{symbol})}
  {
  Return \retval{synonym stream}.
  }

  \IT{(\FU*{SYNONYM-STREAM-SYMBOL} \VAR{synonym-stream})}
  {
  Return \retval{symbol} of \VAR{synonym-stream}.
  }

  \IT{(\FU*{MAKE-TWO-WAY-STREAM} \VAR{input-stream}
    \VAR{output-stream})}
  {Return \retval{two-way stream}.
  }

  \IT{\arrGOO{(\FU*{TWO-WAY-STREAM-INPUT-STREAM} \VAR{
        two-way-stream})\\ 
      (\FU*{TWO-WAY-STREAM-OUTPUT-STREAM} \VAR{ two-way-stream})}{.}}
  {
  Return \retval{stream} \VAR{two-way-stream} receives from or sends
  to, respectively.
  }

  \IT{(\FU*{LISTEN} \Op{\VAR{stream}\DF{\V{*standard-input*}}})}
  {
  \retval{\T} if there is a character in input \VAR{stream}.
  }

  \IT{(\FU*{CLEAR-INPUT}
    \Op{\DES{\VAR{stream}}\DF{\V{*standard-input*}}})}
  {
  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{*standard-output*}}})}
  {
  End output to \VAR{stream} and return \retval{\NIL} immediately,
  after initiating flushing of buffers, or after flushing of buffers,
  respectively. 
  }

  \IT{(\MC*{WITH-OPEN-STREAM} (\VAR{foo} \DES{\VAR{stream}})
    \OPn{(\kwd{declare} \OPn{\NEV{\VAR{decl}}})} \OPn{\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}}})} \OPn{\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}}})} \OPn{\VAR{form}})}
  {
  Evaluate \VAR{form}s with \VAR{foo} locally bound to output
  stream. Append output to \VAR{string} and return \retval{value of
    \VAR{foo}} 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*{*terminal-io*}}
  {
  Bidirectional stream to user terminal.
  }

  \IT{\arrGOO{\V*{*standard-input*}\\
      \V*{*standard-output*}\\
      \V*{*error-output*}}{.}}
  {
  Standard input stream, standard output stream, 
  or standard error output stream, respectively.
  }

  \IT{\arrGOO{\V*{*debug-io*}\\
      \V*{*query-io*}}{.}}
  {
  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{*default-pathname-defaults*}}
      \Op{\VAR{version}\DF{\kwd{:newest}}}})}
  {
  Return \retval{\VAR{pathname}} after filling in missing parts from defaults.
  }

  \IT{\V*{*default-pathname-defaults*}}
  {
  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{*default-pathname-defaults*}}})}
  {
  Return \retval{minimal path string} to sufficiently describe 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{*default-pathname-defaults*}}}} 
    \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}.
  }

  \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}}})}
    \OPn{\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