CLOS-related initargs don't need to be keywords
[clqr.git] / clqr-input-output.tex
bloba8b30b6d7b2435dc8d9e4da0d4bff9411b331c36
1 % Copyright (C) 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2018
2 % Bert Burgemeister
4 % Permission is granted to copy, distribute and/or modify this
5 % document under the terms of the GNU Free Documentation License,
6 % Version 1.2; with no Invariant Sections, no Front-Cover Texts and
7 % no Back-Cover Texts. For details see file COPYING.
10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
11 \section{Input/Output}
12 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
14 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
15 \subsection{Predicates}
16 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
18 \begin{LIST}{1cm}
20 \IT{\arrGOO{(\FU*{STREAMP} \VAR{ foo})\\
21 (\FU*{PATHNAMEP} \VAR{ foo})\\
22 (\FU*{READTABLEP} \VAR{ foo})}{.}}
24 \retval{\T} if \VAR{foo} is of indicated type.
27 \IT{\arrGOO{(\FU*{INPUT-STREAM-P} \VAR{ stream})\\
28 (\FU*{OUTPUT-STREAM-P} \VAR{ stream})\\
29 (\FU*{INTERACTIVE-STREAM-P} \VAR{ stream})\\
30 (\FU*{OPEN-STREAM-P} \VAR{ stream})}{.}}
32 Return \retval{\T} if \VAR{stream} is for input, for output,
33 interactive, or open, respectively.
36 \IT{(\FU*{PATHNAME-MATCH-P} \VAR{path} \VAR{wildcard})}
38 \retval{\T} if \VAR{path} matches \VAR{wildcard}.
41 \IT{(\FU*{WILD-PATHNAME-P} \VAR{path}
42 \OP{\Goo{\kwd{:host}\XOR
43 \kwd{:device}\XOR
44 \kwd{:directory}\XOR
45 \kwd{:name}\XOR
46 \kwd{:type}\XOR
47 \kwd{:version}\XOR\NIL}})}
49 Return \retval{\T} if indicated component in \VAR{path} is
50 wildcard. (\NIL\ indicates any component.)
53 \end{LIST}
56 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
57 \subsection{Reader}
58 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
60 \begin{LIST}{1cm}
62 \IT{(\xorGOO{\FU*{Y-OR-N-P}\\
63 \FU*{YES-OR-NO-P}}{\}} \Op{\VAR{control} \OPn{\VAR{arg}}})}
65 Ask user a question and return \retval{\T} or \retval{\NIL}
66 depending on their answer. See page \pageref{section:Format},
67 \FU{format}, for \VAR{control} and \VAR{arg}s.
70 \IT{(\MC*{WITH-STANDARD-IO-SYNTAX} \PROGN{\VAR{form}})}
72 Evaluate \VAR{form}s with standard behaviour of reader and
73 printer. Return \retval{values of \VAR{form}s}.
76 \IT{(\xorGOO{\FU*{READ}\\
77 \FU*{READ-PRESERVING-WHITESPACE}}{\}}
78 \OP{\DES{\VAR{stream}}\DF{\V{\A standard-input\A}} % standard-input not explicitly in standard
79 \OP{\VAR{eof-err}\DF{\T}
80 \Op{\VAR{eof-val}\DF{\NIL} \Op{\VAR{recursive}\DF{\NIL}}}}})}
82 Read printed representation of \retval{object}.
85 \IT{(\FU*{READ-FROM-STRING} \VAR{string}
86 \OP{\VAR{eof-error}\DF{\T}
87 \OP{\VAR{eof-val}\DF{\NIL}
88 \OP{\orGOO{%
89 \kwd{:start}\VAR{ start}\DF{\LIT{0}}\\
90 \kwd{:end}\VAR{ end}\DF{\NIL}\\
91 \kwd{:preserve-whitespace}\VAR{ bool}\DF{\NIL}}{\}}}}})}
93 Return \retval{object} read from string and zero-indexed \retvalii{position} of
94 next character.
97 \IT{(\FU*{READ-DELIMITED-LIST} \VAR{char}
98 \OP{\DES{\VAR{stream}}\DF{\V{\A standard-input\A}}
99 \Op{\VAR{recursive}\DF{\NIL}}})}
101 Continue reading until encountering \VAR{char}. Return \retval{list}
102 of objects read. Signal error if no \VAR{char} is found in stream.
105 \IT{(\FU*{READ-CHAR} \OP{\DES{\VAR{stream}}\DF{\V{\A standard-input\A}}
106 \OP{\VAR{eof-err}\DF{\T} \Op{\VAR{eof-val}\DF{\NIL}
107 \Op{\VAR{recursive}\DF{\NIL}}}}})}
109 Return \retval{next character} from \VAR{stream}.
112 \IT{(\FU*{READ-CHAR-NO-HANG}
113 \OP{\DES{\VAR{stream}}\DF{\V{\A standard-input\A}}
114 \OP{\VAR{eof-error}\DF{\T} \Op{\VAR{eof-val}\DF{\NIL}
115 \Op{\VAR{recursive}\DF{\NIL}}}}})}
117 \retval{Next character} from \VAR{stream} or \retval{\NIL} if none
118 is available.
121 \IT{(\FU*{PEEK-CHAR}
122 \OP{\VAR{mode}\DF{\NIL} \OP{\DES{\VAR{stream}}\DF{\V{\A standard-input\A}}
123 \OP{\VAR{eof-error}\DF{\T} \Op{\VAR{eof-val}\DF{\NIL}
124 \Op{\VAR{recursive}\DF{\NIL}}}}}})}
126 Next, or if \VAR{mode} is \T, next non-whitespace
127 \retval{character}, or if \VAR{mode} is a character, \retval{next instance}
128 of it, from \VAR{stream} without removing it there.
131 \IT{(\FU*{UNREAD-CHAR} \VAR{character}
132 \Op{\DES{\VAR{stream}}\DF{\V{\A standard-input\A}}})}
134 Put last \FU{read-char}ed \VAR{character} back into \VAR{stream}; return
135 \retval{\NIL}.
138 \IT{(\FU*{READ-BYTE} \DES{\VAR{stream}} \OP{\VAR{eof-err}\DF{\T}
139 \Op{\VAR{eof-val}\DF{\NIL}}})}
141 Read \retval{next byte} from binary \VAR{stream}.
144 \IT{(\FU*{READ-LINE} \OP{\DES{\VAR{stream}}\DF{\V{\A standard-input\A}}
145 \OP{\VAR{eof-err}\DF{\T} \Op{\VAR{eof-val}\DF{\NIL}
146 \Op{\VAR{recursive}\DF{\NIL}}}}})}
148 Return a \retval{line of text} from \VAR{stream} and
149 \retvalii{\T} if line has been ended by end of file.
152 \IT{(\FU*{READ-SEQUENCE} \DES{\VAR{sequence}} \DES{\VAR{stream}}
153 \Op{\kwd{:start} \VAR{start}\DF{\LIT{0}}}\Op{\kwd{:end}
154 \VAR{end}\DF{\NIL}})}
156 Replace elements of \VAR{sequence} between \VAR{start} and \VAR{end}
157 with elements from binary or character \VAR{stream}. Return
158 \retval{index} of \VAR{sequence}'s first unmodified element.
161 \IT{(\FU*{READTABLE-CASE} \VAR{readtable})\DF{\kwd{:upcase}}}
163 \retval{Case sensitivity attribute} (one of \kwd{:upcase},
164 \kwd{:downcase}, \kwd{:preserve}, \kwd{:invert}) of
165 \VAR{readtable}. \kwd{setf}able.
168 \IT{(\FU*{COPY-READTABLE} \OP{\VAR{from-readtable}\DF{\V{\A readtable\A}}
169 \Op{\DES{\VAR{to-readtable}}\DF{\NIL}}})}
171 Return \retval{copy of \VAR{from-readtable}}.
174 \IT{(\FU*{SET-SYNTAX-FROM-CHAR} \VAR{to-char} \VAR{from-char}
175 \OP{\DES{\VAR{to-readtable}}\DF{\V{\A readtable\A}}
176 \Op{\VAR{from-readtable}\DF{standard readtable}}})}
178 Copy syntax of \VAR{from-char} to \VAR{to-readtable}. Return \retval{\T}.
181 \IT{\V{\A readtable\A}}
182 {\index{*READTABLE*@\A READTABLE\A}
183 Current readtable.
186 \IT{\V{\A read-base\A}\DF{\LIT{10}}}
187 {\index{*READ-BASE*@\A READ-BASE\A}
188 Radix for reading \kwd{integer}s and \kwd{ratio}s.
191 \IT{\V{\A read-default-float-format\A}\DF{\kwd{single-float}}}
192 {\index{*READ-DEFAULT-FLOAT-FORMAT*@\A READ-DEFAULT-FLOAT-FORMAT\A}
193 Floating point format to use when not indicated in the number read.
196 \IT{\V{\A read-suppress\A}\DF{\NIL}}
197 {\index{*READ-SUPPRESS*@\A READ-SUPPRESS\A}
198 If \T, reader is syntactically more tolerant.
201 \IT{(\FU*{SET-MACRO-CHARACTER} \VAR{char} \VAR{function}
202 \OP{\VAR{non-term-p}\DF{\NIL}
203 \Op{\DES{\VAR{rt}}\DF{\V{\A readtable\A}}}})}
205 Make \VAR{char} a macro character associated with
206 \VAR{function} of stream and \VAR{char}. Return \retval{\T}.
209 \IT{(\FU*{GET-MACRO-CHARACTER} \VAR{char}
210 \Op{\VAR{rt}\DF{\V{\A readtable\A}}})}
212 \retval{Reader macro function} associated with \VAR{char}, and
213 \retvalii{\T} if \VAR{char} is a non-terminating macro character.
216 \IT{(\FU*{MAKE-DISPATCH-MACRO-CHARACTER} \VAR{char}
217 \OP{\VAR{non-term-p}\DF{\NIL}
218 \Op{\VAR{rt}\DF{\V{\A readtable\A}}}})}
220 Make \VAR{char} a dispatching macro character. Return \retval{\T}.
223 \IT{(\FU*{SET-DISPATCH-MACRO-CHARACTER} \VAR{char} \VAR{sub-char}
224 \VAR{function}
225 \Op{\DES{\VAR{rt}}\DF{\V{\A readtable\A}}})}
227 Make \VAR{function} of stream, \VAR{n}, \VAR{sub-char} a dispatch
228 function of \VAR{char} followed by \VAR{n}, followed by
229 \VAR{sub-char}. Return \retval{\T}.
232 \IT{(\FU*{GET-DISPATCH-MACRO-CHARACTER} \VAR{char} \VAR{sub-char}
233 \Op{\VAR{rt}\DF{\V{\A readtable\A}}})}
235 \retval{Dispatch function} associated with \VAR{char} followed by
236 \VAR{sub-char}.
239 \end{LIST}
241 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
242 \subsection{Character Syntax}
243 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
245 \begin{LIST}{1cm}
247 \IT{\arrGOO{%
248 \KWD{\#\boldmath$|$ }\OPn{\VAR{multi-line-comment}}\KWD{ \boldmath$|$\#}\\
249 \KWD*{; }\OPn{\VAR{one-line-comment}}}{.}}
250 {\index{\#{$"|$} {$"|$}\#}
251 Comments. There are stylistic conventions:
253 \begin{LIST}{.5cm}
254 \IT{\KWD{;;;;} \VAR{title}\qquad\qquad}
255 {Short title for a block of code.}
257 \IT{\KWD{;;;} \VAR{intro}\qquad\qquad}
258 {Description before a block of code.}
260 \IT{\KWD{;;} \VAR{state}\qquad\qquad}
261 {State of program or of following code.}
263 \IT{\arrGOO{%
264 \KWD{;}\VAR{explanation}\\
265 \KWD{;}\VAR{ continuation}}{.}}
266 {Regarding line on which it appears.}
268 \end{LIST}
270 \IT{\KWD*{(}\OPn{\VAR{foo}}\Op{ \KWD*{.} \VAR{bar}\DF{\NIL}}\KWD*{)}}
272 List of \VAR{foo}s with the terminating cdr \VAR{bar}.
275 \IT{\KWD{"}\qquad\qquad}
276 {\index{""}
277 Begin and end of a string.
280 \IT{\KWD*{'}\VAR{foo}\quad\qquad}
282 (\SO*{quote} \VAR{foo}); \VAR{foo} unevaluated.
285 \IT{\KWD{\char18}(\Op{\VAR{foo}} \Op{\KWD*{,}\VAR{bar}} \Op{\KWD{,@}\VAR{baz}}
286 \Op{\KWD*{,.}\DES{\VAR{quux}}} \Op{\VAR{bing}})}
287 {\index{,"@}\index{`@\char18}
288 Backquote. \SO{quote} \VAR{foo} and \VAR{bing}; evaluate \VAR{bar}
289 and splice the lists \VAR{baz} and \VAR{quux} into their
290 elements. When nested, outermost commas inside the innermost
291 backquote expression belong to this backquote.
294 \IT{\KWD{\#\boldmath{$\backslash$}}\VAR{c}}
296 (\FU*{character} \LIT{"}\VAR{c}\LIT{"}), the character \VAR{c}.
298 \index{\#@\#$\backslash$}%
300 \IT{\KWD*{\#b}\VAR{n}; \KWD*{\#o}\VAR{n}; \VAR{n}\kwd{.};
301 \KWD*{\#x}\VAR{n}; \KWD{\#}\VAR{r}\KWD{R}\VAR{n}}
302 {\index{\#R}%
303 Integer of radix 2, 8, 10, 16, or \VAR{r}; $2\le r \le 36$.
306 \IT{\VAR{n}\kwd*{/}\VAR{d}\quad\qquad}
308 The \kwd*{ratio} $\frac{n}{d}$.
311 \IT{\GOO{\Op{\VAR{m}}\kwd{.}\VAR{n}%
312 \OP{\Goo{\KWD{S}\XOR\KWD{F}\XOR\KWD{D}\XOR\KWD{L}\XOR\KWD{E}}%
313 \VAR{x}\DF{\KWD{E}\LIT{0}}}%
314 \XOR%
315 \VAR{m}\OP{\kwd{.}\Op{\VAR{n}}}%
316 \Goo{\KWD{S}\XOR\KWD{F}\XOR\KWD{D}\XOR\KWD{L}\XOR\KWD{E}}\VAR{x}}}
318 $m.n\cdot10^x$ as \kwd*{short-float}, \kwd*{single-float},
319 \kwd*{double-float}, \kwd*{long-float}, or the type from \kwd{\A
320 read-default-float-format\A}.
323 \IT{\KWD*{\#C(}\VAR{a b}\kwd{)}\qquad\qquad}
325 (\FU*{complex} \VAR{a} \VAR{b}), the complex number
326 $\VAR{a}+\VAR{b}\text{i}$.
329 \IT{\KWD*{\#'}\VAR{foo}\qquad\qquad\qquad}
331 (\SO*{function} \VAR{foo}); the function named \VAR{foo}.
334 \IT{\KWD{\#}\VAR{n}\KWD{A}\VAR{sequence}}
335 {\index{\#A}%
336 \VAR{n}-dimensional array.
339 \IT{\KWD{\#}\Op{\VAR{n}}\kwd{(}\OPn{\VAR{foo}}\kwd{)}}
340 {\index{\#(}%
341 Vector of some (or \VAR{n})
342 \VAR{foo}s filled with last \VAR{foo} if necessary.
345 \IT{\KWD{\#}\Op{\VAR{n}}\kwd{\A}\OPn{\VAR{b}}}
346 {\index{\#*@\#\A}%
347 Bit vector of some (or \VAR{n})
348 \VAR{b}s filled with last \VAR{b} if necessary.
351 \IT{\KWD*{\#S(}\VAR{type} \Goos{\VAR{slot} \VAR{value}}\kwd{)}}
353 Structure of \VAR{type}.
356 \IT{\KWD*{\#P}\VAR{string}\qquad\qquad}
358 A pathname.
361 \IT{\KWD*{\#:}\VAR{foo}\qquad\qquad\qquad}
363 Uninterned symbol \VAR{foo}.
366 \IT{\KWD*{\#.}\VAR{form}\qquad\qquad}
368 Read-time value of \VAR{form}.
371 \IT{\V{\A read-eval\A}\DF{\T}}
372 {\index{*READ-EVAL*@\A READ-EVAL\A}
373 If \NIL, a \kwd{reader-error} is signalled at \kwd{\#.}.
376 \IT{\KWD{\#}\VAR{integer}\kwd{=} \VAR{foo}\qquad}
377 {\index{\#=}%
378 Give \VAR{foo} the label \VAR{integer}.
381 \IT{\KWD{\#}\VAR{integer}\kwd{\#}\qquad\qquad}
382 {\index{\#\#}%
383 Object labelled \VAR{integer}.
386 \IT{\KWD{\#\boldmath$<$}\qquad\qquad\qquad}
387 {\index{\#<@\#$<$}%
388 Have the reader signal \kwd{reader-error}.
391 \IT{\arrGOO{\KWD*{\#+}\VAR{feature } \VAR{when-feature}\\
392 \KWD*{\#--}\VAR{feature } \VAR{unless-feature}}{.}}
394 Means \VAR{when-feature} if \VAR{feature} is \T; means
395 \VAR{unless-feature} if \VAR{feature} is \NIL. \VAR{feature} is a
396 symbol from \V{\A features\A}, or (\Goo{\kwd*{AND}\XOR\kwd*{OR}}
397 \OPn{\VAR{feature}}), or (\kwd*{NOT} \VAR{feature}).
400 \IT{\V{\A features\A}}
401 {\index{*FEATURES*@\A FEATURES\A}
402 List of symbols denoting implementation-dependent features.
405 \IT{\kwd{\boldmath$|$}\OPn{\VAR{c}}\kwd{\boldmath$|$};
406 \kwd{\boldmath$\backslash$}\VAR{c}}
408 \index{{$"|$} {$"|$}}%
409 Treat arbitrary character(s) \VAR{c} as alphabetic preserving case.
411 \index{\@{$\backslash$}}%
412 \end{LIST}
415 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
416 \subsection{Printer}
417 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
420 \begin{LIST}{1cm}
422 \IT{(\xorGOO{\FU*{PRIN1}\\
423 \FU*{PRINT}\\
424 \FU*{PPRINT}\\
425 \FU*{PRINC}}{\}}
426 \VAR{foo} \Op{\DES{\VAR{stream}}\DF{\V{\A standard-output\A}}})}
428 Print \VAR{foo} to \VAR{stream} \FU{read}ably,
429 \FU{read}ably between a newline and a space,
430 \FU{read}ably after a newline, or human-readably without any extra
431 characters, respectively. \FU{prin1}, \FU{print} and \FU{princ}
432 return \retval{\VAR{foo}}.
435 \IT{\arrGOO{(\FU*{PRIN1-TO-STRING} \VAR{ foo})\\
436 (\FU*{PRINC-TO-STRING} \VAR{ foo})}{.}}
438 Print \VAR{foo} to \retval{\VAR{string}} \FU{read}ably or
439 human-readably, respectively.
442 \IT{(\GFU*{PRINT-OBJECT} \VAR{object} \DES{\VAR{stream}})}
444 Print \retval{\VAR{object}} to \VAR{stream}. Called by the Lisp
445 printer.
448 \IT{(\MC*{PRINT-UNREADABLE-OBJECT} (\VAR{foo} \DES{\VAR{stream}}
449 \orGOO{\kwd{:type } \VAR{bool}\DF{\NIL}\\
450 \kwd{:identity } \VAR{bool}\DF{\NIL}}{\}})
451 \PROGN{\VAR{form}})}
453 Enclosed in \kwd{\#\boldmath$<$} and \kwd{\boldmath$>$}, print
454 \VAR{foo} by means of \VAR{form}s to \VAR{stream}. Return \retval{\NIL}.
457 \IT{(\FU*{TERPRI} \Op{\DES{\VAR{stream}}\DF{\V{\A standard-output\A}}})}
459 Output a newline to \VAR{stream}. Return \retval{\NIL}.
462 \IT{(\FU*{FRESH-LINE}
463 \Op{\DES{\VAR{stream}}\DF{\V{\A standard-output\A}}})}
465 Output a newline to \VAR{stream} and return \retval{\T} unless
466 \VAR{stream} is already at the start of a line.
469 \IT{(\FU*{WRITE-CHAR} \VAR{char}
470 \Op{\DES{\VAR{stream}}\DF{\V{\A standard-output\A}}})}
472 Output \retval{\VAR{char}} to \VAR{stream}.
475 \IT{(\xorGOO{\FU*{WRITE-STRING}\\
476 \FU*{WRITE-LINE}}{\}} \VAR{string}
477 \OP{\DES{\VAR{stream}}\DF{\V{\A standard-output\A}}
478 \OP{\orGOO{\kwd{:start} \VAR{ start}\DF{\LIT{0}}\\\kwd{:end} \VAR{
479 end}\DF{\NIL}}{\}}}})}
481 Write \retval{\VAR{string}} to \VAR{stream} without/with a
482 trailing newline.
485 \IT{(\FU*{WRITE-BYTE} \VAR{byte} \DES{\VAR{stream}})}
487 Write \retval{\VAR{byte}} to binary \VAR{stream}.
490 \IT{(\FU*{WRITE-SEQUENCE} \VAR{sequence}
491 \DES{\VAR{stream}} \orGOO{\kwd{:start}\VAR{ start}\DF{\LIT{0}}\\
492 \kwd{:end} \VAR{ end}\DF{\NIL}}{\}})}
494 Write elements of \retval{\VAR{sequence}} to binary or character
495 \VAR{stream}.
498 \IT{(\xorGOO{\FU*{WRITE}\\
499 \FU*{WRITE-TO-STRING}}{\}} \VAR{foo} \orGOO{%
500 \kwd{:array} \VAR{ bool}\\
501 \kwd{:base} \VAR{ radix}\\
502 \kwd{:case } \xorGOO{\kwd{:upcase}\\
503 \kwd{:downcase}\\
504 \kwd{:capitalize}}{.}\\
505 \kwd{:circle} \VAR{ bool}\\
506 \kwd{:escape} \VAR{ bool}\\
507 \kwd{:gensym} \VAR{ bool}\\
508 \kwd{:length } \Goo{\VAR{int}\XOR\NIL}\\
509 \kwd{:level } \Goo{\VAR{int}\XOR\NIL}\\
510 \kwd{:lines } \Goo{\VAR{int}\XOR\NIL}\\
511 \kwd{:miser-width } \Goo{\VAR{int}\XOR\NIL}\\
512 \kwd{:pprint-dispatch} \VAR{ dispatch-table}\\
513 \kwd{:pretty} \VAR{ bool}\\
514 \kwd{:radix} \VAR{ bool}\\
515 \kwd{:readably} \VAR{ bool}\\
516 \kwd{:right-margin } \Goo{\VAR{int}\XOR\NIL}\\
517 \kwd{:stream } \DES{\VAR{stream}}\DF{\V{\A standard-output\A}}%
518 }{\}})}
520 Print \VAR{foo} to \VAR{stream} and return \retval{\VAR{foo}}, or
521 print \VAR{foo} into \retval{string}, respectively, after
522 dynamically setting printer variables corresponding to keyword
523 parameters (\kwd{\A print-}\VAR{bar}\kwd{\A} becoming
524 \kwd{:}\VAR{bar}). (\kwd{:stream} keyword with \FU{write} only.)
527 \IT{\arrGOO{%
528 (\FU*{PPRINT-FILL } \DES{\VAR{stream}} \VAR{ foo }
529 \OP{\VAR{parenthesis}\DF{\T} \text{ } \Op{\VAR{noop}}})\\
530 (\FU*{PPRINT-TABULAR } \DES{\VAR{stream}} \VAR{ foo }
531 \OP{\VAR{parenthesis}\DF{\T} \text{ } \Op{\VAR{noop} \text{ }
532 \Op{\VAR{n}\DF{\LIT{16}}}}})\\
533 (\FU*{PPRINT-LINEAR } \DES{\VAR{stream}} \VAR{ foo }
534 \OP{\VAR{parenthesis}\DF{\T} \text{ } \Op{\VAR{noop}}})\\
535 }{.}}
537 Print \VAR{foo} to \VAR{stream}. If \VAR{foo} is a list, print as
538 many elements per line as possible; do the same in a table with
539 a column width of \VAR{n} ems; or print either all elements on
540 one line or each on its own line, respectively. Return
541 \retval{\NIL}. Usable with \FU{format} directive \KWD{\TLD//}.
544 \IT{(\MC*{PPRINT-LOGICAL-BLOCK} (\DES{\VAR{stream}} \VAR{list}
545 \orGOO{\xorGOO{\kwd{:prefix} \VAR{ string}\\
546 \kwd{:per-line-prefix} \VAR{ string}}{\}}\\
547 \kwd{:suffix} \VAR{ string}\DF{\LIT{""}}}{\}})
548 \OPn{(\kwd{declare} \OPn{\NEV{\VAR{decl}}})} \PROGN{\VAR{form}})}
550 Evaluate \VAR{form}s, which should print \VAR{list}, with
551 \VAR{stream} locally bound to a pretty
552 printing stream which outputs to the original \VAR{stream}. If
553 \VAR{list} is in fact not a list, it is printed by
554 \FU{write}. Return \retval{\NIL}.
557 \begin{LIST}{.5cm}
559 \IT{(\MC*{PPRINT-POP})}
561 Take \retval{next element} off \VAR{list}. If there is no remaining
562 tail of \VAR{list}, or \V{\A print-length\A} or \V{\A print-circle\A} indicate
563 printing should end, send element together with an appropriate
564 indicator to \VAR{stream}.
567 \IT{(\FU*{PPRINT-TAB} \xorGOO{\kwd{:line}\\
568 \kwd{:line-relative}\\
569 \kwd{:section}\\
570 \kwd{:section-relative}}{\}} \VAR{c}
571 \VAR{i} \Op{\DES{\VAR{stream}}\DF{\V{\A standard-output\A}}})}
573 Move cursor forward to column number $c + ki$, $k \geq 0$ being as small
574 as possible.
577 \IT{(\FU*{PPRINT-INDENT} \xorGOO{%
578 \kwd{:block}\\
579 \kwd{:current}}{\}} \VAR{n}
580 \OP{\DES{\VAR{stream}}\DF{\V{\A standard-output\A}}})}
582 Specify indentation for innermost logical block relative to
583 leftmost position/to current position. Return \retval{\NIL}.
586 \IT{(\MC*{PPRINT-EXIT-IF-LIST-EXHAUSTED})}
588 If \VAR{list} is empty, terminate logical block. Return
589 \retval{\NIL} otherwise.
592 \end{LIST}
594 \IT{(\FU*{PPRINT-NEWLINE} \xorGOO{%
595 \kwd{:linear}\\
596 \kwd{:fill}\\
597 \kwd{:miser}\\
598 \kwd{:mandatory}}{\}}
599 \OP{\DES{\VAR{stream}}\DF{\V{\A standard-output\A}}})}
601 Print a conditional newline if \VAR{stream} is a pretty printing
602 stream. Return \retval{\NIL}.
605 \IT{\V{\A print-array\A}}
606 {\index{*PRINT-ARRAY*@\A PRINT-ARRAY\A}
607 If \T, print arrays \FU{read}ably.
610 \IT{\V{\A print-base\A}\DF{\LIT{10}}}
611 {\index{*PRINT-BASE*@\A PRINT-BASE\A}
612 Radix for printing rationals, from 2 to 36.
615 \IT{\V{\A print-case\A}\DF{\kwd{:upcase}}}
616 {\index{*PRINT-CASE*@\A PRINT-CASE\A}
617 Print symbol names all uppercase (\kwd{:upcase}), all lowercase
618 (\kwd{:downcase}), capitalized (\kwd{:capitalize}).
621 \IT{\V{\A print-circle\A}\DF{\NIL}}
622 {\index{*PRINT-CIRCLE*@\A PRINT-CIRCLE\A}
623 If \T, avoid indefinite recursion while printing circular
624 structure.
627 \IT{\V{\A print-escape\A}\DF{\T}}
628 {\index{*PRINT-ESCAPE*@\A PRINT-ESCAPE\A}
629 If \NIL, do not print escape characters and package prefixes.
632 \IT{\V{\A print-gensym\A}\DF{\T}}
633 {\index{*PRINT-GENSYM*@\A PRINT-GENSYM\A}
634 If \T, print \kwd{\#:} before uninterned symbols.
637 \IT{\arrGOO{\V{\A print-length\A}\DF{\NIL}\\
638 \V{\A print-level\A}\DF{\NIL}\\
639 \V{\A print-lines\A}\DF{\NIL}
640 }{.}}
641 {\index{*PRINT-LENGTH*@\A PRINT-LENGTH\A}\index{*PRINT-LEVEL*@\A PRINT-LEVEL\A}\index{*PRINT-LINES*@\A PRINT-LINES\A}
642 If integer, restrict printing of objects to that number of
643 elements per level/to that depth/to that number of lines.
646 \IT{\V{\A print-miser-width\A}}
647 {\index{*PRINT-MISER-WIDTH*@\A PRINT-MISER-WIDTH\A}
648 If integer and greater than the width available for printing a
649 substructure, switch to the more compact miser style.
652 \IT{\V{\A print-pretty\A}}
653 {\index{*PRINT-PRETTY*@\A PRINT-PRETTY\A}
654 If \T, print prettily.
657 \IT{\V{\A print-radix\A}\DF{\NIL}}
658 {\index{*PRINT-RADIX*@\A PRINT-RADIX\A}
659 If \T, print rationals with a radix indicator.
662 \IT{\V{\A print-readably\A}\DF{\NIL}}
663 {\index{*PRINT-READABLY*@\A PRINT-READABLY\A}
664 If \T, print \FU{read}ably or signal error
665 \kwd{print-not-readable}.
668 \IT{\V{\A print-right-margin\A}\DF{\NIL}}
669 {\index{*PRINT-RIGHT-MARGIN*@\A PRINT-RIGHT-MARGIN\A}
670 Right margin width in ems while pretty-printing.
673 \IT{(\FU*{SET-PPRINT-DISPATCH} \VAR{type} \VAR{function}
674 \OP{\VAR{priority}\DF{\LIT{0}}
675 \Op{\VAR{table}\DF{\V{\A print-pprint-dispatch\A}}}})}
677 Install entry comprising \VAR{function} of arguments stream and
678 object to print; and \VAR{priority} as
679 \VAR{type} into \VAR{table}. If \VAR{function}
680 is \NIL, remove \VAR{type} from \VAR{table}. Return \retval{\NIL}.
683 \IT{(\FU*{PPRINT-DISPATCH} \VAR{foo}
684 \Op{\VAR{table}\DF{\V{\A print-pprint-dispatch\A}}})}
686 Return highest priority \retval{\VAR{function}} associated with
687 type of \VAR{foo} and \retvalii{\T} if there was a matching type
688 specifier in \VAR{table}.
691 \IT{(\FU*{COPY-PPRINT-DISPATCH}
692 \Op{\VAR{table}\DF{\V{\A print-pprint-dispatch\A}}})}
694 Return \retval{copy of \VAR{table}} or, if \VAR{table} is \NIL,
695 initial value of \V{\A print-pprint-dispatch\A}.
698 \IT{\V{\A print-pprint-dispatch\A}}
699 {\index{*PRINT-PPRINT-DISPATCH*@\A PRINT-PPRINT-DISPATCH\A}
700 Current pretty print dispatch table.
703 \end{LIST}
707 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
708 \subsection{Format}
709 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
710 \label{section:Format}
712 \begin{LIST}{1cm}
714 \IT{(\MC*{FORMATTER} \NEV{\VAR{control}})}
716 Return \retval{function} of \VAR{stream} and \OPn{\VAR{arg}}
717 applying \FU{format} to \VAR{stream}, \VAR{control}, and
718 \OPn{\VAR{arg}} returning \NIL\ or any excess \VAR{arg}s.
721 \IT{(\FU*{FORMAT} \Goo{\T\XOR\NIL\XOR\VAR{out-string}\XOR\VAR{out-stream}}
722 \VAR{control} \OPn{\VAR{arg}})}
724 Output string \VAR{control} which may
725 contain \kwd{\TLD} directives possibly taking some
726 \VAR{arg}s. Alternatively, \VAR{control} can be a function returned
727 by \MC{formatter} which is then applied to \VAR{out-stream} and
728 \OPn{\VAR{arg}}. Output to \VAR{out-string}, \VAR{out-stream} or,
729 if first argument is \T, to \V{\A standard-output\A}. Return
730 \retval{\NIL}. If first argument is \NIL, return
731 \retval{formatted output}.
734 \begin{LIST}{.5cm}
736 \IT{\KWD{\TLD} \Op{\VAR{min-col}\DF{\LIT{0}}} \OP{\KWD{,}\Op{\VAR{col-inc}\DF{\LIT{1}}}
737 \OP{\KWD{,}\Op{\VAR{min-pad}\DF{\LIT{0}}}
738 \OP{\KWD{,'}\VAR{pad-char}\DF{\textvisiblespace}}}}
739 \KWD{\Op{:} \Op{@} \Goo{A\XOR S}}}
740 {\index{\~S@$\sim$S}\index{\~A@$\sim$A}%
741 \EM{Aesthetic/Standard. }
742 Print argument of any type for consumption by humans/by the
743 reader, respectively. With \kwd{:}, print \NIL\ as \LIT{()} rather
744 than \LIT{nil}; with \kwd{@}, add \VAR{pad-char}s on the left
745 rather than on the right.
748 \IT{\KWD{\TLD} \Op{\VAR{radix}\DF{\LIT{10}}} \OP{\KWD{,}\Op{\VAR{width}}
749 \OP{\KWD{,}\Op{\kwd{'}\VAR{pad-char}\DF{\textvisiblespace}}
750 \OP{\KWD{,}\Op{\kwd{'}\VAR{comma-char}\DF{\LIT{,}}}
751 \OP{\KWD{,}\VAR{comma-interval}\DF{\LIT{3}}}}}}
752 \KWD{\Op{:} \Op{@} R}}
753 {\index{\~R@$\sim$R}%
754 \EM{Radix. }
755 (With one or more prefix arguments.) Print argument as number; with
756 \KWD{:}, group digits \VAR{comma-interval} each; with \kwd{@},
757 always prepend a sign.
760 \IT{\Goo{\KWD{\TLD R}\XOR\KWD{\TLD :R}\XOR\KWD{\TLD
761 @R}\XOR\KWD{\TLD @:R}}}
763 \EM{Roman. }
764 Take argument as number and print it as English cardinal number,
765 as English ordinal number, as Roman numeral, or as old Roman
766 numeral, respectively.
769 \IT{\KWD{\TLD} \Op{\VAR{width}}
770 \OP{\KWD{,}\Op{\kwd{'}\VAR{pad-char}\DF{\textvisiblespace}}
771 \OP{\KWD{,}\Op{\kwd{'}\VAR{comma-char}\DF{\LIT{,}}}
772 \OP{\KWD{,}\VAR{comma-interval}\DF{\LIT{3}}}}}
773 \KWD{\Op{:} \Op{@} \Goo{D\XOR B\XOR O\XOR X}}}
774 {\index{\~D@$\sim$D}\index{\~B@$\sim$B}\index{\~O@$\sim$O}\index{\~X@$\sim$X}%
775 \EM{Decimal/Binary/Octal/Hexadecimal. }
776 Print integer argument as number. With \kwd{:}, group digits
777 \VAR{comma-interval} each; with \kwd{@}, always prepend a sign.
780 \IT{\KWD{\TLD} \Op{\VAR{width}} \OP{\KWD{,}\Op{\VAR{dec-digits}}
781 \OP{\KWD{,}\Op{\VAR{shift}\DF{\LIT{0}}}
782 \OP{\KWD{,}\Op{\kwd{'}\VAR{overflow-char}}
783 \OP{\KWD{,'}\VAR{pad-char}\DF{\textvisiblespace}}}}}
784 \KWD{\Op{@} F}}
785 {\index{\~F@$\sim$F}%
786 \EM{Fixed-Format Floating-Point. } With
787 \kwd{@}, always pre\-pend a sign.
790 \IT{\KWD{\TLD} \Op{\VAR{width}} \OP{\KWD{,}\Op{\VAR{dec-digits}}
791 \OP{\KWD{,}\Op{\VAR{exp-digits}}
792 \OP{\KWD{,}\Op{\VAR{scale-factor}\DF{\LIT{1}}}
793 \OP{\KWD{,}\Op{\kwd{'}\VAR{overflow-char}}
794 \OP{\KWD{,}\Op{\kwd{'}\VAR{pad-char}\DF{\textvisiblespace}}
795 \OP{\KWD{,'}\VAR{exp-char}}}}}}}
796 \KWD{\Op{@} \Goo{E\XOR G}}}
797 {\index{\~E@$\sim$E}\index{\~G@$\sim$G}%
798 \EM{Exponential/General Floating-Point. }
799 Print argument as floating-point number with \VAR{dec-digits}
800 after decimal point and \VAR{exp-digits} in the signed
801 exponent. With \KWD{\TLD G}, choose either \KWD{\TLD E} or
802 \KWD{\TLD F}. With \KWD{@}, always prepend a sign.
805 \IT{\KWD{\TLD} \Op{\VAR{dec-digits}\DF{\LIT{2}}}
806 \OP{\KWD{,}\Op{\VAR{int-digits}\DF{\LIT{1}}}
807 \OP{\KWD{,}\Op{\VAR{width}\DF{\LIT{0}}}
808 \OP{\KWD{,'}\VAR{pad-char}\DF{\textvisiblespace}}}}
809 \Op{\KWD{:}} \Op{\kwd{@}} \KWD{\$}}
810 {\index{\~\$@$\sim$\$}%
811 \EM{Monetary Floating-Point. }
812 Print argument as fixed-format floating-point number. With \KWD{:},
813 put sign before any padding; with \KWD{@}, always prepend a
814 sign.
817 \IT{\Goo{\KWD{\TLD C}\XOR\KWD{\TLD :C}\XOR\KWD{\TLD
818 @C}\XOR\KWD{\TLD @:C}}}
819 {\index{\~C@$\sim$C}%
820 \EM{Character. }
821 Print, spell out, print in \kwd{\#$\backslash$} syntax, or tell
822 how to type, respectively, argument as (possibly non-printing)
823 character.
826 \IT{\Goo{%
827 \KWD{\TLD(} \VAR{text} \KWD{\TLD)}\XOR
828 \KWD{\TLD:(} \VAR{text} \KWD{\TLD)}\XOR
829 \KWD{\TLD @(} \VAR{text} \KWD{\TLD)}\XOR
830 \KWD{\TLD @:(} \VAR{text} \KWD{\TLD)}}}
831 {\index{\~(\~)@$\sim$( $\sim$)}%
832 \EM{Case-Conversion. }
833 Convert \VAR{text} to lowercase, convert first letter of each word
834 to uppercase, capitalize first word and convert the rest to
835 lowercase, or convert to uppercase, respectively.
838 \IT{\Goo{\KWD{\TLD P}\XOR\KWD{\TLD:P}
839 \XOR\KWD{\TLD @P}\XOR\KWD{\TLD @:P}}}
840 {\index{\~P@$\sim$P}%
841 \EM{Plural. }
842 If argument \kwd{eql} \LIT{1} print nothing, otherwise print \LIT{s};
843 do the same for the previous argument; if argument \kwd{eql} \LIT{1}
844 print \LIT{y}, otherwise print \LIT{ies}; do the same for the
845 previous argument, respectively.
848 \IT{\KWD{\TLD} \Op{\VAR{n}\DF{\LIT{1}}} \KWD{\%}}
849 {\index{\~\%@$\sim$\%}%
850 \EM{Newline. }
851 Print \VAR{n} newlines.
854 \IT{\KWD{\TLD} \Op{\VAR{n}\DF{\LIT{1}}} \KWD{\&}}
855 {\index{\~\&@$\sim$\&}%
856 \EM{Fresh-Line. }
857 Print $n-1$ newlines if output stream is at the
858 beginning of a line, or \VAR{n} newlines otherwise.
861 \IT{\Goo{%
862 \KWD{\TLD\_}\XOR
863 \KWD{\TLD:\_}\XOR
864 \KWD{\TLD@\_}\XOR
865 \KWD{\TLD @:\_}}}
866 {\index{\~\_{}@$\sim$\_{}}%
867 \EM{Conditional Newline. }
868 Print a newline like \kwd{pprint-newline} with argument
869 \kwd{:linear}, \kwd{:fill}, \kwd{:miser}, or \kwd{:mandatory}, respectively.
872 \IT{\Goo{\KWD{\TLD:$\hookleftarrow$}\XOR\KWD{\TLD@$\hookleftarrow$}\XOR\KWD{\TLD$\hookleftarrow$}}}
873 {\index{\~\~bogus-ordering{}@$\sim\hookleftarrow$}%
874 \EM{Ignored Newline. } Ignore newline, or whitespace following
875 newline, or both, respectively.
878 \IT{\KWD{\TLD} \Op{\VAR{n}\DF{\LIT{1}}} \KWD{\boldmath$|$}}
879 {\index{\~\textbar@$\sim${$"|$}}%
880 \EM{Page. }
881 Print \VAR{n} page separators.
884 \IT{\KWD{\TLD} \Op{\VAR{n}\DF{\LIT{1}}} \KWD{\TLD}}
885 {\index{\~\~@$\sim$$\sim$}%
886 \EM{Tilde. }
887 Print \VAR{n} tildes.
890 \IT{\KWD{\TLD} \Op{\VAR{min-col}\DF{\LIT{0}}}
891 \OP{\KWD{,}\Op{\VAR{col-inc}\DF{\LIT{1}}}
892 \OP{\KWD{,}\Op{\VAR{min-pad}\DF{\LIT{0}}}
893 \OP{\KWD{,'}\VAR{pad-char}\DF{\textvisiblespace}}}}
894 \KWD{\Op{:} \Op{@} \boldmath{$<$}}
895 \OP{\VAR{nl-text} \KWD{\TLD}\Op{\VAR{spare}\DF{\LIT{0}} \Op{\KWD{,}\VAR{width}}}\kwd{:;}}
896 \Goos{\VAR{text} \KWD{\TLD;}} \VAR{text} \KWD{\TLD\boldmath{$>$}}}
897 {\index{\~<\~>@$\sim$$<$ $\sim$$>$}%
898 \EM{Justification. }
899 Justify text produced by \VAR{text}s in a field of at least
900 \VAR{min-col} columns. With \kwd{:}, right justify; with \kwd{@},
901 left justify. If this would leave less than \VAR{spare} characters
902 on the current line, output \VAR{nl-text} first.
905 \IT{\KWD{\TLD} \Op{\KWD{:}} \Op{\KWD{@}} \KWD{\boldmath{$<$}}
906 \GOo{\Op{\VAR{prefix}\DF{\LIT{""}}
907 \KWD{\TLD;}}\XOR\Op{\VAR{per-line-prefix}
908 \KWD{\TLD@;}}}
909 \VAR{body} \OP{\KWD{\TLD;} \VAR{suffix}\DF{\LIT{""}}}
910 \KWD{\TLD:} \Op{\KWD{@}} \KWD{\boldmath{$>$}}}
911 {\index{\~<\~:>@$\sim$$<$ $\sim$:$>$}%
912 \EM{Logical Block. }
913 Act like \kwd{pprint-logical-block} using \VAR{body} as \FU{format}
914 control string on the elements of the list argument or, with \KWD{@},
915 on the remaining arguments, which are extracted by
916 \kwd{pprint-pop}. With \KWD{:}, \VAR{prefix} and \VAR{suffix}
917 default to \LIT{(} and \LIT{)}. When closed by
918 \KWD{\TLD @:\boldmath{$>$}}, spaces in \VAR{body} are replaced with
919 conditional newlines.
922 \IT{\Goo{\KWD{\TLD} \Op{\VAR{n}\DF{\LIT{0}}}
923 \kwd{I}\XOR\KWD{\TLD} \Op{\VAR{n}\DF{\LIT{0}}} \kwd{:I}}}
924 {\index{\~I@$\sim$I}%
925 \EM{Indent. }
926 Set indentation to \VAR{n} relative to leftmost/to current
927 position.
930 \IT{\KWD{\TLD} \Op{\VAR{c}\DF{\LIT{1}}}
931 \Op{\KWD{,}\VAR{i}\DF{\LIT{1}}} \Op{\KWD{:}} \Op{\KWD{@}} \KWD{T}}
932 {\index{\~T@$\sim$T}%
933 \EM{Tabulate. }
934 Move cursor forward to column number $c + ki$, $k \geq 0$ being as small
935 as possible. With \kwd{:}, calculate column numbers relative to
936 the immediately enclosing section. With \kwd{@}, move to column
937 number $c_0 + c + ki$ where $c_0$ is the current position.
940 \IT{\Goo{%
941 \KWD{\TLD} \Op{\VAR{m}\DF{\LIT{1}}} \KWD{\A}\XOR
942 \KWD{\TLD} \Op{\VAR{m}\DF{\LIT{1}}} \KWD{:}\KWD{\A}\XOR
943 \KWD{\TLD} \Op{\VAR{n}\DF{\LIT{0}}} \KWD{@}\KWD{\A}}}
944 {\index{\~*@$\sim$\A}%
945 \EM{Go-To. }
946 Jump \VAR{m} arguments forward, or backward, or to argument \VAR{n}.
949 \IT{\KWD{\TLD} \Op{\VAR{limit}} \Op{\KWD{{:}}} \Op{\kwd{@}}
950 \KWD{\boldmath{$\{$}} \VAR{text} \KWD{\TLD\boldmath{$\}$}}}
951 {\index{\~\{\~\}@$\sim$$\{$ $\sim\}$}%
952 \EM{Iteration. }
953 Use \VAR{text} repeatedly, up to \VAR{limit}, as control
954 string for the elements of the list argument or (with
955 \kwd{@}) for the remaining arguments. With \kwd{:} or \kwd{@:},
956 list elements or remaining arguments should be
957 lists of which a new one is used at each iteration step.
960 \IT{\KWD{\TLD} \OP{\VAR{x} \OP{\kwd{,}\VAR{y} \Op{\kwd{,}\VAR{z}}}}
961 \KWD{\^{}}}
962 {\index{\~\^{}@$\sim$\^{}}%
963 \EM{Escape Upward. }
964 Leave immediately \kwd{\TLD\boldmath{$<$} \TLD\boldmath{$>$}},
965 \kwd{\TLD\boldmath{$<$} \TLD:\boldmath{$>$}},
966 \kwd{\TLD\boldmath{$\{$} \TLD\boldmath{$\}$}}, \kwd{\TLD?}, or the
967 entire \FU{format} operation. With one to three prefixes, act only
968 if $x=0$, $x=y$, or $x\leq y \leq z$, respectively.
971 \IT{\KWD{\TLD} \Op{\VAR{i}} \Op{\KWD{:}} \Op{\KWD{@}}
972 \KWD{[} \Op{\Goos{\VAR{text} \KWD{\TLD;}} \VAR{text}}
973 \Op{\kwd{\TLD:;} \VAR{default}} \KWD{\TLD]}}
974 {\index{\~[\~]@$\sim$[ $\sim$]}%
975 \EM{Conditional Expression. }
976 Use the zero-indexed argumenth (or
977 \VAR{i}th if given) \VAR{text} as a \FU{format} control subclause.
978 With \kwd{:}, use the first \VAR{text} if the argument value is
979 \NIL, or the second \VAR{text} if it is \T. With \kwd{@}, do nothing
980 for an argument value of \NIL. Use the only \VAR{text} and leave
981 the argument to be read again if it is \T.
984 \IT{\Goo{%
985 \KWD{\TLD?}\XOR
986 \KWD{\TLD @?}}
988 {\index{\~?@$\sim$?}%
989 \EM{Recursive Processing. }
990 Process two arguments as control string and argument list, or
991 take one argument as control string and use then the rest of the
992 original arguments.
995 \IT{\KWD{\TLD} \OP{\VAR{prefix} \Goos{\kwd{,}%
996 \VAR{prefix}}}
997 \Op{\kwd{:}} \Op{\kwd{@}}
998 \KWD{/}\OP{\VAR{package}
999 \Op{\LIT{:}}\LIT{:}\DF{\LIT{cl-user:}}}\VAR{function}\KWD{/}}
1000 {\index{\~/ /@$\sim$/ /}%
1001 \EM{Call Function. }
1002 Call all-uppercase \VAR{package}\KWD{::}\VAR{function} with the
1003 arguments stream, format-ar\-gu\-ment, colon-p, at-sign-p and
1004 \VAR{prefix}es for printing format-argument.
1007 \IT{\KWD{\TLD} \Op{\KWD{:}} \Op{\KWD{@}} \KWD{W}}
1008 {\index{\~W@$\sim$W}%
1009 \EM{Write. }
1010 Print argument of any type obeying every printer control
1011 variable. With \kwd{:}, pretty-print. With \kwd{@}, print
1012 without limits on length or depth.
1015 \IT{\Goo{\KWD{V}\XOR\KWD{\#}}}
1016 {\index{V}\index{\#}
1017 In place of the comma-separated prefix parameters: use next
1018 argument or number of remaining unprocessed arguments, respectively.
1021 \end{LIST}
1023 \end{LIST}
1026 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1027 \subsection{Streams}
1028 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1030 \begin{LIST}{1cm}
1032 \IT{(\FU*{OPEN} \VAR{path}
1033 \orGOO{\kwd{:direction }
1034 \xorGOO{\kwd{:input}\\
1035 \kwd{:output}\\
1036 \kwd{:io}\\
1037 \kwd{:probe}}{\}}\DF{\kwd{:input}}\\
1038 \kwd{:element-type }
1039 \xorGOO{\VAR{type}\\
1040 \kwd{:default}}{\}}\DF{\kwd{character}}\\
1041 \kwd{:if-exists }
1042 \xorGOO{\kwd{:new-version}\\
1043 \kwd{:error}\\
1044 \kwd{:rename}\\
1045 \kwd{:rename-and-delete}\\
1046 \kwd{:overwrite}\\
1047 \kwd{:append}\\
1048 \kwd{:supersede}\\
1049 \NIL}{\}}\DF{\parbox{20mm}{%
1050 \kwd{:new-version} if \VAR{path} specifies \kwd{:newest};\\
1051 \NIL\ otherwise}}\\
1052 \kwd{:if-does-not-exist }
1053 \xorGOO{\kwd{:error}\\
1054 \kwd{:create}\\
1055 \NIL}{\}}\DF{\parbox{27mm}{%
1056 \NIL\ for \kwd{:direction :probe};\\
1057 \mbox{\Goo{\kwd{:create}\XOR\kwd{:error}} otherwise}}}\\
1058 \kwd{:external-format } \VAR{format}\DF{\kwd{:default}}%
1059 }{\}})}
1060 {\label{open}
1061 Open \retval{\kwd{file-stream} to \VAR{path}}.
1064 \IT{\arrGOO{%
1065 (\FU*{MAKE-CONCATENATED-STREAM } \OPn{\VAR{input-stream}})\\
1066 (\FU*{MAKE-BROADCAST-STREAM } \OPn{\VAR{output-stream}})\\
1067 (\FU*{MAKE-TWO-WAY-STREAM } \VAR{input-stream-part } \VAR{output-stream-part})\\
1068 (\FU*{MAKE-ECHO-STREAM } \VAR{from-input-stream } \VAR{to-output-stream})\\
1069 (\FU*{MAKE-SYNONYM-STREAM } \VAR{variable-bound-to-stream})}{.}}
1071 Return \retval{stream} of indicated type.
1074 \IT{(\FU*{MAKE-STRING-INPUT-STREAM} \VAR{string}
1075 \OP{\VAR{start}\DF{\LIT{0}}
1076 \Op{\VAR{end}\DF{\NIL}}})}
1078 Return a \retval{\kwd{string-stream}} supplying the characters from \VAR{string}.
1081 \IT{(\FU*{MAKE-STRING-OUTPUT-STREAM} \Op{\kwd{:element-type}
1082 \VAR{type}\DF{\kwd{character}}})}
1084 Return a \retval{\kwd{string-stream}} accepting characters
1085 (available via \FU{get-output-stream-string}).
1088 \IT{\arrGOO{(\FU*{CONCATENATED-STREAM-STREAMS } \VAR{concatenated-stream})\\
1089 (\FU*{BROADCAST-STREAM-STREAMS } \VAR{broadcast-stream})}{.}}
1091 Return \retval{list of streams} \VAR{concatenated-stream} still
1092 has to read from/\VAR{broadcast-stream} is
1093 broadcasting to.
1096 \IT{\arrGOO{%
1097 (\FU*{TWO-WAY-STREAM-INPUT-STREAM} \VAR{ two-way-stream})\\
1098 (\FU*{TWO-WAY-STREAM-OUTPUT-STREAM} \VAR{ two-way-stream})\\
1099 (\FU*{ECHO-STREAM-INPUT-STREAM} \VAR{ echo-stream})\\
1100 (\FU*{ECHO-STREAM-OUTPUT-STREAM} \VAR{ echo-stream})}{.}}
1102 Return \retval{source stream} or \retval{sink stream} of
1103 \VAR{two-way-stream}\slash\VAR{echo-stream}, respectively.
1106 \IT{(\FU*{SYNONYM-STREAM-SYMBOL} \VAR{synonym-stream})}
1108 Return \retval{symbol} of \VAR{synonym-stream}.
1111 \IT{(\FU*{GET-OUTPUT-STREAM-STRING} \DES{\VAR{string-stream}})}
1113 Clear and return as a \retval{string} characters on
1114 \VAR{string-stream}.
1117 \IT{(\FU*{FILE-POSITION} \VAR{stream} \Op{\xorGOO{\kwd{:start}\\
1118 \kwd{:end}\\
1119 \VAR{position}}{\}}})}
1121 Return \retval{position within stream}, or set it to
1122 \retval{\VAR{position}} and return \retval{\T} on success.
1125 \IT{(\FU*{FILE-STRING-LENGTH} \VAR{stream} \VAR{foo})}
1127 \retval{Length} \VAR{foo} would have in \VAR{stream}.
1130 \IT{(\FU*{LISTEN} \Op{\VAR{stream}\DF{\V{\A standard-input\A}}})}
1132 \retval{\T} if there is a character in input \VAR{stream}.
1135 \IT{(\FU*{CLEAR-INPUT}
1136 \Op{\DES{\VAR{stream}}\DF{\V{\A standard-input\A}}})}
1138 Clear input from \VAR{stream}, return \retval{\NIL}.
1141 \IT{(\xorGOO{\FU*{CLEAR-OUTPUT}\\
1142 \FU*{FORCE-OUTPUT}\\
1143 \FU*{FINISH-OUTPUT}}{\}}
1144 \Op{\DES{\VAR{stream}}\DF{\V{\A standard-output\A}}})}
1146 End output to \VAR{stream} and return \retval{\NIL} immediately,
1147 after initiating flushing of buffers, or after flushing of
1148 buffers, respectively.
1151 \IT{(\FU*{CLOSE} \DES{\VAR{stream}} \Op{\kwd{:abort}
1152 \VAR{bool}\DF{\NIL}})}
1154 Close \VAR{stream}. Return \retval{\T} if \VAR{stream} had been
1155 open. If \kwd{:abort} is \T, delete associated file.
1158 \IT{(\MC*{WITH-OPEN-FILE} (\VAR{stream} \VAR{path}
1159 \OPn{\VAR{open-arg}}) \OPn{(\kwd{declare} \OPn{\NEV{\VAR{decl}}})}
1160 \PROGN{\VAR{form}})}
1162 Use \FU{OPEN} with \VAR{open-arg}s to temporarily create
1163 \VAR{stream} to \VAR{path}; return \retval{values of
1164 \VAR{form}s}.
1167 \IT{(\MC*{WITH-OPEN-STREAM} (\VAR{foo} \DES{\VAR{stream}})
1168 \OPn{(\kwd{declare} \OPn{\NEV{\VAR{decl}}})} \PROGN{\VAR{form}})}
1170 Evaluate \VAR{form}s with \VAR{foo} locally bound to
1171 \VAR{stream}. Return \retval{values of \VAR{form}s}.
1174 \IT{(\MC*{WITH-INPUT-FROM-STRING} (\VAR{foo} \VAR{string}
1175 \orGOO{\kwd{:index } \DES{\VAR{index}}\\
1176 \kwd{:start} \VAR{ start}\DF{\LIT{0}}\\
1177 \kwd{:end} \VAR{ end}\DF{\NIL}}{\}}) \OPn{(\kwd{declare}
1178 \OPn{\NEV{\VAR{decl}}})} \PROGN{\VAR{form}})}
1180 Evaluate \VAR{form}s with \VAR{foo} locally bound to input
1181 \kwd{string-stream} from \VAR{string}. Return \retval{values of
1182 \VAR{form}s}; store next reading position into \VAR{index}.
1185 \IT{(\MC*{WITH-OUTPUT-TO-STRING} (\VAR{foo}
1186 \OP{\DES{\VAR{string}}\DF{\NIL}
1187 \Op{\kwd{:element-type}
1188 \VAR{type}\DF{\kwd{character}}}})
1189 \OPn{(\kwd{declare}
1190 \OPn{\NEV{\VAR{decl}}})} \PROGN{\VAR{form}})}
1192 Evaluate \VAR{form}s with \VAR{foo} locally bound to an output
1193 \kwd{string-stream}. Append output to \VAR{string} and return
1194 \retval{values of \VAR{form}s} if \VAR{string} is given. Return
1195 \retval{string containing output} otherwise.
1198 \IT{(\FU*{STREAM-EXTERNAL-FORMAT} \VAR{stream})}
1200 \retval{External file format designator}.
1203 \IT{\V{\A terminal-io\A}}
1204 {\index{*TERMINAL-IO*@\A TERMINAL-IO\A}
1205 Bidirectional stream to user terminal.
1208 \IT{\arrGOO{\V{\A standard-input\A}\\
1209 \V{\A standard-output\A}\\
1210 \V{\A error-output\A}}{.}}
1211 {\index{*STANDARD-INPUT*@\A STANDARD-INPUT\A}%
1212 \index{*STANDARD-OUTPUT*@\A STANDARD-OUTPUT\A}%
1213 \index{*ERROR-OUTPUT*@\A ERROR-OUTPUT\A}
1214 Standard input stream, standard output stream,
1215 or standard error output stream, respectively.
1218 \IT{\arrGOO{\V{\A debug-io\A}\\
1219 \V{\A query-io\A}}{.}}
1220 {\index{*DEBUG-IO*@\A DEBUG-IO\A}\index{*QUERY-IO*@\A QUERY-IO\A}
1221 Bidirectional streams for debugging and user interaction.
1224 \end{LIST}
1227 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1228 \subsection{Pathnames and Files}
1229 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1231 \begin{LIST}{1cm}
1233 \IT{(\FU*{MAKE-PATHNAME}
1234 \orGOO{\kwd{:host } \Goo{\VAR{host}\XOR\NIL\XOR\kwd{:unspecific}}\\
1235 \kwd{:device } \Goo{\VAR{device}\XOR\NIL\XOR\kwd{:unspecific}}\\
1236 \kwd{:directory } \xorGOO{%
1237 \Goo{\VAR{directory}\XOR\kwd{:wild}\XOR\NIL\XOR\kwd{:unspecific}}\\
1238 (\xorGOO{%
1239 \kwd{:absolute}\\
1240 \kwd{:relative}
1241 }{\}}\text{ }%
1242 \xorGOO{%
1243 \VAR{directory}\\
1244 \kwd{:wild}\\
1245 \kwd{:wild-inferiors}\\
1246 \kwd{:up}\\
1247 \kwd{:back}
1248 }{\}^{\!\!*}})
1249 }{.}\\
1250 \kwd{:name }
1251 \Goo{\VAR{file-name}\XOR\kwd{:wild}\XOR\NIL\XOR\kwd{:unspecific}}\\
1252 \kwd{:type }
1253 \Goo{\VAR{file-type}\XOR\kwd{:wild}\XOR\NIL\XOR\kwd{:unspecific}}\\
1254 \kwd{:version }
1255 \Goo{\kwd{:newest}\XOR\VAR{version}\XOR\kwd{:wild}\XOR\NIL\XOR\kwd{:unspecific}}\\
1256 \kwd{:defaults }
1257 \VAR{path}\DF{host from \V{\A default-pathname-defaults\A}}\\
1258 \kwd{:case
1259 \Goo{\kwd{:local}\XOR\kwd{:common}}\DF{\kwd{:local}}}}{\}})}
1261 Construct a \retval{logical pathname} if there is a logical
1262 pathname translation for \VAR{host}, otherwise construct a
1263 \retval{physical pathname}. For \kwd{:case :local}, leave case of
1264 components unchanged. For \kwd{:case :common}, leave mixed-case
1265 components unchanged; convert all-uppercase components into local
1266 customary case; do the opposite with all-lowercase components.
1269 \IT{\arrGOO{%
1270 (\xorGOO{\FU*{PATHNAME-HOST}\\
1271 \FU*{PATHNAME-DEVICE}\\
1272 \FU*{PATHNAME-DIRECTORY}\\
1273 \FU*{PATHNAME-NAME}\\
1274 \FU*{PATHNAME-TYPE}}{\}}
1275 \VAR{ path-or-stream }
1276 \Op{\kwd{:case } \xorGOO{\kwd{:local}\\
1277 \kwd{:common}}{\}}\DF{\kwd{:local}}})\\
1278 (\FU*{PATHNAME-VERSION } \VAR{path-or-stream})}{.}}
1280 Return \retval{pathname component}.
1283 \IT{(\FU*{PARSE-NAMESTRING} \VAR{foo}
1284 \OP{\VAR{host}
1285 \OP{\VAR{default-pathname}\DF{\V{\A default-pathname-defaults\A}}
1286 \orGOO{\kwd{:start} \VAR{ start}\DF{\LIT{0}}\\
1287 \kwd{:end} \VAR{ end}\DF{\NIL}\\
1288 \kwd{:junk-allowed} \VAR{ bool}\DF{\NIL}}{\}}}})}
1290 Return \retval{pathname} converted from
1291 string, pathname, or stream \VAR{foo}; and \retvalii{position}
1292 where parsing stopped.
1295 \IT{(\FU*{MERGE-PATHNAMES} \VAR{path-or-stream}
1296 \OP{\VAR{default-path-or-stream}\DF{\V{\A default-pathname-defaults\A}}
1297 \Op{\VAR{default-version}\DF{\kwd{:newest}}}})}
1299 Return \retval{pathname} made by filling in components missing in
1300 \VAR{path-or-stream} from \VAR{default-path-or-stream}.
1303 \IT{\V{\A default-pathname-defaults\A}}
1304 {\index{*DEFAULT-PATHNAME-DEFAULTS*@\A DEFAULT-PATHNAME-DEFAULTS\A}
1305 Pathname to use if one is needed and none supplied.
1308 \IT{(\FU*{USER-HOMEDIR-PATHNAME} \Op{\VAR{host}})}
1310 User's \retval{home directory}.
1313 \IT{(\FU*{ENOUGH-NAMESTRING} \VAR{path-or-stream}
1314 \Op{\VAR{root-path}\DF{\V{\A default-pathname-defaults\A}}})}
1316 Return \retval{minimal path string} that sufficiently describes
1317 the path of \VAR{path-or-stream} relative to \VAR{root-path.}
1320 \IT{\arrGOO{(\FU*{NAMESTRING}\VAR{ path-or-stream})\\
1321 (\FU*{FILE-NAMESTRING}\VAR{ path-or-stream})\\
1322 (\FU*{DIRECTORY-NAMESTRING}\VAR{ path-or-stream})\\
1323 (\FU*{HOST-NAMESTRING}\VAR{ path-or-stream})}{.}}
1325 Return string representing \retval{full pathname}; \retval{name,
1326 type, and version}; \retval{directory name}; or \retval{host
1327 name}, respectively, of \VAR{path-or-stream}.
1330 \IT{(\FU*{TRANSLATE-PATHNAME} \VAR{path-or-stream} \VAR{wildcard-path-a}
1331 \VAR{wildcard-path-b})}
1333 Translate the path of \VAR{path-or-stream} from
1334 \VAR{wildcard-path-a} into \VAR{wildcard-path-b}. Return
1335 \retval{new path}.
1338 \IT{(\FU*{PATHNAME} \VAR{path-or-stream})}
1340 \retval{Pathname} of \VAR{path-or-stream}.
1343 \IT{(\FU*{LOGICAL-PATHNAME} \VAR{logical-path-or-stream})}
1345 \retval{Logical pathname} of \VAR{logical-path-or-stream}.
1346 Logical pathnames are represented as all-uppercase
1347 \LIT{"}%
1348 \Op{\VAR{host}\LIT{:}}%
1349 \Op{\LIT{;}}%
1350 \Goos{\xorGOO{%
1351 \Goop{\VAR{dir}\XOR\LIT{*}}\\
1352 \LIT{**}}{\}}\LIT{;}}%
1353 \Goos{\VAR{name}\XOR\LIT{*}}%
1354 \OP{\LIT{.}%
1355 \xorGOO{%
1356 \Goop{\VAR{type}\XOR\LIT{*}}\\
1357 \LIT{LISP}}{\}}%
1358 \penalty-5
1359 \Op{\LIT{.}%
1360 \Goo{%
1361 \VAR{version}\XOR\LIT{*}\XOR\LIT{newest}\XOR\LIT{NEWEST}}}}%
1362 \LIT{"}.
1363 \index{*@\A}\index{**@\A\A}%
1366 \IT{(\FU*{LOGICAL-PATHNAME-TRANSLATIONS} \VAR{logical-host})}
1368 \retval{List of (\VAR{from-wildcard to-wildcard}) translations}
1369 for \VAR{logical-host}. \kwd{setf}able.
1372 \IT{(\FU*{LOAD-LOGICAL-PATHNAME-TRANSLATIONS} \VAR{logical-host})}
1374 Load \VAR{logical-host}'s translations. Return \retval{\NIL} if already
1375 loaded; return \retval{\T} if successful.
1378 \IT{(\FU*{TRANSLATE-LOGICAL-PATHNAME} \VAR{path-or-stream})}
1380 \retval{Physical pathname} corresponding to (possibly logical)
1381 pathname of \VAR{path-or-stream}.
1384 \IT{\arrGOO{(\FU*{PROBE-FILE} \VAR{ file})\\
1385 (\FU*{TRUENAME} \VAR{ file})}{.}}
1387 \retval{Canonical name} of \VAR{file}. If \VAR{file} does not exist,
1388 return \retval{\NIL}/signal \kwd{file-error}, respectively.
1391 \IT{(\FU*{FILE-WRITE-DATE} \VAR{file})}
1393 \retval{Time} at which \VAR{file} was last written.
1396 \IT{(\FU*{FILE-AUTHOR} \VAR{file})\qquad\qquad}
1398 Return \retval{name of \VAR{file} owner}.
1401 \IT{(\FU*{FILE-LENGTH} \VAR{stream})}
1403 Return \retval{length of \VAR{stream}}.
1406 \IT{(\FU*{RENAME-FILE} \VAR{foo} \VAR{bar})}
1408 Rename file \VAR{foo} to \VAR{bar}. Unspecified components of path
1409 \VAR{bar} default to those of \VAR{foo}. Return \retval{new
1410 pathname}, \retvalii{old physical file name}, and \retvaliii{new
1411 physical file name}.
1414 \IT{(\FU*{DELETE-FILE} \VAR{file})}
1416 Delete \VAR{file}. Return \retval{\T}.
1419 \IT{(\FU*{DIRECTORY} \VAR{path})}
1421 \retval{List of pathnames} matching \VAR{path}.
1424 \IT{(\FU*{ENSURE-DIRECTORIES-EXIST} \VAR{path} \Op{\kwd{:verbose}
1425 \VAR{bool}})}
1427 Create parts of \retval{\VAR{path}} if necessary. Second return value is
1428 \retvalii{\T} if something has been created.
1431 \end{LIST}
1435 % LocalWords: ies argumenth ar gu ment
1437 %%% Local Variables:
1438 %%% mode: latex
1439 %%% TeX-master: "clqr"
1440 %%% End: