Update README
[clqr.git] / clqr-input-output.tex
blobbb71d7b658e6347fab2d8ad37e601f6af15fc694
1 % Copyright (C) 2008, 2009, 2010, 2011 Bert Burgemeister
3 % Permission is granted to copy, distribute and/or modify this
4 % document under the terms of the GNU Free Documentation License,
5 % Version 1.2 or any later version published by the Free Software
6 % Foundation; 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 p.\ \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 pretty.
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 stream and a \kwd{\&rest} argument applying \FU{format} to
717 stream, \VAR{control}, and the \kwd{\&rest} argument
718 returning \NIL\ or any excess arguments.
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 \OPn{\VAR{arg}}.
728 Output to \VAR{out-string}, \VAR{out-stream} or, if first
729 argument is \T, to \V{\A standard-output\A}. Return \retval{\NIL}. If
730 first argument is \NIL, return \retval{formatted output}.
733 \begin{LIST}{.5cm}
735 \IT{\KWD{\TLD} \Op{\VAR{min-col}\DF{\LIT{0}}} \OP{\KWD{,}\Op{\VAR{col-inc}\DF{\LIT{1}}}
736 \OP{\KWD{,}\Op{\VAR{min-pad}\DF{\LIT{0}}}
737 \OP{\KWD{,}\VAR{pad-char}\DF{\kwd{'}\textvisiblespace}}}}
738 \KWD{\Op{:} \Op{@} \Goo{A\XOR S}}}
739 {\index{\~S@$\sim$S}\index{\~A@$\sim$A}%
740 \EM{Aesthetic/Standard. }
741 Print argument of any type for consumption by humans/by the
742 reader, respectively. With \kwd{:}, print \NIL\ as \LIT{()} rather
743 than \LIT{nil}; with \kwd{@}, add \VAR{pad-char}s on the left
744 rather than on the right.
747 \IT{\KWD{\TLD} \Op{\VAR{radix}\DF{\LIT{10}}} \OP{\KWD{,}\Op{\VAR{width}}
748 \OP{\KWD{,}\Op{\VAR{pad-char}\DF{\kwd{'}\textvisiblespace}}
749 \OP{\KWD{,}\Op{\VAR{comma-char}\DF{\kwd{'}\LIT{,}}}
750 \OP{\KWD{,}\VAR{comma-interval}\DF{\LIT{3}}}}}}
751 \KWD{\Op{:} \Op{@} R}}
752 {\index{\~R@$\sim$R}%
753 \EM{Radix. }
754 (With one or more prefix arguments.) Print argument as number; with
755 \KWD{:}, group digits \VAR{comma-interval} each; with \kwd{@},
756 always prepend a sign.
759 \IT{\Goo{\KWD{\TLD R}\XOR\KWD{\TLD :R}\XOR\KWD{\TLD
760 @R}\XOR\KWD{\TLD @:R}}}
762 \EM{Roman. }
763 Take argument as number and print it as English cardinal number,
764 as English ordinal number, as Roman numeral, or as old Roman
765 numeral, respectively.
768 \IT{\KWD{\TLD} \Op{\VAR{width}}
769 \OP{\KWD{,}\Op{\VAR{pad-char}\DF{\kwd{'}\textvisiblespace}}
770 \OP{\KWD{,}\Op{\VAR{comma-char}\DF{\kwd{'}\LIT{,}}}
771 \OP{\KWD{,}\VAR{comma-interval}\DF{\LIT{3}}}}}
772 \KWD{\Op{:} \Op{@} \Goo{D\XOR B\XOR O\XOR X}}}
773 {\index{\~D@$\sim$D}\index{\~B@$\sim$B}\index{\~O@$\sim$O}\index{\~X@$\sim$X}%
774 \EM{Decimal/Binary/Octal/Hexadecimal. }
775 Print integer argument as number. With \kwd{:}, group digits
776 \VAR{comma-interval} each; with \kwd{@}, always prepend a sign.
779 \IT{\KWD{\TLD} \Op{\VAR{width}} \OP{\KWD{,}\Op{\VAR{dec-digits}}
780 \OP{\KWD{,}\Op{\VAR{shift}\DF{\LIT{0}}}
781 \OP{\KWD{,}\Op{\VAR{overflow-char}}
782 \OP{\KWD{,}\VAR{pad-char}\DF{\kwd{'}\textvisiblespace}}}}}
783 \KWD{\Op{@} F}}
784 {\index{\~F@$\sim$F}%
785 \EM{Fixed-Format Floating-Point. } With
786 \kwd{@}, always pre\-pend a sign.
789 \IT{\KWD{\TLD} \Op{\VAR{width}} \OP{\KWD{,}\Op{\VAR{int-digits}}
790 \OP{\KWD{,}\Op{\VAR{exp-digits}}
791 \OP{\KWD{,}\Op{\VAR{scale-factor}\DF{\LIT{1}}}
792 \OP{\KWD{,}\Op{\VAR{overflow-char}}
793 \OP{\KWD{,}\Op{\VAR{pad-char}\DF{\kwd{'}\textvisiblespace}}
794 \OP{\KWD{,}\VAR{exp-char}}}}}}}
795 \KWD{\Op{@} \Goo{E\XOR G}}}
796 {\index{\~E@$\sim$E}\index{\~G@$\sim$G}%
797 \EM{Exponential/General Floating-Point. }
798 Print argument as floating-point number with \VAR{int-digits}
799 before decimal point and \VAR{exp-digits} in the signed
800 exponent. With \KWD{\TLD G}, choose either \KWD{\TLD E} or
801 \KWD{\TLD F}. With \KWD{@}, always prepend a sign.
804 \IT{\KWD{\TLD} \Op{\VAR{dec-digits}\DF{\LIT{2}}}
805 \OP{\KWD{,}\Op{\VAR{int-digits}\DF{\LIT{1}}}
806 \OP{\KWD{,}\Op{\VAR{width}\DF{\LIT{0}}}
807 \OP{\KWD{,}\VAR{pad-char}\DF{\kwd{'}\textvisiblespace}}}}
808 \Op{\KWD{:}} \Op{\kwd{@}} \KWD{\$}}
809 {\index{\~\$@$\sim$\$}%
810 \EM{Monetary Floating-Point. }
811 Print argument as fixed-format floating-point number. With \KWD{:},
812 put sign before any padding; with \KWD{@}, always prepend a
813 sign.
816 \IT{\Goo{\KWD{\TLD C}\XOR\KWD{\TLD :C}\XOR\KWD{\TLD
817 @C}\XOR\KWD{\TLD @:C}}}
818 {\index{\~C@$\sim$C}%
819 \EM{Character. }
820 Print, spell out, print in \kwd{\#$\backslash$} syntax, or tell
821 how to type, respectively, argument as (possibly non-printing)
822 character.
825 \IT{\Goo{%
826 \KWD{\TLD(} \VAR{text} \KWD{\TLD)}\XOR
827 \KWD{\TLD:(} \VAR{text} \KWD{\TLD)}\XOR
828 \KWD{\TLD @(} \VAR{text} \KWD{\TLD)}\XOR
829 \KWD{\TLD:@(} \VAR{text} \KWD{\TLD)}}}
830 {\index{\~(\~)@$\sim$( $\sim$)}%
831 \EM{Case-Conversion. }
832 Convert \VAR{text} to lowercase, convert first letter of each word
833 to uppercase, capitalize first word and convert the rest to
834 lowercase, or convert to uppercase, respectively.
837 \IT{\Goo{\KWD{\TLD P}\XOR\KWD{\TLD:P}
838 \XOR\KWD{\TLD @P}\XOR\KWD{\TLD:@P}}}
839 {\index{\~P@$\sim$P}%
840 \EM{Plural. }
841 If argument \kwd{eql} \LIT{1} print nothing, otherwise print \LIT{s};
842 do the same for the previous argument; if argument \kwd{eql} \LIT{1}
843 print \LIT{y}, otherwise print \LIT{ies}; do the same for the
844 previous argument, respectively.
847 \IT{\KWD{\TLD} \Op{\VAR{n}\DF{\LIT{1}}} \KWD{\%}}
848 {\index{\~\%@$\sim$\%}%
849 \EM{Newline. }
850 Print \VAR{n} newlines.
853 \IT{\KWD{\TLD} \Op{\VAR{n}\DF{\LIT{1}}} \KWD{\&}}
854 {\index{\~\&@$\sim$\&}%
855 \EM{Fresh-Line. }
856 Print $n-1$ newlines if output stream is at the
857 beginning of a line, or \VAR{n} newlines otherwise.
860 \IT{\Goo{\KWD{\TLD\_}\XOR\KWD{\TLD:\_}\XOR\KWD{\TLD@\_}\XOR\KWD{\TLD:@\_}}}
861 {\index{\~\_{}@$\sim$\_{}}%
862 \EM{Conditional Newline. }
863 Print a newline like \kwd{pprint-newline} with argument
864 \kwd{:linear}, \kwd{:fill}, \kwd{:miser}, or \kwd{:mandatory}, respectively.
867 \IT{\Goo{\KWD{\TLD:$\hookleftarrow$}\XOR\KWD{\TLD@$\hookleftarrow$}\XOR\KWD{\TLD$\hookleftarrow$}}}
868 {\index{\~\~bogus-ordering{}@$\sim\hookleftarrow$}%
869 \EM{Ignored Newline. } Ignore newline, or whitespace following
870 newline, or both, respectively.
873 \IT{\KWD{\TLD} \Op{\VAR{n}\DF{\LIT{1}}} \KWD{\boldmath$|$}}
874 {\index{\~\textbar@$\sim${$"|$}}%
875 \EM{Page. }
876 Print \VAR{n} page separators.
879 \IT{\KWD{\TLD} \Op{\VAR{n}\DF{\LIT{1}}} \KWD{\TLD}}
880 {\index{\~\~@$\sim$$\sim$}%
881 \EM{Tilde. }
882 Print \VAR{n} tildes.
885 \IT{\KWD{\TLD} \Op{\VAR{min-col}\DF{\LIT{0}}}
886 \OP{\KWD{,}\Op{\VAR{col-inc}\DF{\LIT{1}}}
887 \OP{\KWD{,}\Op{\VAR{min-pad}\DF{\LIT{0}}}
888 \OP{\KWD{,}\VAR{pad-char}\DF{\kwd{'}\textvisiblespace}}}}
889 \KWD{\Op{:} \Op{@} \boldmath{$<$}}
890 \OP{\VAR{nl-text} \KWD{\TLD}\Op{\VAR{spare}\DF{\LIT{0}} \Op{\KWD{,}\VAR{width}}}\kwd{:;}}
891 \Goos{\VAR{text} \KWD{\TLD;}} \VAR{text} \KWD{\TLD\boldmath{$>$}}}
892 {\index{\~<\~>@$\sim$$<$ $\sim$$>$}%
893 \EM{Justification. }
894 Justify text produced by \VAR{text}s in a field of at least
895 \VAR{min-col} columns. With \kwd{:}, right justify; with \kwd{@},
896 left justify. If this would leave less than \VAR{spare} characters
897 on the current line, output \VAR{nl-text} first.
900 \IT{\KWD{\TLD} \Op{\KWD{:}} \Op{\KWD{@}} \KWD{\boldmath{$<$}}
901 \GOo{\Op{\VAR{prefix}\DF{\LIT{""}}
902 \KWD{\TLD;}}\XOR\Op{\VAR{per-line-prefix}
903 \KWD{\TLD@;}}}
904 \VAR{body} \OP{\KWD{\TLD;} \VAR{suffix}\DF{\LIT{""}}}
905 \KWD{\TLD:} \Op{\KWD{@}} \KWD{\boldmath{$>$}}}
906 {\index{\~<\~:>@$\sim$$<$ $\sim$:$>$}%
907 \EM{Logical Block. }
908 Act like \kwd{pprint-logical-block} using \VAR{body} as \FU{format}
909 control string on the elements of the list argument or, with \KWD{@},
910 on the remaining arguments, which are extracted by
911 \kwd{pprint-pop}. With \KWD{:}, \VAR{prefix} and \VAR{suffix}
912 default to \LIT{(} and \LIT{)}. When closed by
913 \KWD{\TLD:@\boldmath{$>$}}, spaces in \VAR{body} are replaced with
914 conditional newlines.
917 \IT{\Goo{\KWD{\TLD} \Op{\VAR{n}\DF{\LIT{0}}}
918 \kwd{I}\XOR\KWD{\TLD} \Op{\VAR{n}\DF{\LIT{0}}} \kwd{:I}}}
919 {\index{\~I@$\sim$I}%
920 \EM{Indent. }
921 Set indentation to \VAR{n} relative to leftmost/to current
922 position.
925 \IT{\KWD{\TLD} \Op{\VAR{c}\DF{\LIT{1}}}
926 \Op{\KWD{,}\VAR{i}\DF{\LIT{1}}} \Op{\KWD{:}} \Op{\KWD{@}} \KWD{T}}
927 {\index{\~T@$\sim$T}%
928 \EM{Tabulate. }
929 Move cursor forward to column number $c + ki$, $k \geq 0$ being as small
930 as possible. With \kwd{:}, calculate column numbers relative to
931 the immediately enclosing section. With \kwd{@}, move to column
932 number $c_0 + c + ki$ where $c_0$ is the current position.
935 \IT{\Goo{%
936 \KWD{\TLD} \Op{\VAR{m}\DF{\LIT{1}}} \KWD{\A}\XOR
937 \KWD{\TLD} \Op{\VAR{m}\DF{\LIT{1}}} \KWD{:}\KWD{\A}\XOR
938 \KWD{\TLD} \Op{\VAR{n}\DF{\LIT{0}}} \KWD{@}\KWD{\A}}}
939 {\index{\~*@$\sim$\A}%
940 \EM{Go-To. }
941 Jump \VAR{m} arguments forward, or backward, or to argument \VAR{n}.
944 \IT{\KWD{\TLD} \Op{\VAR{limit}} \Op{\KWD{{:}}} \Op{\kwd{@}}
945 \KWD{\boldmath{$\{$}} \VAR{text} \KWD{\TLD\boldmath{$\}$}}}
946 {\index{\~\{\~\}@$\sim$$\{$ $\sim\}$}%
947 \EM{Iteration. }
948 Use \VAR{text} repeatedly, up to \VAR{limit}, as control
949 string for the elements of the list argument or (with
950 \kwd{@}) for the remaining arguments. With \kwd{:} or \kwd{:@},
951 list elements or remaining arguments should be
952 lists of which a new one is used at each iteration step.
955 \IT{\KWD{\TLD} \OP{\VAR{x} \OP{\kwd{,}\VAR{y} \Op{\kwd{,}\VAR{z}}}}
956 \KWD{\^{}}}
957 {\index{\~\^{}@$\sim$\^{}}%
958 \EM{Escape Upward. }
959 Leave immediately \kwd{\TLD\boldmath{$<$} \TLD\boldmath{$>$}},
960 \kwd{\TLD\boldmath{$<$} \TLD:\boldmath{$>$}},
961 \kwd{\TLD\boldmath{$\{$} \TLD\boldmath{$\}$}}, \kwd{\TLD?}, or the
962 entire \FU{format} operation. With one to three prefixes, act only
963 if $x=0$, $x=y$, or $x\leq y \leq z$, respectively.
966 \IT{\KWD{\TLD} \Op{\VAR{i}} \Op{\KWD{:}} \Op{\KWD{@}}
967 \KWD{[} \Op{\Goos{\VAR{text} \KWD{\TLD;}} \VAR{text}}
968 \Op{\kwd{\TLD:;} \VAR{default}} \KWD{\TLD]}}
969 {\index{\~[\~]@$\sim$[ $\sim$]}%
970 \EM{Conditional Expression. }
971 Use the zero-indexed argumenth (or
972 \VAR{i}th if given) \VAR{text} as a \FU{format} control subclause.
973 With \kwd{:}, use the first \VAR{text} if the argument value is
974 \NIL, or the second \VAR{text} if it is \T. With \kwd{@}, do nothing
975 for an argument value of \NIL. Use the only \VAR{text} and leave
976 the argument to be read again if it is \T.
979 \IT{\KWD{\TLD} \Op{\KWD{@}} \KWD{?}}
980 {\index{\~?@$\sim$?}%
981 \EM{Recursive Processing. }
982 Process two arguments as control string and argument list. With
983 \kwd{@}, take one argument as control string and use then the
984 rest of the original arguments.
987 \IT{\KWD{\TLD} \OP{\VAR{prefix} \Goos{\kwd{,}%
988 \VAR{prefix}}}
989 \Op{\kwd{:}} \Op{\kwd{@}}
990 \KWD{/}\OP{\VAR{package}
991 \LIT{:}\Op{\LIT{:}}\DF{\LIT{cl-user:}}}\VAR{function}\KWD{/}}
992 {\index{\~/ /@$\sim$/ /}%
993 \EM{Call Function. }
994 Call all-uppercase \VAR{package\KWD{::}function} with the
995 arguments stream, format-ar\-gu\-ment, colon-p, at-sign-p and
996 \VAR{prefix}es for printing format-argument.
999 \IT{\KWD{\TLD} \Op{\KWD{:}} \Op{\KWD{@}} \KWD{W}}
1000 {\index{\~W@$\sim$W}%
1001 \EM{Write. }
1002 Print argument of any type obeying every printer control
1003 variable. With \kwd{:}, pretty-print. With \kwd{@}, print
1004 without limits on length or depth.
1007 \IT{\Goo{\KWD{V}\XOR\KWD{\#}}}
1008 {\index{V}\index{\#}
1009 In place of the comma-separated prefix parameters: use next
1010 argument or number of remaining unprocessed arguments, respectively.
1013 \end{LIST}
1015 \end{LIST}
1018 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1019 \subsection{Streams}
1020 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1022 \begin{LIST}{1cm}
1024 \IT{(\FU*{OPEN} \VAR{path}
1025 \orGOO{\kwd{:direction }
1026 \xorGOO{\kwd{:input}\\
1027 \kwd{:output}\\
1028 \kwd{:io}\\
1029 \kwd{:probe}}{\}}\DF{\kwd{:input}}\\
1030 \kwd{:element-type }
1031 \xorGOO{\VAR{type}\\
1032 \kwd{:default}}{\}}\DF{\kwd{character}}\\
1033 \kwd{:if-exists }
1034 \xorGOO{\kwd{:new-version}\\
1035 \kwd{:error}\\
1036 \kwd{:rename}\\
1037 \kwd{:rename-and-delete}\\
1038 \kwd{:overwrite}\\
1039 \kwd{:append}\\
1040 \kwd{:supersede}\\
1041 \NIL}{\}}\DF{\parbox{20mm}{%
1042 \kwd{:new-version} if \VAR{path} specifies \kwd{:newest};\\
1043 \NIL\ otherwise}}\\
1044 \kwd{:if-does-not-exist }
1045 \xorGOO{\kwd{:error}\\
1046 \kwd{:create}\\
1047 \NIL}{\}}\DF{\parbox{27mm}{%
1048 \NIL\ for \kwd{:direction :probe};\\
1049 \mbox{\Goo{\kwd{:create}\XOR\kwd{:error}} otherwise}}}\\
1050 \kwd{:external-format } \VAR{format}\DF{\kwd{:default}}%
1051 }{\}})}
1052 {\label{open}
1053 Open \retval{\kwd{file-stream} to \VAR{path}}.
1056 \IT{\arrGOO{%
1057 (\FU*{MAKE-CONCATENATED-STREAM } \OPn{\VAR{input-stream}})\\
1058 (\FU*{MAKE-BROADCAST-STREAM } \OPn{\VAR{output-stream}})\\
1059 (\FU*{MAKE-TWO-WAY-STREAM } \VAR{input-stream-part } \VAR{output-stream-part})\\
1060 (\FU*{MAKE-ECHO-STREAM } \VAR{from-input-stream } \VAR{to-output-stream})\\
1061 (\FU*{MAKE-SYNONYM-STREAM } \VAR{variable-bound-to-stream})}{.}}
1063 Return \retval{stream} of indicated type.
1066 \IT{(\FU*{MAKE-STRING-INPUT-STREAM} \VAR{string}
1067 \OP{\VAR{start}\DF{\LIT{0}}
1068 \Op{\VAR{end}\DF{\NIL}}})}
1070 Return a \retval{\kwd{string-stream}} supplying the characters from \VAR{string}.
1073 \IT{(\FU*{MAKE-STRING-OUTPUT-STREAM} \Op{\kwd{:element-type}
1074 \VAR{type}\DF{\kwd{character}}})}
1076 Return a \retval{\kwd{string-stream}} accepting characters
1077 (available via \FU{get-output-stream-string}).
1080 \IT{\arrGOO{(\FU*{CONCATENATED-STREAM-STREAMS } \VAR{concatenated-stream})\\
1081 (\FU*{BROADCAST-STREAM-STREAMS } \VAR{broadcast-stream})}{.}}
1083 Return \retval{list of streams} \VAR{concatenated-stream} still
1084 has to read from/\VAR{broadcast-stream} is
1085 broadcasting to.
1088 \IT{\arrGOO{%
1089 (\FU*{TWO-WAY-STREAM-INPUT-STREAM} \VAR{ two-way-stream})\\
1090 (\FU*{TWO-WAY-STREAM-OUTPUT-STREAM} \VAR{ two-way-stream})\\
1091 (\FU*{ECHO-STREAM-INPUT-STREAM} \VAR{ echo-stream})\\
1092 (\FU*{ECHO-STREAM-OUTPUT-STREAM} \VAR{ echo-stream})}{.}}
1094 Return \retval{source stream} or \retval{sink stream} of
1095 \VAR{two-way-stream}\slash\VAR{echo-stream}, respectively.
1098 \IT{(\FU*{SYNONYM-STREAM-SYMBOL} \VAR{synonym-stream})}
1100 Return \retval{symbol} of \VAR{synonym-stream}.
1103 \IT{(\FU*{GET-OUTPUT-STREAM-STRING} \DES{\VAR{string-stream}})}
1105 Clear and return as a \retval{string} characters on
1106 \VAR{string-stream}.
1109 \IT{(\FU*{FILE-POSITION} \VAR{stream} \Op{\xorGOO{\kwd{:start}\\
1110 \kwd{:end}\\
1111 \VAR{position}}{\}}})}
1113 Return \retval{position within stream}, or set it to
1114 \retval{\VAR{position}} and return \retval{\T} on success.
1117 \IT{(\FU*{FILE-STRING-LENGTH} \VAR{stream} \VAR{foo})}
1119 \retval{Length} \VAR{foo} would have in \VAR{stream}.
1122 \IT{(\FU*{LISTEN} \Op{\VAR{stream}\DF{\V{\A standard-input\A}}})}
1124 \retval{\T} if there is a character in input \VAR{stream}.
1127 \IT{(\FU*{CLEAR-INPUT}
1128 \Op{\DES{\VAR{stream}}\DF{\V{\A standard-input\A}}})}
1130 Clear input from \VAR{stream}, return \retval{\NIL}.
1133 \IT{(\xorGOO{\FU*{CLEAR-OUTPUT}\\
1134 \FU*{FORCE-OUTPUT}\\
1135 \FU*{FINISH-OUTPUT}}{\}}
1136 \Op{\DES{\VAR{stream}}\DF{\V{\A standard-output\A}}})}
1138 End output to \VAR{stream} and return \retval{\NIL} immediately,
1139 after initiating flushing of buffers, or after flushing of
1140 buffers, respectively.
1143 \IT{(\FU*{CLOSE} \DES{\VAR{stream}} \Op{\kwd{:abort}
1144 \VAR{bool}\DF{\NIL}})}
1146 Close \VAR{stream}. Return \retval{\T} if \VAR{stream} had been
1147 open. If \kwd{:abort} is \T, delete associated file.
1150 \IT{(\MC*{WITH-OPEN-FILE} (\VAR{stream} \VAR{path}
1151 \OPn{\VAR{open-arg}}) \OPn{(\kwd{declare} \OPn{\NEV{\VAR{decl}}})}
1152 \PROGN{\VAR{form}})}
1154 Use \FU{OPEN} with \VAR{open-arg}s to temporarily create
1155 \VAR{stream} to \VAR{path}; return \retval{values of
1156 \VAR{form}s}.
1159 \IT{(\MC*{WITH-OPEN-STREAM} (\VAR{foo} \DES{\VAR{stream}})
1160 \OPn{(\kwd{declare} \OPn{\NEV{\VAR{decl}}})} \PROGN{\VAR{form}})}
1162 Evaluate \VAR{form}s with \VAR{foo} locally bound to
1163 \VAR{stream}. Return \retval{values of \VAR{form}s}.
1166 \IT{(\MC*{WITH-INPUT-FROM-STRING} (\VAR{foo} \VAR{string}
1167 \orGOO{\kwd{:index } \DES{\VAR{index}}\\
1168 \kwd{:start} \VAR{ start}\DF{\LIT{0}}\\
1169 \kwd{:end} \VAR{ end}\DF{\NIL}}{\}}) \OPn{(\kwd{declare}
1170 \OPn{\NEV{\VAR{decl}}})} \PROGN{\VAR{form}})}
1172 Evaluate \VAR{form}s with \VAR{foo} locally bound to input
1173 \kwd{string-stream} from \VAR{string}. Return \retval{values of
1174 \VAR{form}s}; store next reading position into \VAR{index}.
1177 \IT{(\MC*{WITH-OUTPUT-TO-STRING} (\VAR{foo}
1178 \OP{\DES{\VAR{string}}\DF{\NIL}
1179 \Op{\kwd{:element-type}
1180 \VAR{type}\DF{\kwd{character}}}})
1181 \OPn{(\kwd{declare}
1182 \OPn{\NEV{\VAR{decl}}})} \PROGN{\VAR{form}})}
1184 Evaluate \VAR{form}s with \VAR{foo} locally bound to an output
1185 \kwd{string-stream}. Append output to \VAR{string} and return
1186 \retval{values of \VAR{form}s} if \VAR{string} is given. Return
1187 \retval{string containing output} otherwise.
1190 \IT{(\FU*{STREAM-EXTERNAL-FORMAT} \VAR{stream})}
1192 \retval{External file format designator}.
1195 \IT{\V{\A terminal-io\A}}
1196 {\index{*TERMINAL-IO*@\A TERMINAL-IO\A}
1197 Bidirectional stream to user terminal.
1200 \IT{\arrGOO{\V{\A standard-input\A}\\
1201 \V{\A standard-output\A}\\
1202 \V{\A error-output\A}}{.}}
1203 {\index{*STANDARD-INPUT*@\A STANDARD-INPUT\A}%
1204 \index{*STANDARD-OUTPUT*@\A STANDARD-OUTPUT\A}%
1205 \index{*ERROR-OUTPUT*@\A ERROR-OUTPUT\A}
1206 Standard input stream, standard output stream,
1207 or standard error output stream, respectively.
1210 \IT{\arrGOO{\V{\A debug-io\A}\\
1211 \V{\A query-io\A}}{.}}
1212 {\index{*DEBUG-IO*@\A DEBUG-IO\A}\index{*QUERY-IO*@\A QUERY-IO\A}
1213 Bidirectional streams for debugging and user interaction.
1216 \end{LIST}
1219 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1220 \subsection[Paths and Files]{Pathnames and Files}
1221 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1223 \begin{LIST}{1cm}
1225 \IT{(\FU*{MAKE-PATHNAME}
1226 \orGOO{\kwd{:host } \Goo{\VAR{host}\XOR\NIL\XOR\kwd{:unspecific}}\\
1227 \kwd{:device } \Goo{\VAR{device}\XOR\NIL\XOR\kwd{:unspecific}}\\
1228 \kwd{:directory } \xorGOO{%
1229 \Goo{\VAR{directory}\XOR\kwd{:wild}\XOR\NIL\XOR\kwd{:unspecific}}\\
1230 (\xorGOO{%
1231 \kwd{:absolute}\\
1232 \kwd{:relative}
1233 }{\}}\text{ }%
1234 \xorGOO{%
1235 \VAR{directory}\\
1236 \kwd{:wild}\\
1237 \kwd{:wild-inferiors}\\
1238 \kwd{:up}\\
1239 \kwd{:back}
1240 }{\}^{\!\!*}})
1241 }{.}\\
1242 \kwd{:name } \Goo{\VAR{file-name}\XOR\kwd{:wild}\XOR\NIL\XOR\kwd{:unspecific}}\\
1243 \kwd{:type } \Goo{\VAR{file-type}\XOR\kwd{:wild}\XOR\NIL\XOR\kwd{:unspecific}}\\
1244 \kwd{:version } \Goo{\kwd{:newest}\XOR\VAR{version}\XOR\kwd{:wild}\XOR\NIL\XOR\kwd{:unspecific}}\\
1245 \kwd{:defaults } \VAR{path}\DF{host from \V{\A default-pathname-defaults\A}}\\
1246 \kwd{:case
1247 \Goo{\kwd{:local}\XOR\kwd{:common}}\DF{\kwd{:local}}}}{\}})}
1249 Construct \retval{pathname}.
1250 For \kwd{:case :local}, leave case of components unchanged.
1251 For \kwd{:case :common}, leave mixed-case components unchanged;
1252 convert all-uppercase components into
1253 local customary case; do the opposite with all-lowercase
1254 components.
1257 \IT{\arrGOO{%
1258 (\xorGOO{\FU*{PATHNAME-HOST}\\
1259 \FU*{PATHNAME-DEVICE}\\
1260 \FU*{PATHNAME-DIRECTORY}\\
1261 \FU*{PATHNAME-NAME}\\
1262 \FU*{PATHNAME-TYPE}}{\}}
1263 \VAR{ path }
1264 \Op{\kwd{:case } \xorGOO{\kwd{:local}\\
1265 \kwd{:common}}{\}}\DF{\kwd{:local}}})\\
1266 (\FU*{PATHNAME-VERSION } \VAR{path})}{.}}
1268 Return \retval{pathname component}.
1271 \IT{(\FU*{PARSE-NAMESTRING} \VAR{foo}
1272 \OP{\VAR{host}
1273 \OP{\VAR{default-pathname}\DF{\V{\A default-pathname-defaults\A}}
1274 \orGOO{\kwd{:start} \VAR{ start}\DF{\LIT{0}}\\
1275 \kwd{:end} \VAR{ end}\DF{\NIL}\\
1276 \kwd{:junk-allowed} \VAR{ bool}\DF{\NIL}}{\}}}})}
1278 Return \retval{pathname} converted from
1279 string, pathname, or stream \VAR{foo}; and \retvalii{position}
1280 where parsing stopped.
1283 \IT{(\FU*{MERGE-PATHNAMES} \VAR{pathname}
1284 \OP{\VAR{default-pathname}\DF{\V{\A default-pathname-defaults\A}}
1285 \Op{\VAR{default-version}\DF{\kwd{:newest}}}})}
1287 Return \retval{\VAR{pathname}} after filling in missing components
1288 from \VAR{default-pathname}.
1291 \IT{\V{\A default-pathname-defaults\A}}
1292 {\index{*DEFAULT-PATHNAME-DEFAULTS*@\A DEFAULT-PATHNAME-DEFAULTS\A}
1293 Pathname to use if one is needed and none supplied.
1296 \IT{(\FU*{USER-HOMEDIR-PATHNAME} \Op{\VAR{host}})}
1298 User's \retval{home directory}.
1301 \IT{(\FU*{ENOUGH-NAMESTRING} \VAR{path}
1302 \Op{\VAR{root-path}\DF{\V{\A default-pathname-defaults\A}}})}
1304 Return \retval{minimal path string} to sufficiently describe
1305 \VAR{path} relative to \VAR{root-path.}
1308 \IT{\arrGOO{(\FU*{NAMESTRING}\VAR{ path})\\
1309 (\FU*{FILE-NAMESTRING}\VAR{ path})\\
1310 (\FU*{DIRECTORY-NAMESTRING}\VAR{ path})\\
1311 (\FU*{HOST-NAMESTRING}\VAR{ path})}{.}}
1313 Return string representing \retval{full pathname}; \retval{name,
1314 type, and version}; \retval{directory name}; or \retval{host
1315 name}, respectively, of \VAR{path}.
1318 \IT{(\FU*{TRANSLATE-PATHNAME} \VAR{path} \VAR{wildcard-path-a}
1319 \VAR{wildcard-path-b})}
1321 Translate \VAR{path} from \VAR{wildcard-path-a} into
1322 \VAR{wildcard-path-b}. Return \retval{new path}.
1325 \IT{(\FU*{PATHNAME} \VAR{path})}
1327 \retval{Pathname} of \VAR{path}.
1330 \IT{(\FU*{LOGICAL-PATHNAME} \VAR{logical-path})}
1332 \retval{Logical pathname} of \VAR{logical-path}.
1333 Logical pathnames are represented as all-uppercase
1334 \LIT{\#P"}%
1335 \Op{\VAR{host}\LIT{:}}\Op{\LIT{:}}%
1336 \Goos{\xorGOO{%
1337 \Goop{\VAR{dir}\XOR\LIT{*}}\\
1338 \LIT{**}}{\}}\LIT{;}}%
1339 \penalty-5
1340 \Goos{\VAR{name}\XOR\LIT{*}}%
1341 \OP{\LIT{.}%
1342 \xorGOO{%
1343 \Goop{\VAR{type}\XOR\LIT{*}}\\
1344 \LIT{LISP}}{\}}%
1345 \Op{\LIT{.}%
1346 \Goo{%
1347 \VAR{version}\XOR\LIT{*}\XOR\LIT{newest}\XOR\LIT{NEWEST}}}}%
1348 \LIT{"}.
1349 \index{*@\A}\index{**@\A\A}%
1352 \IT{(\FU*{LOGICAL-PATHNAME-TRANSLATIONS} \VAR{logical-host})}
1354 \retval{List of (\VAR{from-wildcard to-wildcard}) translations}
1355 for \VAR{logical-host}. \kwd{setf}able.
1358 \IT{(\FU*{LOAD-LOGICAL-PATHNAME-TRANSLATIONS} \VAR{logical-host})}
1360 Load \VAR{logical-host}'s translations. Return \retval{\NIL} if already
1361 loaded; return \retval{\T} if successful.
1364 \IT{(\FU*{TRANSLATE-LOGICAL-PATHNAME} \VAR{pathname})}
1366 \retval{Physical pathname} corresponding to (possibly logical)
1367 \VAR{pathname}.
1370 \IT{\arrGOO{(\FU*{PROBE-FILE} \VAR{ file})\\
1371 (\FU*{TRUENAME} \VAR{ file})}{.}}
1373 \retval{Canonical name} of \VAR{file}. If \VAR{file} does not exist,
1374 return \retval{\NIL}/signal \kwd{file-error}, respectively.
1377 \IT{(\FU*{FILE-WRITE-DATE} \VAR{file})}
1379 \retval{Time} at which \VAR{file} was last written.
1382 \IT{(\FU*{FILE-AUTHOR} \VAR{file})\qquad\qquad}
1384 Return \retval{name of \VAR{file} owner}.
1387 \IT{(\FU*{FILE-LENGTH} \VAR{stream})}
1389 Return \retval{length of \VAR{stream}}.
1392 \IT{(\FU*{RENAME-FILE} \VAR{foo} \VAR{bar})}
1394 Rename file \VAR{foo} to \VAR{bar}. Unspecified components of path
1395 \VAR{bar} default to those of \VAR{foo}. Return \retval{new
1396 pathname}, \retvalii{old physical file name}, and \retvaliii{new
1397 physical file name}.
1400 \IT{(\FU*{DELETE-FILE} \VAR{file})}
1402 Delete \VAR{file}. Return \retval{\T}.
1405 \IT{(\FU*{DIRECTORY} \VAR{path})}
1407 \retval{List of pathnames} matching \VAR{path}.
1410 \IT{(\FU*{ENSURE-DIRECTORIES-EXIST} \VAR{path} \Op{\kwd{:verbose}
1411 \VAR{bool}})}
1413 Create parts of \retval{\VAR{path}} if necessary. Second return value is
1414 \retvalii{\T} if something has been created.
1417 \end{LIST}
1421 % LocalWords: ies argumenth ar gu ment
1423 %%% Local Variables:
1424 %%% mode: latex
1425 %%% TeX-master: "clqr"
1426 %%% End: