Unfinished work on figure Data Types.
[clqr.git] / clqr-input-output.tex
blobab4f44b727be203b04c8c4cfd6d4e4e267174400
1 % Copyright (C) 2008, 2009 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 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 \VAR{stream}. Return \retval{index} of
158 \VAR{sequence}'s first unmodified
159 element.
162 \IT{(\FU*{READTABLE-CASE} \VAR{readtable})\DF{\kwd{:upcase}}}
164 \retval{Case sensitivity attribute} (one of \kwd{:upcase},
165 \kwd{:downcase}, \kwd{:preserve}, \kwd{:invert}) of
166 \VAR{readtable}. \kwd{setf}able.
169 \IT{(\FU*{COPY-READTABLE} \OP{\VAR{from-readtable}\DF{\V{\A readtable\A}}
170 \Op{\DES{\VAR{to-readtable}}\DF{\NIL}}})}
172 Return \retval{copy of \VAR{from-readtable}}.
175 \IT{(\FU*{SET-SYNTAX-FROM-CHAR} \VAR{to-char} \VAR{from-char}
176 \OP{\DES{\VAR{to-readtable}}\DF{\V{\A readtable\A}}
177 \Op{\VAR{from-readtable}\DF{standard readtable}}})}
179 Copy syntax of \VAR{from-char} to \VAR{to-readtable}. Return \retval{\T}.
182 \IT{\V{\A readtable\A}}
183 {\index{*READTABLE*@\A READTABLE\A}
184 Current readtable.
187 \IT{\V{\A read-base\A}\DF{\LIT{10}}}
188 {\index{*READ-BASE*@\A READ-BASE\A}
189 Radix for reading \kwd{integer}s and \kwd{ratio}s.
192 \IT{\V{\A read-default-float-format\A}\DF{\kwd{single-float}}}
193 {\index{*READ-DEFAULT-FLOAT-FORMAT*@\A READ-DEFAULT-FLOAT-FORMAT\A}
194 Floating point format to use when not indicated in the number read.
197 \IT{\V{\A read-suppress\A}\DF{\NIL}}
198 {\index{*READ-SUPPRESS*@\A READ-SUPPRESS\A}
199 If \T, reader is syntactically more tolerant.
202 \IT{(\FU*{SET-MACRO-CHARACTER} \VAR{char} \VAR{function}
203 \OP{\VAR{non-term-p}\DF{\NIL}
204 \Op{\DES{\VAR{rt}}\DF{\V{\A readtable\A}}}})}
206 Make \VAR{char} a macro character associated with
207 \VAR{function}. Return \retval{\T}.
210 \IT{(\FU*{GET-MACRO-CHARACTER} \VAR{char}
211 \Op{\VAR{rt}\DF{\V{\A readtable\A}}})}
213 \retval{Reader macro function} associated with \VAR{char}, and
214 \retvalii{\T} if \VAR{char} is a non-terminating macro character.
217 \IT{(\FU*{MAKE-DISPATCH-MACRO-CHARACTER} \VAR{char}
218 \OP{\VAR{non-term-p}\DF{\NIL}
219 \Op{\VAR{rt}\DF{\V{\A readtable\A}}}})}
221 Make \VAR{char} a dispatching macro character. Return \retval{\T}.
224 \IT{(\FU*{SET-DISPATCH-MACRO-CHARACTER} \VAR{char} \VAR{sub-char} \VAR{function}
225 \Op{\DES{\VAR{rt}}\DF{\V{\A readtable\A}}})}
227 Make \VAR{function} a dispatch function of \VAR{char} followed by
228 \VAR{sub-char}. Return \retval{\T}.
231 \IT{(\FU*{GET-DISPATCH-MACRO-CHARACTER} \VAR{char} \VAR{sub-char}
232 \Op{\VAR{rt}\DF{\V{\A readtable\A}}})}
234 \retval{Dispatch function} associated with \VAR{char} followed by \VAR{sub-char}.
237 \end{LIST}
239 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
240 \subsection[Macro Chars]{Macro Characters and Escapes}
241 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
243 \begin{LIST}{1cm}
245 \IT{\arrGOO{%
246 \KWD{\#\boldmath$|$ }\OPn{\VAR{multi-line-comment}}\KWD{ \boldmath$|$\#}\\
247 \KWD*{; }\OPn{\VAR{one-line-comment}}}{.}}
248 {\index{\#{$"|$} {$"|$}\#}
249 Comments. There are conventions:
251 \begin{LIST}{.5cm}
252 \IT{\KWD{;;;;} \VAR{title}\qquad\qquad}
253 {Short title for a block of code.}
255 \IT{\KWD{;;;} \VAR{intro}\qquad\qquad}
256 {Description before a block of code.}
258 \IT{\KWD{;;} \VAR{state}\qquad\qquad}
259 {State of program or of following code.}
261 \IT{\KWD{;} \VAR{explanation}}
262 {Regarding line on which it appears.}
264 \end{LIST}
266 \IT{\KWD*{(}\qquad\quad}
268 Initiate reading of a list.
271 \IT{\KWD{"}\qquad\quad}
272 {\index{""}
273 Begin and end of a string.
276 \IT{\KWD*{'}\VAR{foo}\qquad\quad}
278 (\SO{quote} \VAR{foo}); \VAR{foo} unevaluated.
281 \IT{\KWD{\char18}(\Op{\VAR{foo}} \Op{\KWD*{,}\VAR{bar}} \Op{\KWD{,@}\VAR{baz}}
282 \Op{\KWD*{,.}\DES{\VAR{quux}}} \Op{\VAR{bing}})}
283 {\index{,"@}\index{`@\char18}
284 Backquote. \SO{quote} \VAR{foo} and \VAR{bing}; evaluate \VAR{bar}
285 and splice the lists \VAR{baz} and \VAR{quux} into their
286 elements. When nested, outermost commas inside the innermost
287 backquote expression belong to this backquote.
290 \IT{\KWD{\#\boldmath{$\backslash$}}\VAR{c}\qquad\qquad\qquad}
292 (\FU{character} \LIT{"}\VAR{c}\LIT{"}), the character \VAR{c}.
294 \index{\#@\#$\backslash$}%
296 \IT{\KWD*{\#b}; \KWD*{\#o}; \KWD*{\#x}; \KWD{\#}\VAR{n}\KWD{R}}
298 \index{\#R}%
299 Number of radix 2, 8, 16, or \VAR{n}.
302 \IT{\KWD*{\#C(}\VAR{a b}\kwd{)}\qquad\qquad}
304 (\FU{complex} \VAR{a} \VAR{b}), the complex number $\VAR{a}+\VAR{b}\text{i}$.
307 \IT{\KWD*{\#'}\VAR{foo}\qquad\qquad\qquad}
309 (\SO{function} \VAR{foo}); the function named \VAR{foo}.
312 \IT{\KWD{\#}\VAR{n}\KWD{A}\VAR{sequence}}
314 \index{\#A}%
315 \VAR{n}-dimensional array.
318 \IT{\KWD{\#}\Op{\VAR{n}}\kwd{(}\OPn{\VAR{foo}}\kwd{)}}
320 \index{\#(}%
321 Vector of some (or \VAR{n})
322 \VAR{foo}s filled with last \VAR{foo} if necessary.
325 \IT{\KWD{\#}\Op{\VAR{n}}\kwd{\A}\OPn{\VAR{b}}}
327 \index{\#*@\#\A}%
328 Bit vector of some (or \VAR{n})
329 \VAR{b}s filled with last \VAR{b} if necessary.
332 \IT{\KWD*{\#S(}\VAR{type} \Goos{\VAR{slot} \VAR{value}}\kwd{)}}
334 Structure of \VAR{type}.
337 \IT{\KWD*{\#P}\VAR{string}\qquad\qquad}
339 A pathname.
342 \IT{\KWD*{\#:}\VAR{foo}\qquad\qquad\qquad}
344 Uninterned symbol \VAR{foo}.
347 \IT{\KWD*{\#.}\VAR{form}\qquad\qquad}
349 Read-time value of \VAR{form}.
352 \IT{\V{\A read-eval\A}\DF{\T}}
353 {\index{*READ-EVAL*@\A READ-EVAL\A}
354 If \NIL, a \kwd{reader-error} is signalled by \kwd{\#.}.
357 \IT{\KWD{\#}\VAR{int}\kwd{=} \VAR{foo}\qquad\quad}
359 \index{\#=}%
360 Give \VAR{foo} the label \VAR{int}.
363 \IT{\KWD{\#}\VAR{int}\kwd{\#}\qquad\qquad}
365 \index{\#\#}%
366 Object labelled \VAR{int}.
369 \IT{\KWD{\#\boldmath$<$}\qquad\qquad\qquad}
371 \index{\#<@\#$<$}%
372 Have the reader signal \kwd{reader-error}.
375 \IT{\arrGOO{\KWD*{\#+}\VAR{feature } \VAR{when-feature}\\
376 \KWD*{\#--}\VAR{feature } \VAR{unless-feature}}{.}}
378 Means \VAR{when-feature} if \VAR{feature} is \T, means
379 \VAR{unless-feature} if \VAR{feature} is \NIL. \VAR{feature} is a
380 symbol from \V{\A features\A}, or (\Goo{\kwd{AND}\XOR\kwd{OR}}
381 \OPn{\VAR{feature}}), or (\kwd{NOT} \VAR{feature}).
384 \IT{\V{\A features\A}}
385 {\index{*FEATURES*@\A FEATURES\A}
386 List of symbols denoting implementation-dependent features.
389 \IT{\kwd{\boldmath$|$}\OPn{\VAR{c}}\kwd{\boldmath$|$};
390 \kwd{\boldmath$\backslash$}\VAR{c}}
392 Treat arbitrary character(s) \VAR{c} as alphabetic preserving case.
394 \index{\@{$\backslash$}}%
395 \index{{$"|$} {$"|$}}%
397 \end{LIST}
400 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
401 \subsection{Printer}
402 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
405 \begin{LIST}{1cm}
407 \IT{(\xorGOO{\FU*{PRIN1}\\
408 \FU*{PRINT}\\
409 \FU*{PPRINT}\\
410 \FU*{PRINC}}{\}}
411 \VAR{foo} \Op{\DES{\VAR{stream}}\DF{\V{\A standard-output\A}}})}
413 Print \VAR{foo} to \VAR{stream} \FU{read}ably,
414 \FU{read}ably between a newline and a space,
415 \FU{read}ably after a newline, or human-readably without any extra
416 characters, respectively. \FU{prin1}, \FU{print} and \FU{princ}
417 return \retval{\VAR{foo}}.
420 \IT{\arrGOO{(\FU*{PRIN1-TO-STRING} \VAR{ foo})\\
421 (\FU*{PRINC-TO-STRING} \VAR{ foo})}{.}}
423 Print \VAR{foo} to \retval{\VAR{string}} \FU{read}ably or
424 human-readably, respectively.
427 \IT{(\GFU*{PRINT-OBJECT} \VAR{object} \DES{\VAR{stream}})}
429 Print \retval{\VAR{object}} to \VAR{stream}. Called by the Lisp
430 printer.
433 \IT{(\MC*{PRINT-UNREADABLE-OBJECT} (\VAR{foo} \DES{\VAR{stream}}
434 \orGOO{\kwd{:type } \VAR{bool}\DF{\NIL}\\
435 \kwd{:identity } \VAR{bool}\DF{\NIL}}{\}})
436 \PROGN{\VAR{form}})}
438 Enclosed in \kwd{\#\boldmath$<$} and \kwd{\boldmath$>$}, print
439 \VAR{foo} by means of \VAR{form}s to \VAR{stream}. Return \retval{\NIL}.
442 \IT{(\FU*{TERPRI} \Op{\DES{\VAR{stream}}\DF{\V{\A standard-output\A}}})}
444 Output a newline to \VAR{stream}. Return \retval{\NIL}.
447 \IT{(\FU*{FRESH-LINE})
448 \Op{\DES{\VAR{stream}}\DF{\V{\A standard-output\A}}}}
450 Output a newline to \VAR{stream} and return \retval{\T} unless \VAR{stream}
451 is already at the start of a line.
454 \IT{(\FU*{WRITE-CHAR} \VAR{char}
455 \Op{\DES{\VAR{stream}}\DF{\V{\A standard-output\A}}})}
457 Output \retval{\VAR{char}} to \VAR{stream}.
460 \IT{(\xorGOO{\FU*{WRITE-STRING}\\
461 \FU*{WRITE-LINE}}{\}} \VAR{string}
462 \OP{\DES{\VAR{stream}}\DF{\V{\A standard-output\A}}
463 \OP{\orGOO{\kwd{:start} \VAR{ start}\DF{\LIT{0}}\\\kwd{:end} \VAR{
464 end}\DF{\NIL}}{\}}}})}
466 Write \retval{\VAR{string}} to \VAR{stream} without/with a trailing newline.
469 \IT{(\FU*{WRITE-BYTE} \VAR{byte} \DES{\VAR{stream}})}
471 Write \retval{\VAR{byte}} to binary \VAR{stream}.
474 \IT{(\FU*{WRITE-SEQUENCE} \VAR{sequence}
475 \DES{\VAR{stream}} \orGOO{\kwd{:start}\VAR{ start}\DF{\LIT{0}}\\
476 \kwd{:end} \VAR{ end}\DF{\NIL}}{\}})}
478 Write elements of \retval{\VAR{sequence}} to \VAR{stream}.
481 \IT{(\xorGOO{\FU*{WRITE}\\
482 \FU*{WRITE-TO-STRING}}{\}} \VAR{foo} \orGOO{%
483 \kwd{:array} \VAR{ bool}\\
484 \kwd{:base} \VAR{ radix}\\
485 \kwd{:case } \xorGOO{\kwd{:upcase}\\
486 \kwd{:downcase}\\
487 \kwd{:capitalize}}{.}\\
488 \kwd{:circle} \VAR{ bool}\\
489 \kwd{:escape} \VAR{ bool}\\
490 \kwd{:gensym} \VAR{ bool}\\
491 \kwd{:length } \Goo{\VAR{int}\XOR\NIL}\\
492 \kwd{:level } \Goo{\VAR{int}\XOR\NIL}\\
493 \kwd{:lines } \Goo{\VAR{int}\XOR\NIL}\\
494 \kwd{:miser-width } \Goo{\VAR{int}\XOR\NIL}\\
495 \kwd{:pprint-dispatch} \VAR{ dispatch-table}\\
496 \kwd{:pretty} \VAR{ bool}\\
497 \kwd{:radix} \VAR{ bool}\\
498 \kwd{:readably} \VAR{ bool}\\
499 \kwd{:right-margin } \Goo{\VAR{int}\XOR\NIL}\\
500 \kwd{:stream } \DES{\VAR{stream}}\DF{\V{\A standard-output\A}}%
501 }{\}})}
503 Print \VAR{foo} to \VAR{stream} and return \retval{\VAR{foo}}, or print \VAR{foo} into
504 \retval{string}, respectively, after dynamically setting printer variables
505 corresponding to keyword parameters (\kwd{\A print-}\VAR{bar}\kwd{\A} becoming
506 \kwd{:}\VAR{bar}). (\kwd{:stream} keyword with \FU{write} only.)
509 \IT{\arrGOO{%
510 (\FU*{PPRINT-FILL } \DES{\VAR{stream}} \VAR{ foo }
511 \OP{\VAR{parenthesis}\DF{\T} \text{ } \Op{\VAR{noop}}})\\
512 (\FU*{PPRINT-TABULAR } \DES{\VAR{stream}} \VAR{ foo }
513 \OP{\VAR{parenthesis}\DF{\T} \text{ } \Op{\VAR{noop} \text{ }
514 \Op{\VAR{n}\DF{\LIT{16}}}}})\\
515 (\FU*{PPRINT-LINEAR } \DES{\VAR{stream}} \VAR{ foo }
516 \OP{\VAR{parenthesis}\DF{\T} \text{ } \Op{\VAR{noop}}})\\
517 }{.}}
519 Print \VAR{foo} to \VAR{stream}. If \VAR{foo} is a list, print as
520 many elements per line as possible; do the same in a table with
521 a column width of \VAR{n} ems; or print either all elements on
522 one line or each on its own line, respectively. Return
523 \retval{\NIL}. Usable with \FU{format} directive \KWD{\TLD//}.
526 \IT{(\MC*{PPRINT-LOGICAL-BLOCK} (\DES{\VAR{stream}} \VAR{list}
527 \orGOO{\xorGOO{\kwd{:prefix} \VAR{ string}\\
528 \kwd{:per-line-prefix} \VAR{ string}}{\}}\\
529 \kwd{:suffix} \VAR{ string}\DF{\LIT{""}}}{\}})
530 \OPn{(\kwd{declare} \OPn{\NEV{\VAR{decl}}})} \PROGN{\VAR{form}})}
532 Evaluate \VAR{form}s, which should print \VAR{list}, with
533 \VAR{stream} locally bound to a pretty
534 printing stream which outputs to the original \VAR{stream}. If
535 \VAR{list} is in fact not a list, it is printed by
536 \FU{write}. Return \retval{\NIL}.
539 \begin{LIST}{.5cm}
541 \IT{(\MC*{PPRINT-POP})}
543 Take \retval{next element} off \VAR{list}. If there is no remaining
544 tail of \VAR{list}, or \V{\A print-length\A} or \V{\A print-circle\A} indicate
545 printing should end, send element together with an appropriate
546 indicator to \VAR{stream}.
549 \IT{(\FU*{PPRINT-TAB} \xorGOO{\kwd{:line}\\
550 \kwd{:line-relative}\\
551 \kwd{:section}\\
552 \kwd{:section-relative}}{\}} \VAR{c}
553 \VAR{i} \Op{\DES{\VAR{stream}}\DF{\V{\A standard-output\A}}})}
555 Move cursor forward to column number $c + ki$, $k \geq 0$ being as small
556 as possible.
559 \IT{(\FU*{PPRINT-INDENT} \xorGOO{%
560 \kwd{:block}\\
561 \kwd{:current}}{\}} \VAR{n}
562 \OP{\DES{\VAR{stream}}\DF{\V{\A standard-output\A}}})}
564 Specify indentation for innermost logical block relative to
565 leftmost position/to current position. Return \retval{\NIL}.
568 \IT{(\MC*{PPRINT-EXIT-IF-LIST-EXHAUSTED})}
570 If \VAR{list} is empty, terminate logical block. Return
571 \retval{\NIL} otherwise.
574 \end{LIST}
576 \IT{(\FU*{PPRINT-NEWLINE} \xorGOO{%
577 \kwd{:linear}\\
578 \kwd{:fill}\\
579 \kwd{:miser}\\
580 \kwd{:mandatory}}{\}}
581 \OP{\DES{\VAR{stream}}\DF{\V{\A standard-output\A}}})}
583 Print a conditional newline if \VAR{stream} is a pretty printing
584 stream. Return \retval{\NIL}.
587 \IT{\V{\A print-array\A}}
588 {\index{*PRINT-ARRAY*@\A PRINT-ARRAY\A}
589 If \T, print arrays \FU{read}ably.
592 \IT{\V{\A print-base\A}\DF{\LIT{10}}}
593 {\index{*PRINT-BASE*@\A PRINT-BASE\A}
594 Radix for printing rationals, from 2 to 36.
597 \IT{\V{\A print-case\A}\DF{\kwd{:upcase}}}
598 {\index{*PRINT-CASE*@\A PRINT-CASE\A}
599 Print symbol names all uppercase (\kwd{:upcase}), all lowercase
600 (\kwd{:downcase}), capitalized (\kwd{:capitalize}).
603 \IT{\V{\A print-circle\A}\DF{\NIL}}
604 {\index{*PRINT-CIRCLE*@\A PRINT-CIRCLE\A}
605 If \T, avoid indefinite recursion while printing circular
606 structure.
609 \IT{\V{\A print-escape\A}\DF{\T}}
610 {\index{*PRINT-ESCAPE*@\A PRINT-ESCAPE\A}
611 If \NIL, do not print escape characters and package prefixes.
614 \IT{\V{\A print-gensym\A}\DF{\T}}
615 {\index{*PRINT-GENSYM*@\A PRINT-GENSYM\A}
616 If \T, print \kwd{\#:} before uninterned symbols.
619 \IT{\arrGOO{\V{\A print-length\A}\DF{\NIL}\\
620 \V{\A print-level\A}\DF{\NIL}\\
621 \V{\A print-lines\A}\DF{\NIL}
622 }{.}}
623 {\index{*PRINT-LENGTH*@\A PRINT-LENGTH\A}\index{*PRINT-LEVEL*@\A PRINT-LEVEL\A}\index{*PRINT-LINES*@\A PRINT-LINES\A}
624 If integer, restrict printing of objects to that number of elements per
625 level/to that depth/to that number of lines.
628 \IT{\V{\A print-miser-width\A}}
629 {\index{*PRINT-MISER-WIDTH*@\A PRINT-MISER-WIDTH\A}
630 If integer and greater than the width available for printing a
631 substructure, switch to the more compact miser style.
634 \IT{\V{\A print-pretty\A}}
635 {\index{*PRINT-PRETTY*@\A PRINT-PRETTY\A}
636 If \T, print pretty.
639 \IT{\V{\A print-radix\A}\DF{\NIL}}
640 {\index{*PRINT-RADIX*@\A PRINT-RADIX\A}
641 If \T, print rationals with a radix indicator.
644 \IT{\V{\A print-readably\A}\DF{\NIL}}
645 {\index{*PRINT-READABLY*@\A PRINT-READABLY\A}
646 If \T, print \FU{read}ably or signal error
647 \kwd{print-not-readable}.
650 \IT{\V{\A print-right-margin\A}\DF{\NIL}}
651 {\index{*PRINT-RIGHT-MARGIN*@\A PRINT-RIGHT-MARGIN\A}
652 Right margin width in ems while pretty-printing.
655 \IT{(\FU*{SET-PPRINT-DISPATCH} \VAR{type} \VAR{function}
656 \OP{\VAR{priority}\DF{\LIT{0}}
657 \Op{\VAR{table}\DF{\V{\A print-pprint-dispatch\A}}}})}
659 Install entry comprising \VAR{function} of arguments stream and
660 object to print; and \VAR{priority} as
661 \VAR{type} into \VAR{table}. If \VAR{function}
662 is \NIL, remove \VAR{type} from \VAR{table}. Return \retval{\NIL}.
665 \IT{(\FU*{PPRINT-DISPATCH} \VAR{foo}
666 \Op{\VAR{table}\DF{\V{\A print-pprint-dispatch\A}}})}
668 Return highest priority \retval{\VAR{function}} associated with type of
669 \VAR{foo} and \retvalii{\T} if there was a matching type specifier
670 in \VAR{table}.
673 \IT{(\FU*{COPY-PPRINT-DISPATCH}
674 \Op{\VAR{table}\DF{\V{\A print-pprint-dispatch\A}}})}
676 Return \retval{copy of \VAR{table}} or, if \VAR{table} is \NIL,
677 initial value of \V{\A print-pprint-dispatch\A}.
680 \IT{\V{\A print-pprint-dispatch\A}}
681 {\index{*PRINT-PPRINT-DISPATCH*@\A PRINT-PPRINT-DISPATCH\A}
682 Current pretty print dispatch table.
685 \end{LIST}
689 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
690 \subsection{Format}
691 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
692 \label{section:Format}
694 \begin{LIST}{1cm}
696 \IT{(\MC*{FORMATTER} \NEV{\VAR{control}})}
698 Return \retval{function} of stream and a \kwd{\&rest} argument applying \FU{format} to
699 stream, \VAR{control}, and the \kwd{\&rest} argument
700 returning \NIL\ or any excess arguments.
703 \IT{(\FU*{FORMAT} \Goo{\T\XOR\NIL\XOR\VAR{out-string}\XOR\VAR{out-stream}}
704 \VAR{control} \OPn{\VAR{arg}})}
706 Output string \VAR{control} which may
707 contain \kwd{\TLD} directives possibly taking some
708 \VAR{arg}s. Alternatively, \VAR{control} can be a function returned
709 by \MC{formatter} which is then applied to \VAR{out-stream} and \OPn{\VAR{arg}}.
710 Output to \VAR{out-string}, \VAR{out-stream} or, if first
711 argument is \T, to \V{\A standard-output\A}. Return \retval{\NIL}. If
712 first argument is \NIL, return \retval{formatted output}.
715 \begin{LIST}{.5cm}
717 \IT{\KWD{\TLD} \Op{\VAR{min-col}\DF{\LIT{0}}} \OP{\KWD{,}\Op{\VAR{col-inc}\DF{\LIT{1}}}
718 \OP{\KWD{,}\Op{\VAR{min-pad}\DF{\LIT{0}}}
719 \OP{\KWD{,}\VAR{pad-char}\DF{\kwd{'}\textvisiblespace}}}}
720 \KWD{\Op{:} \Op{@} \Goo{A\XOR S}}}
721 {\index{\~S@$\sim$S}\index{\~A@$\sim$A}%
722 \EM{Aesthetic/Standard. }
723 Print argument of any type for consumption by humans/by the
724 reader, respectively. With \kwd{:}, print \NIL\ as \LIT{()} rather
725 than \LIT{nil}; with \kwd{@}, add \VAR{pad-char}s on the left
726 rather than on the right.
729 \IT{\KWD{\TLD} \Op{\VAR{radix}\DF{\LIT{10}}} \OP{\KWD{,}\Op{\VAR{width}}
730 \OP{\KWD{,}\Op{\VAR{pad-char}\DF{\kwd{'}\textvisiblespace}}
731 \OP{\KWD{,}\Op{\VAR{comma-char}\DF{\kwd{'}\LIT{,}}}
732 \OP{\KWD{,}\VAR{comma-interval}\DF{\LIT{3}}}}}}
733 \KWD{\Op{:} \Op{@} R}}
734 {\index{\~R@$\sim$R}%
735 \EM{Radix. }
736 (With one or more prefix arguments.) Print argument as number; with
737 \KWD{:}, group digits \VAR{comma-interval} each; with \kwd{@},
738 always prepend a sign.
741 \IT{\Goo{\KWD{\TLD R}\XOR\KWD{\TLD :R}\XOR\KWD{\TLD
742 @R}\XOR\KWD{\TLD @:R}}}
744 \EM{Roman. }
745 Take argument as number and print it as English cardinal number,
746 as English ordinal number, as Roman numeral, or as old Roman
747 numeral, respectively.
750 \IT{\KWD{\TLD} \Op{\VAR{width}}
751 \OP{\KWD{,}\Op{\VAR{pad-char}\DF{\kwd{'}\textvisiblespace}}
752 \OP{\KWD{,}\Op{\VAR{comma-char}\DF{\kwd{'}\LIT{,}}}
753 \OP{\KWD{,}\VAR{comma-interval}\DF{\LIT{3}}}}}
754 \KWD{\Op{:} \Op{@} \Goo{D\XOR B\XOR O\XOR X}}}
755 {\index{\~D@$\sim$D}\index{\~B@$\sim$B}\index{\~O@$\sim$O}\index{\~X@$\sim$X}%
756 \EM{Decimal/Binary/Octal/Hexadecimal. }
757 Print integer argument as number. With \kwd{:}, group digits
758 \VAR{comma-interval} each; with \kwd{@}, always prepend a sign.
761 \IT{\KWD{\TLD} \Op{\VAR{width}} \OP{\KWD{,}\Op{\VAR{dec-digits}}
762 \OP{\KWD{,}\Op{\VAR{shift}\DF{\LIT{0}}}
763 \OP{\KWD{,}\Op{\VAR{overflow-char}}
764 \OP{\KWD{,}\VAR{pad-char}\DF{\kwd{'}\textvisiblespace}}}}}
765 \KWD{\Op{@} F}}
766 {\index{\~F@$\sim$F}%
767 \EM{Fixed-Format Floating-Point. } With
768 \kwd{@}, always pre\-pend a sign.
771 \IT{\KWD{\TLD} \Op{\VAR{width}} \OP{\KWD{,}\Op{\VAR{int-digits}}
772 \OP{\KWD{,}\Op{\VAR{exp-digits}}
773 \OP{\KWD{,}\Op{\VAR{scale-factor}\DF{\LIT{1}}}
774 \OP{\KWD{,}\Op{\VAR{overflow-char}}
775 \OP{\KWD{,}\Op{\VAR{pad-char}\DF{\kwd{'}\textvisiblespace}}
776 \OP{\KWD{,}\VAR{exp-char}}}}}}}
777 \KWD{\Op{@} \Goo{E\XOR G}}}
778 {\index{\~E@$\sim$E}\index{\~G@$\sim$G}%
779 \EM{Exponential/General Floating-Point. }
780 Print argument as floating-point number with \VAR{int-digits}
781 before decimal point and \VAR{exp-digits} in the signed
782 exponent. With \KWD{\TLD G}, choose either \KWD{\TLD E} or
783 \KWD{\TLD F}. With \KWD{@}, always prepend a sign.
786 \IT{\KWD{\TLD} \Op{\VAR{dec-digits}\DF{\LIT{2}}}
787 \OP{\KWD{,}\Op{\VAR{int-digits}\DF{\LIT{1}}}
788 \OP{\KWD{,}\Op{\VAR{width}\DF{\LIT{0}}}
789 \OP{\KWD{,}\VAR{pad-char}\DF{\kwd{'}\textvisiblespace}}}}
790 \Op{\KWD{:}} \Op{\kwd{@}} \KWD{\$}}
791 {\index{\~\$@$\sim$\$}%
792 \EM{Monetary Floating-Point. }
793 Print argument as fixed-format floating-point number. With \KWD{:},
794 put sign before any padding; with \KWD{@}, always prepend a sign.}
796 \IT{\Goo{\KWD{\TLD C}\XOR\KWD{\TLD :C}\XOR\KWD{\TLD
797 @C}\XOR\KWD{\TLD @:C}}}
798 {\index{\~C@$\sim$C}%
799 \EM{Character. }
800 Print, spell out, print in \kwd{\#$\backslash$} syntax, or tell
801 how to type, respectively, argument as (possibly non-printing)
802 character.
805 \IT{\Goo{%
806 \KWD{\TLD(} \VAR{text} \KWD{\TLD)}\XOR
807 \KWD{\TLD:(} \VAR{text} \KWD{\TLD)}\XOR
808 \KWD{\TLD @(} \VAR{text} \KWD{\TLD)}\XOR
809 \KWD{\TLD:@(} \VAR{text} \KWD{\TLD)}}}
810 {\index{\~(\~)@$\sim$( $\sim$)}%
811 \EM{Case-Conversion. }
812 Convert \VAR{text} to lowercase, convert first letter of each word
813 to uppercase, capitalize first word and convert the rest to
814 lowercase, or convert to uppercase, respectively.
817 \IT{\Goo{\KWD{\TLD P}\XOR\KWD{\TLD:P}
818 \XOR\KWD{\TLD @P}\XOR\KWD{\TLD:@P}}}
819 {\index{\~P@$\sim$P}%
820 \EM{Plural. }
821 If argument \kwd{eql} \LIT{1} print nothing, otherwise print \LIT{s};
822 do the same for the previous argument; if argument \kwd{eql} \LIT{1}
823 print \LIT{y}, otherwise print \LIT{ies}; do the same for the
824 previous argument, respectively.
827 \IT{\KWD{\TLD} \Op{\VAR{n}\DF{\LIT{1}}} \KWD{\%}}
828 {\index{\~\%@$\sim$\%}%
829 \EM{Newline. }
830 Print \VAR{n} newlines.
833 \IT{\KWD{\TLD} \Op{\VAR{n}\DF{\LIT{1}}} \KWD{\&}}
834 {\index{\~\&@$\sim$\&}%
835 \EM{Fresh-Line. }
836 Print $n-1$ newlines if output stream is at the
837 beginning of a line, or \VAR{n} newlines otherwise.
840 \IT{\Goo{\KWD{\TLD\_}\XOR\KWD{\TLD:\_}\XOR\KWD{\TLD@\_}\XOR\KWD{\TLD:@\_}}}
841 {\index{\~\_{}@$\sim$\_{}}%
842 \EM{Conditional Newline. }
843 Print a newline like \kwd{pprint-newline} with argument
844 \kwd{:linear}, \kwd{:fill}, \kwd{:miser}, or \kwd{:mandatory}, respectively.
847 \IT{\KWD{\TLD} \Op{\KWD{:}} \Op{\KWD{@}} $\hookleftarrow$}
849 \EM{Ignored Newline. } Ignore newline and following
850 whitespace. With \kwd{:}, ignore only newline; with \kwd{@},
851 ignore only following whitespace.
854 \IT{\KWD{\TLD} \Op{\VAR{n}\DF{\LIT{1}}} \KWD{\boldmath$|$}}
855 {\index{\~\textbar@$\sim${$"|$}}%
856 \EM{Page. }
857 Print \VAR{n} page separators.
860 \IT{\KWD{\TLD} \Op{\VAR{n}\DF{\LIT{1}}} \KWD{\TLD}}
861 {\index{\~\~@$\sim$$\sim$}%
862 \EM{Tilde. }
863 Print \VAR{n} tildes.
866 \IT{\KWD{\TLD} \Op{\VAR{min-col}\DF{\LIT{0}}}
867 \OP{\KWD{,}\Op{\VAR{col-inc}\DF{\LIT{1}}}
868 \OP{\KWD{,}\Op{\VAR{min-pad}\DF{\LIT{0}}}
869 \OP{\KWD{,}\VAR{pad-char}\DF{\kwd{'}\textvisiblespace}}}}
870 \KWD{\Op{:} \Op{@} \boldmath{$<$}}
871 \OP{\VAR{nl-text} \KWD{\TLD}\Op{\VAR{spare}\DF{\LIT{0}} \Op{,\VAR{width}}}\kwd{:;}}
872 \Goos{\VAR{text}\KWD{\TLD;}} \VAR{text} \KWD{\TLD\boldmath{$>$}}}
873 {\index{\~<\~>@$\sim$$<$ $\sim$$>$}%
874 \EM{Justification. }
875 Justify text produced by \VAR{text}s in a field of at least
876 \VAR{min-col} columns. With \kwd{:}, right justify; with \kwd{@},
877 left justify. If this would leave less than \VAR{spare} characters
878 on the current line, output \VAR{nl-text} first.
881 \IT{\KWD{\TLD} \Op{\KWD{:}} \Op{\KWD{@}} \KWD{\boldmath{$<$}}
882 \GOo{\Op{\VAR{prefix}\DF{\LIT{""}}
883 \KWD{\TLD;}}\XOR\Op{\VAR{per-line-prefix}
884 \KWD{\TLD@;}}}
885 \VAR{body} \OP{\KWD{\TLD;} \VAR{suffix}\DF{\LIT{""}}}
886 \KWD{\TLD:} \Op{\KWD{@}} \KWD{\boldmath{$>$}}}
887 {\index{\~<\~:>@$\sim$$<$ $\sim$:$>$}%
888 \EM{Logical Block. }
889 Act like \kwd{pprint-logical-block} using \VAR{body} as \FU{format}
890 control string on the elements of the list argument or, with \KWD{@},
891 on the remaining arguments, which are extracted by
892 \kwd{pprint-pop}. With \KWD{:}, \VAR{prefix} and \VAR{suffix}
893 default to \LIT{(} and \LIT{)}. When closed by
894 \KWD{\TLD:@\boldmath{$>$}}, spaces in \VAR{body} are replaced with
895 conditional newlines.
898 \IT{\Goo{\KWD{\TLD} \Op{\VAR{n}\DF{\LIT{0}}}
899 \kwd{I}\XOR\KWD{\TLD} \Op{\VAR{n}\DF{\LIT{0}}} \kwd{:I}}}
900 {\index{\~I@$\sim$I}%
901 \EM{Indent. }
902 Set indentation to \VAR{n} relative to leftmost/to current
903 position.
906 \IT{\KWD{\TLD} \Op{\VAR{c}\DF{\LIT{1}}}
907 \Op{\KWD{,}\VAR{i}\DF{\LIT{1}}} \Op{\KWD{:}} \Op{\KWD{@}} \KWD{T}}
908 {\index{\~T@$\sim$T}%
909 \EM{Tabulate. }
910 Move cursor forward to column number $c + ki$, $k \geq 0$ being as small
911 as possible. With \kwd{:}, calculate column numbers relative to
912 the immediately enclosing section. With \kwd{@}, move to column
913 number $c_0 + c + ki$ where $c_0$ is the current position.
916 \IT{\Goo{%
917 \KWD{\TLD} \Op{\VAR{m}\DF{\LIT{1}}} \KWD{\A}\XOR
918 \KWD{\TLD} \Op{\VAR{m}\DF{\LIT{1}}} \KWD{:}\KWD{\A}\XOR
919 \KWD{\TLD} \Op{\VAR{n}\DF{\LIT{0}}} \KWD{@}\KWD{\A}}}
920 {\index{\~*@$\sim$\A}%
921 \EM{Go-To. }
922 Jump \VAR{m} arguments forward, or backward, or to argument \VAR{n}.
925 \IT{\KWD{\TLD} \Op{\VAR{limit}} \Op{\KWD{{:}}} \Op{\kwd{@}}
926 \KWD{\boldmath{$\{$}} \VAR{text} \KWD{\TLD\boldmath{$\}$}}}
927 {\index{\~\{\~\}@$\sim$$\{$ $\sim\}$}%
928 \EM{Iteration. }
929 \VAR{text} is used repeatedly, up to \VAR{limit}, as control
930 string for the elements of the list argument or (with
931 \kwd{@}) for the remaining arguments. With \kwd{:} or \kwd{:@},
932 list elements or remaining arguments should be
933 lists of which a new one is used at each iteration step.
936 \IT{\KWD{\TLD} \OP{\VAR{x} \OP{\kwd{,} \VAR{y} \Op{\kwd{,} \VAR{z}}}}
937 \KWD{\^{}}}
938 {\index{\~\^{}@$\sim$\^{}}%
939 \EM{Escape Upward. }
940 Leave immediately \kwd{\TLD\boldmath{$<$} \TLD\boldmath{$>$}},
941 \kwd{\TLD\boldmath{$<$} \TLD:\boldmath{$>$}},
942 \kwd{\TLD\boldmath{$\{$} \TLD\boldmath{$\}$}}, \kwd{\TLD?}, or the
943 entire \FU{format} operation. With one to three prefixes, act only
944 if $x=0$, $x=y$, or $x\leq y \leq z$, respectively.
947 \IT{\KWD{\TLD} \Op{\VAR{i}} \Op{\KWD{:}} \Op{\KWD{@}}
948 \KWD{[} \Op{\Goos{\VAR{text} \KWD{\TLD;}} \VAR{text}}
949 \Op{\kwd{\TLD:;} \VAR{default}} \KWD{\TLD]}}
950 {\index{\~[\~]@$\sim$[ $\sim$]}%
951 \EM{Conditional Expression. }
952 The \VAR{text}s are format control subclauses the zero-indexed argumenth (or the
953 \VAR{i}th if given) of which is chosen. With \kwd{:}, the argument
954 is boolean and takes first \VAR{text} for \NIL\ and second
955 \VAR{text} for \T. With \kwd{@}, the argument is boolean and if \T, takes
956 the only \VAR{text} and remains to be read; no \VAR{text} is
957 chosen and the argument is used up if it is \NIL.
960 \IT{\KWD{\TLD} \Op{\KWD{@}} \KWD{?}}
961 {\index{\~?@$\sim$?}%
962 \EM{Recursive Processing. }
963 Process two arguments as \FU{format} string and argument list. With
964 \kwd{@}, take one argument as \FU{format} string and use then the
965 rest of the original arguments.
968 \IT{\KWD{\TLD} \OP{\VAR{prefix}\Goos{\kwd{,}
969 \VAR{prefix}}} \Op{\kwd{:}} \Op{\kwd{@}} \KWD{/}\VAR{function}\KWD{/}}
970 {\index{\~/ /@$\sim$/ /}%
971 \EM{Call Function. }
972 Call \VAR{function} with the arguments stream, format-ar\-gu\-ment,
973 colon-p, at-sign-p and \VAR{prefix}es for printing format-argument.
976 \IT{\KWD{\TLD} \Op{\KWD{:}} \Op{\KWD{@}} \KWD{W}}
977 {\index{\~W@$\sim$W}%
978 \EM{Write. }
979 Print argument of any type obeying every printer control variable. With \kwd{:},
980 pretty-print. With \kwd{@}, print without limits on length or depth.
983 \IT{\Goo{\KWD{V}\XOR\KWD{\#}}}
984 {\index{V}\index{\#}
985 In place of the comma-separated prefix parameters: use next
986 argument or number of remaining unprocessed arguments, respectively.
989 \end{LIST}
991 \end{LIST}
994 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
995 \subsection{Streams}
996 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
998 \begin{LIST}{1cm}
1000 \IT{(\FU*{OPEN} \VAR{path}
1001 \orGOO{\kwd{:direction} \xorGOO{\kwd{:input}\\
1002 \kwd{:output}\\
1003 \kwd{:io}\\
1004 \kwd{:probe}}{\}}\DF{\kwd{:input}}\\
1005 \kwd{:element-type} \VAR{ type}\DF{\kwd{character}}\\
1006 \kwd{:if-exists}
1007 \xorGOO{\kwd{:new-version}\\
1008 \kwd{:error}\\
1009 \kwd{:rename}\\
1010 \kwd{:rename-and-delete}\\
1011 \kwd{:overwrite}\\
1012 \kwd{:append}\\
1013 \kwd{:supersede}\\
1014 \NIL}{.}\\
1015 \kwd{:if-does-not exist} \xorGOO{\kwd{:error}\\
1016 \kwd{:create}\\
1017 \NIL}{.}\\
1018 \kwd{:external-format } \VAR{format}\DF{\kwd{:default}}%
1019 }{\}})}
1020 {\label{open}
1021 Open \retval{\kwd{file-stream} to \VAR{path}}.
1024 \IT{\arrGOO{%
1025 (\FU*{MAKE-CONCATENATED-STREAM } \OPn{\VAR{input-stream}})\\
1026 (\FU*{MAKE-BROADCAST-STREAM } \OPn{\VAR{output-stream}})\\
1027 (\FU*{MAKE-TWO-WAY-STREAM } \VAR{input-stream-part } \VAR{output-stream-part})\\
1028 (\FU*{MAKE-ECHO-STREAM } \VAR{from-input-stream } \VAR{to-output-stream})\\
1029 (\FU*{MAKE-SYNONYM-STREAM } \VAR{variable-bound-to-stream})}{.}}
1031 Return \retval{stream} of indicated type.
1034 \IT{(\FU*{MAKE-STRING-INPUT-STREAM} \VAR{string}
1035 \OP{\VAR{start}\DF{\LIT{0}}
1036 \Op{\VAR{end}\DF{\NIL}}})}
1038 Return a \retval{\kwd{string-stream}} supplying the characters from \VAR{string}.
1041 \IT{(\FU*{MAKE-STRING-OUTPUT-STREAM} \Op{\kwd{:element-type}
1042 \VAR{type}\DF{\kwd{character}}})}
1044 Return a \retval{\kwd{string-stream}} accepting characters
1045 (available via \FU{get-output-stream-string}).
1048 \IT{\arrGOO{(\FU*{CONCATENATED-STREAM-STREAMS } \VAR{concatenated-stream})\\
1049 (\FU*{BROADCAST-STREAM-STREAMS } \VAR{broadcast-stream})}{.}}
1051 Return \retval{list of streams} \VAR{concatenated-stream} still
1052 has to read from/\VAR{broadcast-stream} is
1053 broadcasting to.
1056 \IT{\arrGOO{%
1057 (\FU*{TWO-WAY-STREAM-INPUT-STREAM} \VAR{ two-way-stream})\\
1058 (\FU*{TWO-WAY-STREAM-OUTPUT-STREAM} \VAR{ two-way-stream})\\
1059 (\FU*{ECHO-STREAM-INPUT-STREAM} \VAR{ echo-stream})\\
1060 (\FU*{ECHO-STREAM-OUTPUT-STREAM} \VAR{ echo-stream})}{.}}
1062 Return \retval{source stream} or \retval{sink stream} of
1063 \VAR{two-way-stream}\slash\VAR{echo-stream}, respectively.
1066 \IT{(\FU*{SYNONYM-STREAM-SYMBOL} \VAR{synonym-stream})}
1068 Return \retval{symbol} of \VAR{synonym-stream}.
1071 \IT{(\FU*{GET-OUTPUT-STREAM-STRING} \DES{\VAR{string-stream}})}
1073 Clear and return as a \retval{string} characters on \VAR{string-stream}.
1076 \IT{(\FU*{LISTEN} \Op{\VAR{stream}\DF{\V{\A standard-input\A}}})}
1078 \retval{\T} if there is a character in input \VAR{stream}.
1081 \IT{(\FU*{CLEAR-INPUT}
1082 \Op{\DES{\VAR{stream}}\DF{\V{\A standard-input\A}}})}
1084 Clear input from \VAR{stream}, return \retval{\NIL}.
1087 \IT{(\xorGOO{\FU*{CLEAR-OUTPUT}\\
1088 \FU*{FORCE-OUTPUT}\\
1089 \FU*{FINISH-OUTPUT}}{\}}
1090 \Op{\DES{\VAR{stream}}\DF{\V{\A standard-output\A}}})}
1092 End output to \VAR{stream} and return \retval{\NIL} immediately,
1093 after initiating flushing of buffers, or after flushing of buffers,
1094 respectively.
1097 \IT{(\FU*{CLOSE} \DES{\VAR{stream}} \Op{\kwd{:abort}
1098 \VAR{bool}\DF{\NIL}})}
1100 Close \VAR{stream}. Return \retval{\T} if \VAR{stream} had been
1101 open. If \kwd{:abort} is \T, delete associated file.
1104 \IT{(\MC*{WITH-OPEN-STREAM} (\VAR{foo} \DES{\VAR{stream}})
1105 \OPn{(\kwd{declare} \OPn{\NEV{\VAR{decl}}})} \PROGN{\VAR{form}})}
1107 Evaluate \VAR{form}s with \VAR{foo} locally bound to
1108 \VAR{stream}. Return \retval{values of \VAR{form}s}.
1111 \IT{(\MC*{WITH-INPUT-FROM-STRING} (\VAR{foo} \VAR{string}
1112 \orGOO{\kwd{:index } \DES{\VAR{index}}\\
1113 \kwd{:start} \VAR{ start}\DF{\LIT{0}}\\
1114 \kwd{:end} \VAR{ end}\DF{\NIL}}{\}}) \OPn{(\kwd{declare}
1115 \OPn{\NEV{\VAR{decl}}})} \PROGN{\VAR{form}})}
1117 Evaluate \VAR{form}s with \VAR{foo} locally bound to input \kwd{string-stream}
1118 from \VAR{string}. Return \retval{values of \VAR{form}s}; store next
1119 reading position into \VAR{index}.
1122 \IT{(\MC*{WITH-OUTPUT-TO-STRING} (\VAR{foo}
1123 \Op{\DES{\VAR{string}}\DF{\NIL}} \Op{\kwd{:element-type}
1124 \VAR{type}\DF{\kwd{character}}}) \OPn{(\kwd{declare}
1125 \OPn{\NEV{\VAR{decl}}})} \PROGN{\VAR{form}})}
1127 Evaluate \VAR{form}s with \VAR{foo} locally bound to an output
1128 \kwd{string-stream}. Append output to \VAR{string} and return
1129 \retval{values of \VAR{form}s} if \VAR{string} is given. Return
1130 \retval{string containing output} otherwise.
1133 \IT{(\FU*{STREAM-EXTERNAL-FORMAT} \VAR{stream})}
1135 \retval{External file format designator}.
1138 \IT{\V{\A terminal-io\A}}
1139 {\index{*TERMINAL-IO*@\A TERMINAL-IO\A}
1140 Bidirectional stream to user terminal.
1143 \IT{\arrGOO{\V{\A standard-input\A}\\
1144 \V{\A standard-output\A}\\
1145 \V{\A error-output\A}}{.}}
1146 {\index{*STANDARD-INPUT*@\A STANDARD-INPUT\A}%
1147 \index{*STANDARD-OUTPUT*@\A STANDARD-OUTPUT\A}%
1148 \index{*ERROR-OUTPUT*@\A ERROR-OUTPUT\A}
1149 Standard input stream, standard output stream,
1150 or standard error output stream, respectively.
1153 \IT{\arrGOO{\V{\A debug-io\A}\\
1154 \V{\A query-io\A}}{.}}
1155 {\index{*DEBUG-IO*@\A DEBUG-IO\A}\index{*QUERY-IO*@\A QUERY-IO\A}
1156 Bidirectional streams for debugging and user interaction.
1159 \end{LIST}
1162 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1163 \subsection{Files}
1164 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1166 \begin{LIST}{1cm}
1168 \IT{(\FU*{MAKE-PATHNAME}
1169 \orGOO{\kwd{:host} \VAR{ host}\\
1170 \kwd{:device} \VAR{ dev}\\
1171 \kwd{:directory} \VAR{ dir}\\
1172 \kwd{:name} \VAR{ file-name}\\
1173 \kwd{:type} \VAR{ file-type}\\
1174 \kwd{:version} \VAR{ ver}\\
1175 \kwd{:defaults} \VAR{ path}\\
1176 \kwd{:case
1177 \Goo{\kwd{:local}\XOR\kwd{:common}}\DF{\kwd{:local}}}}{\}})}
1179 Construct \retval{pathname}.
1182 \IT{(\FU*{MERGE-PATHNAMES} \VAR{pathname}
1183 \OP{\VAR{default-pathname}\DF{\V{\A default-pathname-defaults\A}}
1184 \Op{\VAR{default-version}\DF{\kwd{:newest}}}})}
1186 Return \retval{\VAR{pathname}} after filling in missing parts from defaults.
1189 \IT{\V{\A default-pathname-defaults\A}}
1190 {\index{*DEFAULT-PATHNAME-DEFAULTS*@\A DEFAULT-PATHNAME-DEFAULTS\A}
1191 Pathname to use if one is needed and none supplied.
1194 \IT{(\FU*{PATHNAME} \VAR{path})}
1196 \retval{Pathname} of \VAR{path}.
1199 \IT{(\FU*{ENOUGH-NAMESTRING} \VAR{path}
1200 \Op{\VAR{root-path}\DF{\V{\A default-pathname-defaults\A}}})}
1202 Return \retval{minimal path string} to sufficiently describe
1203 \VAR{path} relative to \VAR{root-path.}
1206 \IT{\arrGOO{(\FU*{NAMESTRING}\VAR{ path})\\
1207 (\FU*{FILE-NAMESTRING}\VAR{ path})\\
1208 (\FU*{DIRECTORY-NAMESTRING}\VAR{ path})\\
1209 (\FU*{HOST-NAMESTRING}\VAR{ path})}{.}}
1211 Return string representing \retval{full pathname}; \retval{name,
1212 type, and version}; \retval{directory name}; or \retval{host
1213 name}, respectively, of \VAR{path}.
1216 \IT{(\FU*{PARSE-NAMESTRING} \VAR{foo}
1217 \OP{\VAR{host}
1218 \OP{\VAR{default-pathname}\DF{\V{\A default-pathname-defaults\A}}
1219 \orGOO{\kwd{:start} \VAR{ start}\DF{\LIT{0}}\\
1220 \kwd{:end} \VAR{ end}\DF{\NIL}\\
1221 \kwd{:junk-allowed} \VAR{ bool}\DF{\NIL}}{\}}}})}
1223 Return \retval{pathname} converted from
1224 string, pathname, or stream \VAR{foo}; and \retvalii{position}
1225 where parsing stopped.
1228 \IT{\arrGOO{%
1229 (\xorGOO{\FU*{PATHNAME-HOST}\\
1230 \FU*{PATHNAME-DEVICE}\\
1231 \FU*{PATHNAME-DIRECTORY}\\
1232 \FU*{PATHNAME-NAME}\\
1233 \FU*{PATHNAME-TYPE}}{\}}
1234 \VAR{ path }
1235 \Op{\kwd{:case } \xorGOO{\kwd{:local}\\
1236 \kwd{:common}}{\}}\DF{\kwd{:local}}})\\
1237 (\FU*{PATHNAME-VERSION } \VAR{path})}{.}}
1239 Return \retval{pathname component}.
1242 \IT{(\FU*{LOGICAL-PATHNAME} \VAR{path})}
1244 \retval{Logical name} of \VAR{path}.
1247 \IT{(\FU*{TRANSLATE-PATHNAME} \VAR{path-a} \VAR{path-b}
1248 \VAR{path-c})}
1250 Translate \VAR{path-a} from wildcard \VAR{path-b} into wildcard
1251 \VAR{path-c}. Return \retval{new path}.
1254 \IT{(\FU*{LOGICAL-PATHNAME-TRANSLATIONS} \VAR{host})}
1256 \retval{\VAR{host}'s list of translations}. \kwd{setf}able.
1259 \IT{(\FU*{LOAD-LOGICAL-PATHNAME-TRANSLATIONS} \VAR{host})}
1261 Load \VAR{host}'s translations. Return \retval{\NIL} if already
1262 loaded, return \retval{\T} if successful.
1265 \IT{(\FU*{TRANSLATE-LOGICAL-PATHNAME} \VAR{path})}
1267 Physical \retval{pathname} of \VAR{path}.
1270 \IT{\arrGOO{(\FU*{PROBE-FILE} \VAR{ file})\\
1271 (\FU*{TRUENAME} \VAR{ file})}{.}}
1273 \retval{Canonical name} of \VAR{file}. If \VAR{file} does not exist,
1274 return \retval{\NIL}/signal \kwd{file-error}, respectively.
1277 \IT{(\FU*{FILE-WRITE-DATE} \VAR{file})}
1279 \retval{Time} at which \VAR{file} was last written.
1282 \IT{(\FU*{FILE-AUTHOR} \VAR{file})\qquad\qquad}
1284 Return \retval{name of \VAR{file} owner}.
1287 \IT{(\FU*{FILE-LENGTH} \VAR{stream})}
1289 Return \retval{length of \VAR{stream}}.
1292 \IT{(\FU*{FILE-POSITION} \VAR{stream} \Op{\xorGOO{\kwd{:start}\\
1293 \kwd{:end}\\
1294 \VAR{position}}{\}}})}
1296 Return \retval{position within stream}, or set it to
1297 \retval{\VAR{position}} and return \retval{\T} on success.
1300 \IT{(\FU*{FILE-STRING-LENGTH} \VAR{stream} \VAR{foo})}
1302 \retval{Length} \VAR{foo} would have in \VAR{stream}.
1305 \IT{(\FU*{RENAME-FILE} \VAR{foo} \VAR{bar})}
1307 Rename file \VAR{foo} to \VAR{bar}. Unspecified parts of path
1308 \VAR{bar} default to those of \VAR{foo}. Return \retval{new
1309 pathname}, \retvalii{old file name}, and \retvaliii{new file name}.
1312 \IT{(\FU*{DELETE-FILE} \VAR{file})}
1314 Delete \VAR{file}, return \retval{\T}.
1317 \IT{(\FU*{DIRECTORY} \VAR{path})}
1319 Return \retval{list of pathnames}.
1322 \IT{(\FU*{ENSURE-DIRECTORIES-EXIST} \VAR{path} \Op{\kwd{:verbose}
1323 \VAR{bool}})}
1325 Create parts of \retval{\VAR{path}} if necessary. Second return value is
1326 \retvalii{\T} if something has been created.
1329 \IT{(\MC*{WITH-OPEN-FILE} (\VAR{stream} \VAR{path}
1330 \OPn{\VAR{open-arg}}) \OPn{(\kwd{declare} \OPn{\NEV{\VAR{decl}}})}
1331 \PROGN{\VAR{form}})}
1333 Use \FU{OPEN} with \VAR{open-arg}s (cf.\ page \pageref{open}) to temporarily
1334 create \VAR{stream} to \VAR{path}; return \retval{values of \VAR{form}s}.
1337 \IT{(\FU*{USER-HOMEDIR-PATHNAME} \Op{\VAR{host}})}
1339 User's \retval{home directory}.
1343 \end{LIST}
1347 % LocalWords: ies argumenth ar gu ment
1349 %%% Local Variables:
1350 %%% mode: latex
1351 %%% TeX-master: "clqr"
1352 %%% End: