Commit | Line | Data |
---|---|---|
2da09c3f MV |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
be96155b LC |
3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2009, |
4 | @c 2010, 2011, 2012 Free Software Foundation, Inc. | |
2da09c3f MV |
5 | @c See the file guile.texi for copying conditions. |
6 | ||
a0e07ba4 | 7 | @node Pretty Printing |
3229f68b | 8 | @section Pretty Printing |
a0e07ba4 NJ |
9 | |
10 | @c FIXME::martin: Review me! | |
11 | ||
12 | @cindex pretty printing | |
13 | The module @code{(ice-9 pretty-print)} provides the procedure | |
14 | @code{pretty-print}, which provides nicely formatted output of Scheme | |
15 | objects. This is especially useful for deeply nested or complex data | |
16 | structures, such as lists and vectors. | |
17 | ||
b8596c08 | 18 | The module is loaded by entering the following: |
a0e07ba4 NJ |
19 | |
20 | @lisp | |
21 | (use-modules (ice-9 pretty-print)) | |
22 | @end lisp | |
23 | ||
24 | This makes the procedure @code{pretty-print} available. As an example | |
25 | how @code{pretty-print} will format the output, see the following: | |
26 | ||
27 | @lisp | |
28 | (pretty-print '(define (foo) (lambda (x) | |
385dbc8b KR |
29 | (cond ((zero? x) #t) ((negative? x) -x) (else |
30 | (if (= x 1) 2 (* x x x))))))) | |
a0e07ba4 NJ |
31 | @print{} |
32 | (define (foo) | |
33 | (lambda (x) | |
34 | (cond ((zero? x) #t) | |
35 | ((negative? x) -x) | |
36 | (else (if (= x 1) 2 (* x x x)))))) | |
37 | @end lisp | |
38 | ||
385dbc8b | 39 | @deffn {Scheme Procedure} pretty-print obj [port] [keyword-options] |
a0e07ba4 NJ |
40 | Print the textual representation of the Scheme object @var{obj} to |
41 | @var{port}. @var{port} defaults to the current output port, if not | |
42 | given. | |
385dbc8b KR |
43 | |
44 | The further @var{keyword-options} are keywords and parameters as | |
45 | follows, | |
46 | ||
47 | @table @asis | |
48 | @item @nicode{#:display?} @var{flag} | |
49 | If @var{flag} is true then print using @code{display}. The default is | |
50 | @code{#f} which means use @code{write} style. (@pxref{Writing}) | |
51 | ||
52 | @item @nicode{#:per-line-prefix} @var{string} | |
53 | Print the given @var{string} as a prefix on each line. The default is | |
54 | no prefix. | |
55 | ||
56 | @item @nicode{#:width} @var{columns} | |
57 | Print within the given @var{columns}. The default is 79. | |
58 | @end table | |
a0e07ba4 NJ |
59 | @end deffn |
60 | ||
2a946b44 | 61 | |
b8596c08 AW |
62 | @cindex truncated printing |
63 | Also exported by the @code{(ice-9 pretty-print)} module is | |
64 | @code{truncated-print}, a procedure to print Scheme datums, truncating | |
65 | the output to a certain number of characters. This is useful when you | |
66 | need to present an arbitrary datum to the user, but you only have one | |
67 | line in which to do so. | |
68 | ||
69 | @lisp | |
70 | (define exp '(a b #(c d e) f . g)) | |
71 | (truncated-print exp #:width 10) (newline) | |
72 | @print{} (a b . #) | |
73 | (truncated-print exp #:width 15) (newline) | |
74 | @print{} (a b # f . g) | |
75 | (truncated-print exp #:width 18) (newline) | |
76 | @print{} (a b #(c ...) . #) | |
77 | (truncated-print exp #:width 20) (newline) | |
78 | @print{} (a b #(c d e) f . g) | |
87a6a236 | 79 | (truncated-print "The quick brown fox" #:width 20) (newline) |
b8596c08 AW |
80 | @print{} "The quick brown..." |
81 | (truncated-print (current-module) #:width 20) (newline) | |
82 | @print{} #<directory (gui...> | |
83 | @end lisp | |
84 | ||
c5e05a1c LC |
85 | @code{truncated-print} will not output a trailing newline. If an expression does |
86 | not fit in the given width, it will be truncated -- possibly | |
87 | ellipsized@footnote{On Unicode-capable ports, the ellipsis is represented by | |
88 | character `HORIZONTAL ELLIPSIS' (U+2026), otherwise it is represented by three | |
89 | dots.}, or in the worst case, displayed as @nicode{#}. | |
b8596c08 AW |
90 | |
91 | @deffn {Scheme Procedure} truncated-print obj [port] [keyword-options] | |
92 | Print @var{obj}, truncating the output, if necessary, to make it fit | |
64de6db5 | 93 | into @var{width} characters. By default, @var{obj} will be printed using |
ecb87335 | 94 | @code{write}, though that behavior can be overridden via the |
b8596c08 AW |
95 | @var{display?} keyword argument. |
96 | ||
97 | The default behaviour is to print depth-first, meaning that the entire | |
64de6db5 BT |
98 | remaining width will be available to each sub-expression of @var{obj} -- |
99 | e.g., if @var{obj} is a vector, each member of @var{obj}. One can attempt to | |
b8596c08 AW |
100 | ``ration'' the available width, trying to allocate it equally to each |
101 | sub-expression, via the @var{breadth-first?} keyword argument. | |
102 | ||
103 | The further @var{keyword-options} are keywords and parameters as | |
104 | follows, | |
105 | ||
106 | @table @asis | |
107 | @item @nicode{#:display?} @var{flag} | |
108 | If @var{flag} is true then print using @code{display}. The default is | |
109 | @code{#f} which means use @code{write} style. (@pxref{Writing}) | |
110 | ||
111 | @item @nicode{#:width} @var{columns} | |
112 | Print within the given @var{columns}. The default is 79. | |
113 | ||
114 | @item @nicode{#:breadth-first?} @var{flag} | |
115 | If @var{flag} is true, then allocate the available width breadth-first | |
116 | among elements of a compound data structure (list, vector, pair, | |
117 | etc.). The default is @code{#f} which means that any element is | |
118 | allowed to consume all of the available width. | |
119 | @end table | |
120 | @end deffn | |
121 | ||
122 | ||
a0e07ba4 | 123 | @node Formatted Output |
3229f68b | 124 | @section Formatted Output |
a0e07ba4 | 125 | @cindex formatted output |
a0e07ba4 | 126 | |
76d3f3d4 KR |
127 | @c For reference, in this section escapes like ~a are given in |
128 | @c @nicode, to give code font in TeX etc, but leave them unadorned in | |
129 | @c Info. | |
130 | @c | |
131 | @c The idea is to reduce clutter around what's shown, and avoid any | |
132 | @c possible confusion over whether the ` ' quotes are part of what | |
133 | @c should be entered. (In particular for instance of course ' is | |
134 | @c meaningful in a format string, introducing a char parameter). | |
135 | ||
136 | The @code{format} function is a powerful way to print numbers, strings | |
137 | and other objects together with literal text under the control of a | |
138 | format string. This function is available from | |
139 | ||
140 | @example | |
141 | (use-modules (ice-9 format)) | |
142 | @end example | |
143 | ||
144 | A format string is generally more compact and easier than using just | |
145 | the standard procedures like @code{display}, @code{write} and | |
146 | @code{newline}. Parameters in the output string allow various output | |
147 | styles, and parameters can be taken from the arguments for runtime | |
148 | flexibility. | |
149 | ||
150 | @code{format} is similar to the Common Lisp procedure of the same | |
151 | name, but it's not identical and doesn't have quite all the features | |
152 | found in Common Lisp. | |
153 | ||
154 | C programmers will note the similarity between @code{format} and | |
155 | @code{printf}, though escape sequences are marked with @nicode{~} | |
156 | instead of @nicode{%}, and are more powerful. | |
157 | ||
158 | @sp 1 | |
df0a1002 | 159 | @deffn {Scheme Procedure} format dest fmt arg @dots{} |
76d3f3d4 KR |
160 | Write output specified by the @var{fmt} string to @var{dest}. |
161 | @var{dest} can be an output port, @code{#t} for | |
c89920a7 AW |
162 | @code{current-output-port} (@pxref{Default Ports}), or @code{#f} to |
163 | return the output as a string. | |
76d3f3d4 KR |
164 | |
165 | @var{fmt} can contain literal text to be output, and @nicode{~} | |
166 | escapes. Each escape has the form | |
167 | ||
168 | @example | |
169 | ~ [param [, param@dots{}] [:] [@@] code | |
170 | @end example | |
171 | ||
172 | @nicode{code} is a character determining the escape sequence. The | |
173 | @nicode{:} and @nicode{@@} characters are optional modifiers, one or | |
174 | both of which change the way various codes operate. Optional | |
175 | parameters are accepted by some codes too. Parameters have the | |
176 | following forms, | |
a0e07ba4 | 177 | |
76d3f3d4 | 178 | @table @asis |
80a894c9 | 179 | @item @nicode{[+/-]number} |
76d3f3d4 KR |
180 | An integer, with optional @nicode{+} or @nicode{-}. |
181 | @item @nicode{'} (apostrophe) | |
182 | The following character in the format string, for instance @nicode{'z} | |
183 | for @nicode{z}. | |
184 | @item @nicode{v} | |
185 | The next function argument as the parameter. @nicode{v} stands for | |
186 | ``variable'', a parameter can be calculated at runtime and included in | |
187 | the arguments. Upper case @nicode{V} can be used too. | |
188 | @item @nicode{#} | |
189 | The number of arguments remaining. (See @nicode{~*} below for some | |
190 | usages.) | |
a0e07ba4 NJ |
191 | @end table |
192 | ||
76d3f3d4 KR |
193 | Parameters are separated by commas (@nicode{,}). A parameter can be |
194 | left empty to keep its default value when supplying later parameters. | |
a0e07ba4 | 195 | |
76d3f3d4 KR |
196 | @sp 1 |
197 | The following escapes are available. The code letters are not | |
198 | case-sensitive, upper and lower case are the same. | |
a0e07ba4 | 199 | |
76d3f3d4 KR |
200 | @table @asis |
201 | @item @nicode{~a} | |
202 | @itemx @nicode{~s} | |
203 | Object output. Parameters: @var{minwidth}, @var{padinc}, | |
204 | @var{minpad}, @var{padchar}. | |
205 | ||
206 | @nicode{~a} outputs an argument like @code{display}, @nicode{~s} | |
207 | outputs an argument like @code{write} (@pxref{Writing}). | |
208 | ||
209 | @example | |
210 | (format #t "~a" "foo") @print{} foo | |
211 | (format #t "~s" "foo") @print{} "foo" | |
212 | @end example | |
213 | ||
80a894c9 KR |
214 | @nicode{~:a} and @nicode{~:s} put objects that don't have an external |
215 | representation in quotes like a string. | |
76d3f3d4 KR |
216 | |
217 | @example | |
218 | (format #t "~:a" car) @print{} "#<primitive-procedure car>" | |
219 | @end example | |
220 | ||
221 | If the output is less than @var{minwidth} characters (default 0), it's | |
80a894c9 KR |
222 | padded on the right with @var{padchar} (default space). @nicode{~@@a} |
223 | and @nicode{~@@s} put the padding on the left instead. | |
76d3f3d4 KR |
224 | |
225 | @example | |
226 | (format #f "~5a" 'abc) @result{} "abc " | |
227 | (format #f "~5,,,'-@@a" 'abc) @result{} "--abc" | |
228 | @end example | |
229 | ||
230 | @var{minpad} is a minimum for the padding then plus a multiple of | |
231 | @var{padinc}. Ie.@: the padding is @math{@var{minpad} + @var{N} * | |
232 | @var{padinc}}, where @var{n} is the smallest integer making the total | |
233 | object plus padding greater than or equal to @var{minwidth}. The | |
234 | default @var{minpad} is 0 and the default @var{padinc} is 1 (imposing | |
235 | no minimum or multiple). | |
236 | ||
237 | @example | |
238 | (format #f "~5,1,4a" 'abc) @result{} "abc " | |
239 | @end example | |
240 | ||
241 | @item @nicode{~c} | |
242 | Character. Parameter: @var{charnum}. | |
243 | ||
244 | Output a character. The default is to simply output, as per | |
80a894c9 KR |
245 | @code{write-char} (@pxref{Writing}). @nicode{~@@c} prints in |
246 | @code{write} style. @nicode{~:c} prints control characters (ASCII 0 | |
247 | to 31) in @nicode{^X} form. | |
76d3f3d4 KR |
248 | |
249 | @example | |
250 | (format #t "~c" #\z) @print{} z | |
251 | (format #t "~@@c" #\z) @print{} #\z | |
252 | (format #t "~:c" #\newline) @print{} ^J | |
253 | @end example | |
254 | ||
255 | If the @var{charnum} parameter is given then an argument is not taken | |
256 | but instead the character is @code{(integer->char @var{charnum})} | |
257 | (@pxref{Characters}). This can be used for instance to output | |
258 | characters given by their ASCII code. | |
259 | ||
260 | @example | |
261 | (format #t "~65c") @print{} A | |
262 | @end example | |
263 | ||
264 | @item @nicode{~d} | |
265 | @itemx @nicode{~x} | |
266 | @itemx @nicode{~o} | |
267 | @itemx @nicode{~b} | |
268 | Integer. Parameters: @var{minwidth}, @var{padchar}, @var{commachar}, | |
269 | @var{commawidth}. | |
270 | ||
271 | Output an integer argument as a decimal, hexadecimal, octal or binary | |
afd08fdf | 272 | integer (respectively), in a locale-independent way. |
76d3f3d4 KR |
273 | |
274 | @example | |
275 | (format #t "~d" 123) @print{} 123 | |
276 | @end example | |
277 | ||
80a894c9 | 278 | @nicode{~@@d} etc shows a @nicode{+} sign is shown on positive |
76d3f3d4 KR |
279 | numbers. |
280 | ||
281 | @c FIXME: "+" is not shown on zero, unlike in Common Lisp. Should | |
282 | @c that be changed in the code, or is it too late and should just be | |
283 | @c documented that way? | |
284 | ||
285 | @example | |
286 | (format #t "~@@b" 12) @print{} +1100 | |
287 | @end example | |
288 | ||
289 | If the output is less than the @var{minwidth} parameter (default no | |
290 | minimum), it's padded on the left with the @var{padchar} parameter | |
291 | (default space). | |
292 | ||
293 | @example | |
294 | (format #t "~5,'*d" 12) @print{} ***12 | |
295 | (format #t "~5,'0d" 12) @print{} 00012 | |
296 | (format #t "~3d" 1234) @print{} 1234 | |
297 | @end example | |
298 | ||
80a894c9 | 299 | @nicode{~:d} adds commas (or the @var{commachar} parameter) every |
afd08fdf LC |
300 | three digits (or the @var{commawidth} parameter many). However, when |
301 | your intent is to write numbers in a way that follows typographical | |
302 | conventions, using @nicode{~h} is recommended. | |
76d3f3d4 KR |
303 | |
304 | @example | |
305 | (format #t "~:d" 1234567) @print{} 1,234,567 | |
306 | (format #t "~10,'*,'/,2:d" 12345) @print{} ***1/23/45 | |
307 | @end example | |
308 | ||
309 | Hexadecimal @nicode{~x} output is in lower case, but the @nicode{~(} | |
310 | and @nicode{~)} case conversion directives described below can be used | |
311 | to get upper case. | |
312 | ||
313 | @example | |
314 | (format #t "~x" 65261) @print{} feed | |
315 | (format #t "~:@@(~x~)" 65261) @print{} FEED | |
316 | @end example | |
317 | ||
318 | @item @nicode{~r} | |
319 | Integer in words, roman numerals, or a specified radix. Parameters: | |
320 | @var{radix}, @var{minwidth}, @var{padchar}, @var{commachar}, | |
321 | @var{commawidth}. | |
322 | ||
323 | With no parameters output is in words as a cardinal like ``ten'', or | |
80a894c9 | 324 | @nicode{~:r} prints an ordinal like ``tenth''. |
76d3f3d4 KR |
325 | |
326 | @example | |
327 | (format #t "~r" 9) @print{} nine ;; cardinal | |
328 | (format #t "~r" -9) @print{} minus nine ;; cardinal | |
329 | (format #t "~:r" 9) @print{} ninth ;; ordinal | |
330 | @end example | |
331 | ||
80a894c9 | 332 | And also with no parameters, @nicode{~@@r} gives roman numerals and |
40296bab | 333 | @nicode{~:@@r} gives old roman numerals. In old roman numerals |
80a894c9 KR |
334 | there's no ``subtraction'', so 9 is @nicode{VIIII} instead of |
335 | @nicode{IX}. In both cases only positive numbers can be output. | |
76d3f3d4 KR |
336 | |
337 | @example | |
338 | (format #t "~@@r" 89) @print{} LXXXIX ;; roman | |
40296bab | 339 | (format #t "~:@@r" 89) @print{} LXXXVIIII ;; old roman |
76d3f3d4 KR |
340 | @end example |
341 | ||
342 | When a parameter is given it means numeric output in the specified | |
343 | @var{radix}. The modifiers and parameters following the radix are the | |
344 | same as described for @nicode{~d} etc above. | |
345 | ||
346 | @example | |
347 | (format #f "~3r" 27) @result{} "1000" ;; base 3 | |
348 | (format #f "~3,5r" 26) @result{} " 222" ;; base 3 width 5 | |
349 | @end example | |
350 | ||
351 | @item @nicode{~f} | |
352 | Fixed-point float. Parameters: @var{width}, @var{decimals}, | |
353 | @var{scale}, @var{overflowchar}, @var{padchar}. | |
354 | ||
355 | Output a number or number string in fixed-point format, ie.@: with a | |
356 | decimal point. | |
357 | ||
358 | @example | |
359 | (format #t "~f" 5) @print{} 5.0 | |
360 | (format #t "~f" "123") @print{} 123.0 | |
361 | (format #t "~f" "1e-1") @print{} 0.1 | |
362 | @end example | |
363 | ||
80a894c9 KR |
364 | @nicode{~@@f} prints a @nicode{+} sign on positive numbers (including |
365 | zero). | |
76d3f3d4 KR |
366 | |
367 | @example | |
368 | (format #t "~@@f" 0) @print{} +0.0 | |
369 | @end example | |
370 | ||
371 | If the output is less than @var{width} characters it's padded on the | |
372 | left with @var{padchar} (space by default). If the output equals or | |
373 | exceeds @var{width} then there's no padding. The default for | |
374 | @var{width} is no padding. | |
375 | ||
376 | @example | |
377 | (format #f "~6f" -1.5) @result{} " -1.5" | |
378 | (format #f "~6,,,,'*f" 23) @result{} "**23.0" | |
379 | (format #f "~6f" 1234567.0) @result{} "1234567.0" | |
380 | @end example | |
381 | ||
382 | @var{decimals} is how many digits to print after the decimal point, | |
383 | with the value rounded or padded with zeros as necessary. (The | |
384 | default is to output as many decimals as required.) | |
385 | ||
386 | @example | |
387 | (format #t "~1,2f" 3.125) @print{} 3.13 | |
388 | (format #t "~1,2f" 1.5) @print{} 1.50 | |
389 | @end example | |
390 | ||
391 | @var{scale} is a power of 10 applied to the value, moving the decimal | |
392 | point that many places. A positive @var{scale} increases the value | |
393 | shown, a negative decreases it. | |
394 | ||
395 | @example | |
396 | (format #t "~,,2f" 1234) @print{} 123400.0 | |
397 | (format #t "~,,-2f" 1234) @print{} 12.34 | |
398 | @end example | |
399 | ||
400 | If @var{overflowchar} and @var{width} are both given and if the output | |
401 | would exceed @var{width}, then that many @var{overflowchar}s are | |
402 | printed instead of the value. | |
403 | ||
404 | @example | |
9fd01bce AW |
405 | (format #t "~6,,,'xf" 12345) @print{} 12345. |
406 | (format #t "~5,,,'xf" 12345) @print{} xxxxx | |
76d3f3d4 KR |
407 | @end example |
408 | ||
afd08fdf LC |
409 | @item @nicode{~h} |
410 | Localized number@footnote{The @nicode{~h} format specifier first | |
411 | appeared in Guile version 2.0.6.}. Parameters: @var{width}, | |
412 | @var{decimals}, @var{padchar}. | |
413 | ||
414 | Like @nicode{~f}, output an exact or floating point number, but do so | |
415 | according to the current locale, or according to the given locale object | |
416 | when the @code{:} modifier is used (@pxref{Number Input and Output, | |
417 | @code{number->locale-string}}). | |
418 | ||
419 | @example | |
420 | (format #t "~h" 12345.5678) ; with "C" as the current locale | |
421 | @print{} 12345.5678 | |
422 | ||
423 | (format #t "~14,,'*:h" 12345.5678 | |
424 | (make-locale LC_ALL "en_US")) | |
425 | @print{} ***12,345.5678 | |
426 | ||
427 | (format #t "~,2:h" 12345.5678 | |
428 | (make-locale LC_NUMERIC "fr_FR")) | |
429 | @print{} 12 345,56 | |
430 | @end example | |
431 | ||
76d3f3d4 KR |
432 | @item @nicode{~e} |
433 | Exponential float. Parameters: @var{width}, @var{mantdigits}, | |
434 | @var{expdigits}, @var{intdigits}, @var{overflowchar}, @var{padchar}, | |
435 | @var{expchar}. | |
436 | ||
437 | Output a number or number string in exponential notation. | |
438 | ||
439 | @example | |
440 | (format #t "~e" 5000.25) @print{} 5.00025E+3 | |
441 | (format #t "~e" "123.4") @print{} 1.234E+2 | |
442 | (format #t "~e" "1e4") @print{} 1.0E+4 | |
443 | @end example | |
444 | ||
80a894c9 KR |
445 | @nicode{~@@e} prints a @nicode{+} sign on positive numbers (including |
446 | zero). (This is for the mantissa, a @nicode{+} or @nicode{-} sign is | |
447 | always shown on the exponent.) | |
76d3f3d4 KR |
448 | |
449 | @example | |
450 | (format #t "~@@e" 5000.0) @print{} +5.0E+3 | |
451 | @end example | |
452 | ||
453 | If the output is less than @var{width} characters it's padded on the | |
454 | left with @var{padchar} (space by default). The default for | |
455 | @var{width} is to output with no padding. | |
456 | ||
457 | @example | |
458 | (format #f "~10e" 1234.0) @result{} " 1.234E+3" | |
459 | (format #f "~10,,,,,'*e" 0.5) @result{} "****5.0E-1" | |
460 | @end example | |
461 | ||
462 | @c FIXME: Describe what happens when the number is bigger than WIDTH. | |
463 | @c There seems to be a bit of dodginess about this, or some deviation | |
464 | @c from Common Lisp. | |
465 | ||
466 | @var{mantdigits} is the number of digits shown in the mantissa after | |
467 | the decimal point. The value is rounded or trailing zeros are added | |
468 | as necessary. The default @var{mantdigits} is to show as much as | |
469 | needed by the value. | |
470 | ||
471 | @example | |
472 | (format #f "~,3e" 11111.0) @result{} "1.111E+4" | |
473 | (format #f "~,8e" 123.0) @result{} "1.23000000E+2" | |
474 | @end example | |
475 | ||
476 | @var{expdigits} is the minimum number of digits shown for the | |
477 | exponent, with leading zeros added if necessary. The default for | |
478 | @var{expdigits} is to show only as many digits as required. At least | |
479 | 1 digit is always shown. | |
480 | ||
481 | @example | |
482 | (format #f "~,,1e" 1.0e99) @result{} "1.0E+99" | |
483 | (format #f "~,,6e" 1.0e99) @result{} "1.0E+000099" | |
484 | @end example | |
485 | ||
486 | @var{intdigits} (default 1) is the number of digits to show before the | |
487 | decimal point in the mantissa. @var{intdigits} can be zero, in which | |
488 | case the integer part is a single @nicode{0}, or it can be negative, | |
489 | in which case leading zeros are shown after the decimal point. | |
490 | ||
491 | @c FIXME: When INTDIGITS is 0, Common Lisp format apparently only | |
492 | @c shows the single 0 digit if it fits in WIDTH. format.scm seems to | |
493 | @c show it always. Is it meant to? | |
494 | ||
495 | @example | |
496 | (format #t "~,,,3e" 12345.0) @print{} 123.45E+2 | |
497 | (format #t "~,,,0e" 12345.0) @print{} 0.12345E+5 | |
498 | (format #t "~,,,-3e" 12345.0) @print{} 0.00012345E+8 | |
499 | @end example | |
500 | ||
501 | @c FIXME: MANTDIGITS with negative INTDIGITS doesn't match CL spec, | |
502 | @c believe the spec says it ought to still show mantdigits+1 sig | |
679cceed | 503 | @c figures, i.e. leading zeros don't count towards MANTDIGITS, but it |
76d3f3d4 KR |
504 | @c seems to just treat MANTDIGITS as how many digits after the |
505 | @c decimal point. | |
506 | ||
507 | If @var{overflowchar} is given then @var{width} is a hard limit. If | |
508 | the output would exceed @var{width} then instead that many | |
509 | @var{overflowchar}s are printed. | |
510 | ||
511 | @example | |
512 | (format #f "~6,,,,'xe" 100.0) @result{} "1.0E+2" | |
513 | (format #f "~3,,,,'xe" 100.0) @result{} "xxx" | |
514 | @end example | |
515 | ||
516 | @var{expchar} is the exponent marker character (default @nicode{E}). | |
517 | ||
518 | @example | |
519 | (format #t "~,,,,,,'ee" 100.0) @print{} 1.0e+2 | |
520 | @end example | |
521 | ||
522 | @item @nicode{~g} | |
523 | General float. Parameters: @var{width}, @var{mantdigits}, | |
524 | @var{expdigits}, @var{intdigits}, @var{overflowchar}, @var{padchar}, | |
525 | @var{expchar}. | |
526 | ||
527 | Output a number or number string in either exponential format the same | |
528 | as @nicode{~e}, or fixed-point format like @nicode{~f} but aligned | |
529 | where the mantissa would have been and followed by padding where the | |
530 | exponent would have been. | |
531 | ||
532 | @c FIXME: The default MANTDIGITS is apparently max(needed,min(n,7)) | |
533 | @c where 10^(n-1)<=abs(x)<=10^n. But the Common Lisp spec seems to | |
534 | @c ask for "needed" to be without leading or trailing zeros, whereas | |
535 | @c format.scm seems to include trailing zeros, ending up with it | |
536 | @c using fixed format for bigger values than it should. | |
537 | ||
538 | Fixed-point is used when the absolute value is 0.1 or more and it | |
539 | takes no more space than the mantissa in exponential format, ie.@: | |
540 | basically up to @var{mantdigits} digits. | |
541 | ||
542 | @example | |
543 | (format #f "~12,4,2g" 999.0) @result{} " 999.0 " | |
544 | (format #f "~12,4,2g" "100000") @result{} " 1.0000E+05" | |
545 | @end example | |
546 | ||
547 | The parameters are interpreted as per @nicode{~e} above. When | |
548 | fixed-point is used, the @var{decimals} parameter to @nicode{~f} is | |
549 | established from @var{mantdigits}, so as to give a total | |
550 | @math{@var{mantdigits}+1} figures. | |
551 | ||
552 | @item @nicode{~$} | |
553 | Monetary style fixed-point float. Parameters: @var{decimals}, | |
554 | @var{intdigits}, @var{width}, @var{padchar}. | |
555 | ||
556 | @c For reference, fmtdoc.txi from past versions of slib showed the | |
557 | @c INTDIGITS parameter as SCALE. That looks like a typo, in the code | |
558 | @c and in the Common Lisp spec it's a minimum digits for the integer | |
559 | @c part, it isn't a power of 10 like in ~f. | |
560 | ||
561 | Output a number or number string in fixed-point format, ie.@: with a | |
562 | decimal point. @var{decimals} is the number of decimal places to | |
563 | show, default 2. | |
564 | ||
565 | @example | |
566 | (format #t "~$" 5) @print{} 5.00 | |
567 | (format #t "~4$" "2.25") @print{} 2.2500 | |
568 | (format #t "~4$" "1e-2") @print{} 0.0100 | |
569 | @end example | |
570 | ||
80a894c9 KR |
571 | @nicode{~@@$} prints a @nicode{+} sign on positive numbers (including |
572 | zero). | |
76d3f3d4 KR |
573 | |
574 | @example | |
575 | (format #t "~@@$" 0) @print{} +0.00 | |
576 | @end example | |
577 | ||
578 | @var{intdigits} is a minimum number of digits to show in the integer | |
579 | part of the value (default 1). | |
580 | ||
581 | @example | |
582 | (format #t "~,3$" 9.5) @print{} 009.50 | |
583 | (format #t "~,0$" 0.125) @print{} .13 | |
584 | @end example | |
585 | ||
586 | If the output is less than @var{width} characters (default 0), it's | |
80a894c9 KR |
587 | padded on the left with @var{padchar} (default space). @nicode{~:$} |
588 | puts the padding after the sign. | |
76d3f3d4 KR |
589 | |
590 | @example | |
591 | (format #f "~,,8$" -1.5) @result{} " -1.50" | |
592 | (format #f "~,,8:$" -1.5) @result{} "- 1.50" | |
40296bab | 593 | (format #f "~,,8,'.:@@$" 3) @result{} "+...3.00" |
76d3f3d4 KR |
594 | @end example |
595 | ||
596 | Note that floating point for dollar amounts is generally not a good | |
597 | idea, because a cent @math{0.01} cannot be represented exactly in the | |
598 | binary floating point Guile uses, which leads to slowly accumulating | |
599 | rounding errors. Keeping values as cents (or fractions of a cent) in | |
600 | integers then printing with the scale option in @nicode{~f} may be a | |
601 | better approach. | |
602 | ||
603 | @c For reference, fractions don't work with ~$ (or any of the float | |
604 | @c conversions) currently. If they did work then we could perhaps | |
605 | @c suggest keeping dollar amounts as rationals, which would of course | |
606 | @c give exact cents. An integer as cents is probably still a better | |
607 | @c recommendation though, since it forces one to think about where | |
608 | @c and when rounding can or should occur. | |
609 | ||
610 | @item @nicode{~i} | |
611 | Complex fixed-point float. Parameters: @var{width}, @var{decimals}, | |
612 | @var{scale}, @var{overflowchar}, @var{padchar}. | |
613 | ||
614 | @c For reference, in Common Lisp ~i is an indent, but slib fmtdoc.txi | |
615 | @c described it as complex number output, so we keep that. | |
616 | ||
617 | Output the argument as a complex number, with both real and imaginary | |
618 | part shown (even if one or both are zero). | |
619 | ||
620 | The parameters and modifiers are the same as for fixed-point | |
621 | @nicode{~f} described above. The real and imaginary parts are both | |
622 | output with the same given parameters and modifiers, except that for | |
623 | the imaginary part the @nicode{@@} modifier is always enabled, so as | |
624 | to print a @nicode{+} sign between the real and imaginary parts. | |
625 | ||
626 | @example | |
627 | (format #t "~i" 1) @print{} 1.0+0.0i | |
628 | @end example | |
629 | ||
630 | @item @nicode{~p} | |
631 | Plural. No parameters. | |
632 | ||
633 | Output nothing if the argument is 1, or @samp{s} for any other | |
634 | value. | |
635 | ||
636 | @example | |
637 | (format #t "enter name~p" 1) @print{} enter name | |
638 | (format #t "enter name~p" 2) @print{} enter names | |
639 | @end example | |
640 | ||
80a894c9 | 641 | @nicode{~@@p} prints @samp{y} for 1 or @samp{ies} otherwise. |
76d3f3d4 KR |
642 | |
643 | @example | |
644 | (format #t "pupp~@@p" 1) @print{} puppy | |
645 | (format #t "pupp~@@p" 2) @print{} puppies | |
646 | @end example | |
647 | ||
80a894c9 KR |
648 | @nicode{~:p} re-uses the preceding argument instead of taking a new |
649 | one, which can be convenient when printing some sort of count. | |
76d3f3d4 KR |
650 | |
651 | @example | |
80a894c9 | 652 | (format #t "~d cat~:p" 9) @print{} 9 cats |
40296bab | 653 | (format #t "~d pupp~:@@p" 5) @print{} 5 puppies |
76d3f3d4 KR |
654 | @end example |
655 | ||
80a894c9 KR |
656 | @nicode{~p} is designed for English plurals and there's no attempt to |
657 | support other languages. @nicode{~[} conditionals (below) may be able | |
658 | to help. When using @code{gettext} to translate messages | |
659 | @code{ngettext} is probably best though | |
660 | (@pxref{Internationalization}). | |
661 | ||
76d3f3d4 | 662 | @item @nicode{~y} |
b8596c08 AW |
663 | Structured printing. Parameters: @var{width}. |
664 | ||
665 | @nicode{~y} outputs an argument using @code{pretty-print} | |
666 | (@pxref{Pretty Printing}). The result will be formatted to fit within | |
667 | @var{width} columns (79 by default), consuming multiple lines if | |
668 | necessary. | |
76d3f3d4 | 669 | |
b8596c08 AW |
670 | @nicode{~@@y} outputs an argument using @code{truncated-print} |
671 | (@pxref{Pretty Printing}). The resulting code will be formatted to fit | |
672 | within @var{width} columns (79 by default), on a single line. The | |
673 | output will be truncated if necessary. | |
76d3f3d4 | 674 | |
9274c3dd AW |
675 | @nicode{~:@@y} is like @nicode{~@@y}, except the @var{width} parameter |
676 | is interpreted to be the maximum column to which to output. That is to | |
677 | say, if you are at column 10, and @nicode{~60:@@y} is seen, the datum | |
678 | will be truncated to 50 columns. | |
76d3f3d4 KR |
679 | |
680 | @item @nicode{~?} | |
681 | @itemx @nicode{~k} | |
682 | Sub-format. No parameters. | |
683 | ||
684 | Take a format string argument and a second argument which is a list of | |
80a894c9 KR |
685 | arguments for that string, and output the result. |
686 | ||
687 | @example | |
688 | (format #t "~?" "~d ~d" '(1 2)) @print{} 1 2 | |
689 | @end example | |
690 | ||
691 | @nicode{~@@?} takes arguments for the sub-format directly rather than | |
692 | in a list. | |
76d3f3d4 KR |
693 | |
694 | @example | |
76d3f3d4 KR |
695 | (format #t "~@@? ~s" "~d ~d" 1 2 "foo") @print{} 1 2 "foo" |
696 | @end example | |
697 | ||
698 | @nicode{~?} and @nicode{~k} are the same, @nicode{~k} is provided for | |
699 | T-Scheme compatibility. | |
700 | ||
701 | @item @nicode{~*} | |
702 | Argument jumping. Parameter: @var{N}. | |
703 | ||
80a894c9 KR |
704 | Move forward @var{N} arguments (default 1) in the argument list. |
705 | @nicode{~:*} moves backwards. (@var{N} cannot be negative.) | |
a0e07ba4 | 706 | |
76d3f3d4 | 707 | @example |
471d2c6d KR |
708 | (format #f "~d ~2*~d" 1 2 3 4) @result{} "1 4" |
709 | (format #f "~d ~:*~d" 6) @result{} "6 6" | |
76d3f3d4 | 710 | @end example |
a0e07ba4 | 711 | |
80a894c9 KR |
712 | @nicode{~@@*} moves to argument number @var{N}. The first argument is |
713 | number 0 (and that's the default for @var{N}). | |
a0e07ba4 | 714 | |
76d3f3d4 KR |
715 | @example |
716 | (format #f "~d~d again ~@@*~d~d" 1 2) @result{} "12 again 12" | |
717 | (format #f "~d~d~d ~1@@*~d~d" 1 2 3) @result{} "123 23" | |
718 | @end example | |
a0e07ba4 | 719 | |
471d2c6d KR |
720 | A @nicode{#} move to the end followed by a @nicode{:} modifier move |
721 | back can be used for an absolute position relative to the end of the | |
722 | argument list, a reverse of what the @nicode{@@} modifier does. | |
a0e07ba4 | 723 | |
76d3f3d4 | 724 | @example |
471d2c6d | 725 | (format #t "~#*~2:*~a" 'a 'b 'c 'd) @print{} c |
76d3f3d4 | 726 | @end example |
a0e07ba4 | 727 | |
72b3aa56 | 728 | At the end of the format string the current argument position doesn't |
471d2c6d | 729 | matter, any further arguments are ignored. |
a0e07ba4 | 730 | |
76d3f3d4 KR |
731 | @item @nicode{~t} |
732 | Advance to a column position. Parameters: @var{colnum}, @var{colinc}, | |
733 | @var{padchar}. | |
a0e07ba4 | 734 | |
76d3f3d4 KR |
735 | Output @var{padchar} (space by default) to move to the given |
736 | @var{colnum} column. The start of the line is column 0, the default | |
737 | for @var{colnum} is 1. | |
a0e07ba4 | 738 | |
76d3f3d4 KR |
739 | @example |
740 | (format #f "~tX") @result{} " X" | |
741 | (format #f "~3tX") @result{} " X" | |
742 | @end example | |
a0e07ba4 | 743 | |
76d3f3d4 KR |
744 | If the current column is already past @var{colnum}, then the move is |
745 | to there plus a multiple of @var{colinc}, ie.@: column | |
746 | @math{@var{colnum} + @var{N} * @var{colinc}} for the smallest @var{N} | |
747 | which makes that value greater than or equal to the current column. | |
748 | The default @var{colinc} is 1 (which means no further move). | |
a0e07ba4 | 749 | |
76d3f3d4 KR |
750 | @example |
751 | (format #f "abcd~2,5,'.tx") @result{} "abcd...x" | |
752 | @end example | |
a0e07ba4 | 753 | |
80a894c9 KR |
754 | @nicode{~@@t} takes @var{colnum} as an offset from the current column. |
755 | @var{colnum} many pad characters are output, then further padding to | |
756 | make the current column a multiple of @var{colinc}, if it isn't | |
757 | already so. | |
76d3f3d4 KR |
758 | |
759 | @example | |
760 | (format #f "a~3,5'*@@tx") @result{} "a****x" | |
761 | @end example | |
762 | ||
471d2c6d KR |
763 | @nicode{~t} is implemented using @code{port-column} (@pxref{Reading}), |
764 | so it works even there has been other output before @code{format}. | |
765 | ||
76d3f3d4 KR |
766 | @item @nicode{~~} |
767 | Tilde character. Parameter: @var{n}. | |
768 | ||
769 | Output a tilde character @nicode{~}, or @var{n} many if a parameter is | |
770 | given. Normally @nicode{~} introduces an escape sequence, @nicode{~~} | |
771 | is the way to output a literal tilde. | |
772 | ||
773 | @item @nicode{~%} | |
774 | Newline. Parameter: @var{n}. | |
775 | ||
776 | Output a newline character, or @var{n} many if a parameter is given. | |
777 | A newline (or a few newlines) can of course be output just by | |
778 | including them in the format string. | |
779 | ||
780 | @item @nicode{~&} | |
781 | Start a new line. Parameter: @var{n}. | |
782 | ||
783 | Output a newline if not already at the start of a line. With a | |
784 | parameter, output that many newlines, but with the first only if not | |
785 | already at the start of a line. So for instance 3 would be a newline | |
786 | if not already at the start of a line, and 2 further newlines. | |
787 | ||
788 | @item @nicode{~_} | |
789 | Space character. Parameter: @var{n}. | |
790 | ||
791 | @c For reference, in Common Lisp ~_ is a conditional newline, but | |
792 | @c slib fmtdoc.txi described it as a space, so we keep that. | |
793 | ||
794 | Output a space character, or @var{n} many if a parameter is given. | |
795 | ||
796 | With a variable parameter this is one way to insert runtime calculated | |
797 | padding (@nicode{~t} or the various field widths can do similar | |
798 | things). | |
799 | ||
800 | @example | |
801 | (format #f "~v_foo" 4) @result{} " foo" | |
802 | @end example | |
803 | ||
804 | @item @nicode{~/} | |
805 | Tab character. Parameter: @var{n}. | |
806 | ||
807 | Output a tab character, or @var{n} many if a parameter is given. | |
808 | ||
809 | @item @nicode{~|} | |
810 | Formfeed character. Parameter: @var{n}. | |
811 | ||
812 | Output a formfeed character, or @var{n} many if a parameter is given. | |
813 | ||
814 | @item @nicode{~!} | |
815 | Force output. No parameters. | |
816 | ||
817 | At the end of output, call @code{force-output} to flush any buffers on | |
818 | the destination (@pxref{Writing}). @nicode{~!} can occur anywhere in | |
819 | the format string, but the force is done at the end of output. | |
820 | ||
821 | When output is to a string (destination @code{#f}), @nicode{~!} does | |
822 | nothing. | |
823 | ||
824 | @item @nicode{~newline} (ie.@: newline character) | |
825 | Continuation line. No parameters. | |
826 | ||
827 | Skip this newline and any following whitespace in the format string, | |
80a894c9 KR |
828 | ie.@: don't send it to the output. This can be used to break up a |
829 | long format string for readability, but not print the extra | |
76d3f3d4 KR |
830 | whitespace. |
831 | ||
76d3f3d4 KR |
832 | @example |
833 | (format #f "abc~ | |
834 | ~d def~ | |
835 | ~d" 1 2) @result{} "abc1 def2" | |
836 | @end example | |
837 | ||
80a894c9 KR |
838 | @nicode{~:newline} skips the newline but leaves any further whitespace |
839 | to be printed normally. | |
840 | ||
841 | @nicode{~@@newline} prints the newline then skips following | |
842 | whitespace. | |
843 | ||
76d3f3d4 | 844 | @item @nicode{~(} @nicode{~)} |
f0a9ab4d KR |
845 | Case conversion. No parameters. |
846 | ||
847 | Between @nicode{~(} and @nicode{~)} the case of all output is changed. | |
848 | The modifiers on @nicode{~(} control the conversion. | |
76d3f3d4 | 849 | |
f47029a1 | 850 | @itemize @w{} |
76d3f3d4 | 851 | @item |
80a894c9 | 852 | @nicode{~(} --- lower case. |
76d3f3d4 KR |
853 | @c |
854 | @c FIXME: The : and @ modifiers are not yet documented because the | |
855 | @c code applies string-capitalize and string-capitalize-first to each | |
856 | @c separate format:out-str call, which has various subtly doubtful | |
857 | @c effects. And worse they're applied to individual characters, | |
858 | @c including literal characters in the format string, which has the | |
859 | @c silly effect of being always an upcase. | |
860 | @c | |
861 | @c The Common Lisp spec is apparently for the capitalization to be | |
862 | @c applied in one hit to the whole of the output between ~( and ~). | |
863 | @c (This can no doubt be implemented without accumulating all that | |
864 | @c text, just by keeping a state or the previous char to tell whether | |
865 | @c within a word.) | |
866 | @c | |
867 | @c @item | |
868 | @c @nicode{:} --- first letter of each word upper case, the rest lower | |
869 | @c case, as per the @code{string-capitalize} function (@pxref{Alphabetic | |
870 | @c Case Mapping}). | |
871 | @c @item | |
872 | @c @nicode{@@} --- first letter of just the first word upper case, the | |
873 | @c rest lower case. | |
874 | @c | |
875 | @item | |
40296bab | 876 | @nicode{~:@@(} --- upper case. |
76d3f3d4 KR |
877 | @end itemize |
878 | ||
879 | For example, | |
880 | ||
881 | @example | |
882 | (format #t "~(Hello~)") @print{} hello | |
40296bab | 883 | (format #t "~:@@(Hello~)") @print{} HELLO |
76d3f3d4 KR |
884 | @end example |
885 | ||
886 | In the future it's intended the modifiers @nicode{:} and @nicode{@@} | |
887 | alone will capitalize the first letters of words, as per Common Lisp | |
888 | @code{format}, but the current implementation of this is flawed and | |
889 | not recommended for use. | |
890 | ||
891 | Case conversions do not nest, currently. This might change in the | |
892 | future, but if it does then it will be to Common Lisp style where the | |
893 | outermost conversion has priority, overriding inner ones (making those | |
894 | fairly pointless). | |
895 | ||
896 | @item @nicode{~@{} @nicode{~@}} | |
897 | Iteration. Parameter: @var{maxreps} (for @nicode{~@{}). | |
898 | ||
899 | The format between @nicode{~@{} and @nicode{~@}} is iterated. The | |
900 | modifiers to @nicode{~@{} determine how arguments are taken. The | |
901 | default is a list argument with each iteration successively consuming | |
902 | elements from it. This is a convenient way to output a whole list. | |
903 | ||
904 | @example | |
905 | (format #t "~@{~d~@}" '(1 2 3)) @print{} 123 | |
906 | (format #t "~@{~s=~d ~@}" '("x" 1 "y" 2)) @print{} "x"=1 "y"=2 | |
907 | @end example | |
908 | ||
80a894c9 KR |
909 | @nicode{~:@{} takes a single argument which is a list of lists, each |
910 | of those contained lists gives the arguments for the iterated format. | |
76d3f3d4 | 911 | |
40296bab | 912 | @c @print{} on a new line here to avoid overflowing page width in DVI |
76d3f3d4 | 913 | @example |
40296bab KR |
914 | (format #t "~:@{~dx~d ~@}" '((1 2) (3 4) (5 6))) |
915 | @print{} 1x2 3x4 5x6 | |
76d3f3d4 KR |
916 | @end example |
917 | ||
80a894c9 KR |
918 | @nicode{~@@@{} takes arguments directly, with each iteration |
919 | successively consuming arguments. | |
76d3f3d4 KR |
920 | |
921 | @example | |
922 | (format #t "~@@@{~d~@}" 1 2 3) @print{} 123 | |
923 | (format #t "~@@@{~s=~d ~@}" "x" 1 "y" 2) @print{} "x"=1 "y"=2 | |
924 | @end example | |
925 | ||
40296bab | 926 | @nicode{~:@@@{} takes list arguments, one argument for each iteration, |
80a894c9 | 927 | using that list for the format. |
76d3f3d4 | 928 | |
40296bab | 929 | @c @print{} on a new line here to avoid overflowing page width in DVI |
76d3f3d4 | 930 | @example |
40296bab KR |
931 | (format #t "~:@@@{~dx~d ~@}" '(1 2) '(3 4) '(5 6)) |
932 | @print{} 1x2 3x4 5x6 | |
76d3f3d4 KR |
933 | @end example |
934 | ||
935 | Iterating stops when there are no more arguments or when the | |
936 | @var{maxreps} parameter to @nicode{~@{} is reached (default no | |
937 | maximum). | |
938 | ||
939 | @example | |
940 | (format #t "~2@{~d~@}" '(1 2 3 4)) @print{} 12 | |
941 | @end example | |
942 | ||
943 | If the format between @nicode{~@{} and @nicode{~@}} is empty, then a | |
944 | format string argument is taken (before iteration argument(s)) and | |
945 | used instead. This allows a sub-format (like @nicode{~?} above) to be | |
946 | iterated. | |
947 | ||
948 | @example | |
949 | (format #t "~@{~@}" "~d" '(1 2 3)) @print{} 123 | |
950 | @end example | |
951 | ||
952 | @c FIXME: What is the @nicode{:} modifier to ~} meant to do? The | |
953 | @c Common Lisp spec says it's a minimum of 1 iteration, but the | |
954 | @c format.scm code seems to merely make it have MAXREPS default to 1. | |
955 | ||
956 | Iterations can be nested, an inner iteration operates in the same way | |
957 | as described, but of course on the arguments the outer iteration | |
958 | provides it. This can be used to work into nested list structures. | |
959 | For example in the following the inner @nicode{~@{~d~@}x} is applied | |
960 | to @code{(1 2)} then @code{(3 4 5)} etc. | |
961 | ||
962 | @example | |
963 | (format #t "~@{~@{~d~@}x~@}" '((1 2) (3 4 5))) @print{} 12x345x | |
964 | @end example | |
965 | ||
80a894c9 KR |
966 | See also @nicode{~^} below for escaping from iteration. |
967 | ||
76d3f3d4 KR |
968 | @item @nicode{~[} @nicode{~;} @nicode{~]} |
969 | Conditional. Parameter: @var{selector}. | |
970 | ||
971 | A conditional block is delimited by @nicode{~[} and @nicode{~]}, and | |
972 | @nicode{~;} separates clauses within the block. @nicode{~[} takes an | |
973 | integer argument and that number clause is used. The first clause is | |
974 | number 0. | |
975 | ||
976 | @example | |
977 | (format #f "~[peach~;banana~;mango~]" 1) @result{} "banana" | |
978 | @end example | |
979 | ||
980 | The @var{selector} parameter can be used for the clause number, | |
981 | instead of taking an argument. | |
982 | ||
983 | @example | |
984 | (format #f "~2[peach~;banana~;mango~]") @result{} "mango" | |
985 | @end example | |
986 | ||
987 | If the clause number is out of range then nothing is output. Or the | |
80a894c9 | 988 | last clause can be @nicode{~:;} to use that for a number out of range. |
76d3f3d4 KR |
989 | |
990 | @example | |
991 | (format #f "~[banana~;mango~]" 99) @result{} "" | |
992 | (format #f "~[banana~;mango~:;fruit~]" 99) @result{} "fruit" | |
993 | @end example | |
994 | ||
80a894c9 KR |
995 | @nicode{~:[} treats the argument as a flag, and expects two clauses. |
996 | The first is used if the argument is @code{#f} or the second | |
997 | otherwise. | |
76d3f3d4 KR |
998 | |
999 | @example | |
1000 | (format #f "~:[false~;not false~]" #f) @result{} "false" | |
1001 | (format #f "~:[false~;not false~]" 'abc) @result{} "not false" | |
1002 | ||
1003 | (let ((n 3)) | |
1004 | (format #t "~d gnu~:[s are~; is~] here" n (= 1 n))) | |
1005 | @print{} 3 gnus are here | |
1006 | @end example | |
1007 | ||
80a894c9 KR |
1008 | @nicode{~@@[} also treats the argument as a flag, and expects one |
1009 | clause. If the argument is @code{#f} then no output is produced and | |
1010 | the argument is consumed, otherwise the clause is used and the | |
1011 | argument is not consumed, it's left for the clause. This can be used | |
1012 | for instance to suppress output if @code{#f} means something not | |
1013 | available. | |
76d3f3d4 KR |
1014 | |
1015 | @example | |
1016 | (format #f "~@@[temperature=~d~]" 27) @result{} "temperature=27" | |
1017 | (format #f "~@@[temperature=~d~]" #f) @result{} "" | |
1018 | @end example | |
1019 | ||
1020 | @item @nicode{~^} | |
1021 | Escape. Parameters: @var{val1}, @var{val2}, @var{val3}. | |
1022 | ||
1023 | Stop formatting if there are no more arguments. This can be used for | |
80a894c9 | 1024 | instance to have a format string adapt to a variable number of |
76d3f3d4 KR |
1025 | arguments. |
1026 | ||
1027 | @example | |
1028 | (format #t "~d~^ ~d" 1) @print{} 1 | |
1029 | (format #t "~d~^ ~d" 1 2) @print{} 1 2 | |
1030 | @end example | |
1031 | ||
1032 | Within a @nicode{~@{} @nicode{~@}} iteration, @nicode{~^} stops the | |
1033 | current iteration step if there are no more arguments to that step, | |
80a894c9 KR |
1034 | but continuing with possible further steps and the rest of the format. |
1035 | This can be used for instance to avoid a separator on the last | |
1036 | iteration, or to adapt to variable length argument lists. | |
76d3f3d4 KR |
1037 | |
1038 | @example | |
1039 | (format #f "~@{~d~^/~@} go" '(1 2 3)) @result{} "1/2/3 go" | |
1040 | (format #f "~:@{ ~d~^~d~@} go" '((1) (2 3))) @result{} " 1 23 go" | |
1041 | @end example | |
1042 | ||
1043 | @c For reference, format.scm doesn't implement that Common Lisp ~:^ | |
1044 | @c modifier which stops the entire iterating of ~:{ or ~@:{. | |
1045 | ||
1046 | @c FIXME: Believe the Common Lisp spec is for ~^ within ~[ ~] | |
1047 | @c conditional to terminate the whole format (or iteration step if in | |
1048 | @c an iteration). But format.scm seems to terminate just the | |
1049 | @c conditional form. | |
1050 | @c | |
1051 | @c (format #f "~[abc~^def~;ghi~] blah" 0) | |
1052 | @c @result{} "abc blah" ;; looks wrong | |
1053 | ||
1054 | @c FIXME: Believe the Common Lisp spec is for ~^ within ~( ~) to end | |
1055 | @c that case conversion and then also terminate the whole format (or | |
1056 | @c iteration step if in an iteration). But format.scm doesn't seem | |
1057 | @c to do that quite right. | |
1058 | @c | |
1059 | @c (format #f "~d ~^ ~d" 1) @result{} "1 " | |
1060 | @c (format #f "~(~d ~^ ~d~)" 1) @result{} ERROR | |
1061 | ||
1062 | Within a @nicode{~?} sub-format, @nicode{~^} operates just on that | |
1063 | sub-format. If it terminates the sub-format then the originating | |
1064 | format will still continue. | |
1065 | ||
1066 | @example | |
1067 | (format #t "~? items" "~d~^ ~d" '(1)) @print{} 1 items | |
1068 | (format #t "~? items" "~d~^ ~d" '(1 2)) @print{} 1 2 items | |
1069 | @end example | |
1070 | ||
1071 | The parameters to @nicode{~^} (which are numbers) change the condition | |
1072 | used to terminate. For a single parameter, termination is when that | |
1073 | value is zero (notice this makes plain @nicode{~^} equivalent to | |
1074 | @nicode{~#^}). For two parameters, termination is when those two are | |
1075 | equal. For three parameters, termination is when @math{@var{val1} | |
1076 | @le{} @var{val2}} and @math{@var{val2} @le{} @var{val3}}. | |
1077 | ||
1078 | @c FIXME: Good examples of these? | |
1079 | ||
1080 | @item @nicode{~q} | |
80a894c9 KR |
1081 | Inquiry message. Insert a copyright message into the output. |
1082 | ||
1083 | @nicode{~:q} inserts the format implementation version. | |
a0e07ba4 NJ |
1084 | @end table |
1085 | ||
76d3f3d4 | 1086 | @sp 1 |
471d2c6d KR |
1087 | It's an error if there are not enough arguments for the escapes in the |
1088 | format string, but any excess arguments are ignored. | |
76d3f3d4 KR |
1089 | |
1090 | Iterations @nicode{~@{} @nicode{~@}} and conditionals @nicode{~[} | |
1091 | @nicode{~;} @nicode{~]} can be nested, but must be properly nested, | |
1092 | meaning the inner form must be entirely within the outer form. So | |
1093 | it's not possible, for instance, to try to conditionalize the endpoint | |
1094 | of an iteration. | |
1095 | ||
1096 | @example | |
1097 | (format #t "~@{ ~[ ... ~] ~@}" ...) ;; good | |
1098 | (format #t "~@{ ~[ ... ~@} ... ~]" ...) ;; bad | |
1099 | @end example | |
1100 | ||
1101 | The same applies to case conversions @nicode{~(} @nicode{~)}, they | |
1102 | must properly nest with respect to iterations and conditionals (though | |
1103 | currently a case conversion cannot nest within another case | |
1104 | conversion). | |
1105 | ||
1106 | When a sub-format (@nicode{~?}) is used, that sub-format string must | |
1107 | be self-contained. It cannot for instance give a @nicode{~@{} to | |
1108 | begin an iteration form and have the @nicode{~@}} up in the | |
1109 | originating format, or similar. | |
a0e07ba4 NJ |
1110 | @end deffn |
1111 | ||
76d3f3d4 KR |
1112 | @sp 1 |
1113 | Guile contains a @code{format} procedure even when the module | |
1114 | @code{(ice-9 format)} is not loaded. The default @code{format} is | |
1115 | @code{simple-format} (@pxref{Writing}), it doesn't support all escape | |
1116 | sequences documented in this section, and will signal an error if you | |
1117 | try to use one of them. The reason for two versions is that the full | |
1118 | @code{format} is fairly large and requires some time to load. | |
1119 | @code{simple-format} is often adequate too. | |
a0e07ba4 NJ |
1120 | |
1121 | ||
6da1534c | 1122 | @node File Tree Walk |
3229f68b | 1123 | @section File Tree Walk |
6da1534c KR |
1124 | @cindex file tree walk |
1125 | ||
af98fafa LC |
1126 | @cindex file system traversal |
1127 | @cindex directory traversal | |
1128 | ||
6da1534c | 1129 | The functions in this section traverse a tree of files and |
243db01e LC |
1130 | directories. They come in two flavors: the first one is a high-level |
1131 | functional interface, and the second one is similar to the C @code{ftw} | |
1132 | and @code{nftw} routines (@pxref{Working with Directory Trees,,, libc, | |
1133 | GNU C Library Reference Manual}). | |
6da1534c KR |
1134 | |
1135 | @example | |
1136 | (use-modules (ice-9 ftw)) | |
1137 | @end example | |
1138 | @sp 1 | |
1139 | ||
7948c5d9 | 1140 | @deffn {Scheme Procedure} file-system-tree file-name [enter? [stat]] |
243db01e | 1141 | Return a tree of the form @code{(@var{file-name} @var{stat} |
af98fafa | 1142 | @var{children} ...)} where @var{stat} is the result of @code{(@var{stat} |
243db01e LC |
1143 | @var{file-name})} and @var{children} are similar structures for each |
1144 | file contained in @var{file-name} when it designates a directory. | |
1145 | ||
1146 | The optional @var{enter?} predicate is invoked as @code{(@var{enter?} | |
1147 | @var{name} @var{stat})} and should return true to allow recursion into | |
1148 | directory @var{name}; the default value is a procedure that always | |
1149 | returns @code{#t}. When a directory does not match @var{enter?}, it | |
1150 | nonetheless appears in the resulting tree, only with zero children. | |
1151 | ||
af98fafa LC |
1152 | The @var{stat} argument is optional and defaults to @code{lstat}, as for |
1153 | @code{file-system-fold} (see below.) | |
1154 | ||
243db01e LC |
1155 | The example below shows how to obtain a hierarchical listing of the |
1156 | files under the @file{module/language} directory in the Guile source | |
1157 | tree, discarding their @code{stat} info: | |
1158 | ||
1159 | @example | |
1160 | (use-modules (ice-9 match)) | |
1161 | ||
1162 | (define remove-stat | |
1163 | ;; Remove the `stat' object the `file-system-tree' provides | |
1164 | ;; for each file in the tree. | |
1165 | (match-lambda | |
1166 | ((name stat) ; flat file | |
1167 | name) | |
1168 | ((name stat children ...) ; directory | |
1169 | (list name (map remove-stat children))))) | |
1170 | ||
1171 | (let ((dir (string-append (assq-ref %guile-build-info 'top_srcdir) | |
1172 | "/module/language"))) | |
1173 | (remove-stat (file-system-tree dir))) | |
1174 | ||
1175 | @result{} | |
1176 | ("language" | |
1177 | (("value" ("spec.go" "spec.scm")) | |
1178 | ("scheme" | |
1179 | ("spec.go" | |
1180 | "spec.scm" | |
1181 | "compile-tree-il.scm" | |
1182 | "decompile-tree-il.scm" | |
1183 | "decompile-tree-il.go" | |
1184 | "compile-tree-il.go")) | |
1185 | ("tree-il" | |
1186 | ("spec.go" | |
1187 | "fix-letrec.go" | |
1188 | "inline.go" | |
1189 | "fix-letrec.scm" | |
1190 | "compile-glil.go" | |
1191 | "spec.scm" | |
1192 | "optimize.scm" | |
1193 | "primitives.scm" | |
1194 | @dots{})) | |
1195 | @dots{})) | |
1196 | @end example | |
7948c5d9 | 1197 | @end deffn |
243db01e LC |
1198 | |
1199 | @cindex file system combinator | |
1200 | ||
1201 | It is often desirable to process directories entries directly, rather | |
1202 | than building up a tree of entries in memory, like | |
1203 | @code{file-system-tree} does. The following procedure, a | |
1204 | @dfn{combinator}, is designed to allow directory entries to be processed | |
1205 | directly as a directory tree is traversed; in fact, | |
1206 | @code{file-system-tree} is implemented in terms of it. | |
1207 | ||
be96155b | 1208 | @deffn {Scheme Procedure} file-system-fold enter? leaf down up skip error init file-name [stat] |
243db01e LC |
1209 | Traverse the directory at @var{file-name}, recursively, and return the |
1210 | result of the successive applications of the @var{leaf}, @var{down}, | |
1211 | @var{up}, and @var{skip} procedures as described below. | |
1212 | ||
1213 | Enter sub-directories only when @code{(@var{enter?} @var{path} | |
1214 | @var{stat} @var{result})} returns true. When a sub-directory is | |
1215 | entered, call @code{(@var{down} @var{path} @var{stat} @var{result})}, | |
1216 | where @var{path} is the path of the sub-directory and @var{stat} the | |
af98fafa | 1217 | result of @code{(false-if-exception (@var{stat} @var{path}))}; when it is |
243db01e LC |
1218 | left, call @code{(@var{up} @var{path} @var{stat} @var{result})}. |
1219 | ||
1220 | For each file in a directory, call @code{(@var{leaf} @var{path} | |
1221 | @var{stat} @var{result})}. | |
1222 | ||
1223 | When @var{enter?} returns @code{#f}, or when an unreadable directory is | |
1224 | encountered, call @code{(@var{skip} @var{path} @var{stat} | |
1225 | @var{result})}. | |
1226 | ||
1227 | When @var{file-name} names a flat file, @code{(@var{leaf} @var{path} | |
1228 | @var{stat} @var{init})} is returned. | |
1229 | ||
be96155b LC |
1230 | When an @code{opendir} or @var{stat} call fails, call @code{(@var{error} |
1231 | @var{path} @var{stat} @var{errno} @var{result})}, with @var{errno} being | |
1232 | the operating system error number that was raised---e.g., | |
1233 | @code{EACCES}---and @var{stat} either @code{#f} or the result of the | |
1234 | @var{stat} call for that entry, when available. | |
1235 | ||
243db01e LC |
1236 | The special @file{.} and @file{..} entries are not passed to these |
1237 | procedures. The @var{path} argument to the procedures is a full file | |
1238 | name---e.g., @code{"../foo/bar/gnu"}; if @var{file-name} is an absolute | |
1239 | file name, then @var{path} is also an absolute file name. Files and | |
1240 | directories, as identified by their device/inode number pair, are | |
1241 | traversed only once. | |
1242 | ||
af98fafa LC |
1243 | The optional @var{stat} argument defaults to @code{lstat}, which means |
1244 | that symbolic links are not followed; the @code{stat} procedure can be | |
1245 | used instead when symbolic links are to be followed (@pxref{File System, | |
1246 | stat}). | |
1247 | ||
243db01e LC |
1248 | The example below illustrates the use of @code{file-system-fold}: |
1249 | ||
1250 | @example | |
1251 | (define (total-file-size file-name) | |
1252 | "Return the size in bytes of the files under FILE-NAME (similar | |
1253 | to `du --apparent-size' with GNU Coreutils.)" | |
1254 | ||
1255 | (define (enter? name stat result) | |
1256 | ;; Skip version control directories. | |
1257 | (not (member (basename name) '(".git" ".svn" "CVS")))) | |
1258 | (define (leaf name stat result) | |
1259 | ;; Return RESULT plus the size of the file at NAME. | |
1260 | (+ result (stat:size stat))) | |
1261 | ||
1262 | ;; Count zero bytes for directories. | |
1263 | (define (down name stat result) result) | |
1264 | (define (up name stat result) result) | |
1265 | ||
1266 | ;; Likewise for skipped directories. | |
1267 | (define (skip name stat result) result) | |
1268 | ||
be96155b LC |
1269 | ;; Ignore unreadable files/directories but warn the user. |
1270 | (define (error name stat errno result) | |
1271 | (format (current-error-port) "warning: ~a: ~a~%" | |
1272 | name (strerror errno)) | |
1273 | result) | |
1274 | ||
1275 | (file-system-fold enter? leaf down up skip error | |
243db01e LC |
1276 | 0 ; initial counter is zero bytes |
1277 | file-name)) | |
1278 | ||
1279 | (total-file-size ".") | |
1280 | @result{} 8217554 | |
1281 | ||
1282 | (total-file-size "/dev/null") | |
1283 | @result{} 0 | |
1284 | @end example | |
7948c5d9 | 1285 | @end deffn |
243db01e LC |
1286 | |
1287 | The alternative C-like functions are described below. | |
1288 | ||
7948c5d9 | 1289 | @deffn {Scheme Procedure} scandir name [select? [entry<?]] |
1629429d LC |
1290 | Return the list of the names of files contained in directory @var{name} |
1291 | that match predicate @var{select?} (by default, all files). The | |
1292 | returned list of file names is sorted according to @var{entry<?}, which | |
1293 | defaults to @code{string-locale<?} such that file names are sorted in | |
de929870 LC |
1294 | the locale's alphabetical order (@pxref{Text Collation}). Return |
1295 | @code{#f} when @var{name} is unreadable or is not a directory. | |
1629429d LC |
1296 | |
1297 | This procedure is modeled after the C library function of the same name | |
1298 | (@pxref{Scanning Directory Content,,, libc, GNU C Library Reference | |
1299 | Manual}). | |
7948c5d9 | 1300 | @end deffn |
1629429d | 1301 | |
7948c5d9 | 1302 | @deffn {Scheme Procedure} ftw startname proc ['hash-size n] |
c4e84357 | 1303 | Walk the file system tree descending from @var{startname}, calling |
6da1534c KR |
1304 | @var{proc} for each file and directory. |
1305 | ||
1306 | Hard links and symbolic links are followed. A file or directory is | |
1307 | reported to @var{proc} only once, and skipped if seen again in another | |
1308 | place. One consequence of this is that @code{ftw} is safe against | |
1309 | circularly linked directory structures. | |
1310 | ||
1311 | Each @var{proc} call is @code{(@var{proc} filename statinfo flag)} and | |
1312 | it should return @code{#t} to continue, or any other value to stop. | |
1313 | ||
1314 | @var{filename} is the item visited, being @var{startname} plus a | |
1315 | further path and the name of the item. @var{statinfo} is the return | |
1316 | from @code{stat} (@pxref{File System}) on @var{filename}. @var{flag} | |
1317 | is one of the following symbols, | |
1318 | ||
1319 | @table @code | |
1320 | @item regular | |
1321 | @var{filename} is a file, this includes special files like devices, | |
1322 | named pipes, etc. | |
1323 | ||
1324 | @item directory | |
1325 | @var{filename} is a directory. | |
1326 | ||
1327 | @item invalid-stat | |
1328 | An error occurred when calling @code{stat}, so nothing is known. | |
1329 | @var{statinfo} is @code{#f} in this case. | |
1330 | ||
1331 | @item directory-not-readable | |
1332 | @var{filename} is a directory, but one which cannot be read and hence | |
1333 | won't be recursed into. | |
1334 | ||
1335 | @item symlink | |
1336 | @var{filename} is a dangling symbolic link. Symbolic links are | |
1337 | normally followed and their target reported, the link itself is | |
1338 | reported if the target does not exist. | |
1339 | @end table | |
1340 | ||
1341 | The return value from @code{ftw} is @code{#t} if it ran to completion, | |
1342 | or otherwise the non-@code{#t} value from @var{proc} which caused the | |
1343 | stop. | |
1344 | ||
1345 | Optional argument symbol @code{hash-size} and an integer can be given | |
1346 | to set the size of the hash table used to track items already visited. | |
1347 | (@pxref{Hash Table Reference}) | |
1348 | ||
1349 | @c Actually, it's probably safe to escape from ftw, just need to | |
1350 | @c check it. | |
1351 | @c | |
1352 | In the current implementation, returning non-@code{#t} from @var{proc} | |
1353 | is the only valid way to terminate @code{ftw}. @var{proc} must not | |
1354 | use @code{throw} or similar to escape. | |
7948c5d9 | 1355 | @end deffn |
6da1534c KR |
1356 | |
1357 | ||
7948c5d9 | 1358 | @deffn {Scheme Procedure} nftw startname proc ['chdir] ['depth] ['hash-size n] ['mount] ['physical] |
c4e84357 | 1359 | Walk the file system tree starting at @var{startname}, calling |
6da1534c KR |
1360 | @var{proc} for each file and directory. @code{nftw} has extra |
1361 | features over the basic @code{ftw} described above. | |
1362 | ||
40296bab KR |
1363 | Like @code{ftw}, hard links and symbolic links are followed. A file |
1364 | or directory is reported to @var{proc} only once, and skipped if seen | |
1365 | again in another place. One consequence of this is that @code{nftw} | |
1366 | is safe against circular linked directory structures. | |
6da1534c KR |
1367 | |
1368 | Each @var{proc} call is @code{(@var{proc} filename statinfo flag | |
40296bab | 1369 | base level)} and it should return @code{#t} to continue, or any |
6da1534c KR |
1370 | other value to stop. |
1371 | ||
1372 | @var{filename} is the item visited, being @var{startname} plus a | |
1373 | further path and the name of the item. @var{statinfo} is the return | |
40296bab KR |
1374 | from @code{stat} on @var{filename} (@pxref{File System}). @var{base} |
1375 | is an integer offset into @var{filename} which is where the basename | |
1376 | for this item begins. @var{level} is an integer giving the directory | |
1377 | nesting level, starting from 0 for the contents of @var{startname} (or | |
1378 | that item itself if it's a file). @var{flag} is one of the following | |
1379 | symbols, | |
6da1534c KR |
1380 | |
1381 | @table @code | |
1382 | @item regular | |
40296bab KR |
1383 | @var{filename} is a file, including special files like devices, named |
1384 | pipes, etc. | |
6da1534c KR |
1385 | |
1386 | @item directory | |
1387 | @var{filename} is a directory. | |
1388 | ||
1389 | @item directory-processed | |
1390 | @var{filename} is a directory, and its contents have all been visited. | |
1391 | This flag is given instead of @code{directory} when the @code{depth} | |
1392 | option below is used. | |
1393 | ||
1394 | @item invalid-stat | |
1395 | An error occurred when applying @code{stat} to @var{filename}, so | |
1396 | nothing is known about it. @var{statinfo} is @code{#f} in this case. | |
1397 | ||
1398 | @item directory-not-readable | |
1399 | @var{filename} is a directory, but one which cannot be read and hence | |
1400 | won't be recursed into. | |
1401 | ||
6da1534c | 1402 | @item stale-symlink |
40296bab KR |
1403 | @var{filename} is a dangling symbolic link. Links are normally |
1404 | followed and their target reported, the link itself is reported if its | |
1405 | target does not exist. | |
1406 | ||
1407 | @item symlink | |
1408 | When the @code{physical} option described below is used, this | |
1409 | indicates @var{filename} is a symbolic link whose target exists (and | |
1410 | is not being followed). | |
6da1534c KR |
1411 | @end table |
1412 | ||
1413 | The following optional arguments can be given to modify the way | |
1414 | @code{nftw} works. Each is passed as a symbol (and @code{hash-size} | |
1415 | takes a following integer value). | |
1416 | ||
1417 | @table @asis | |
1418 | @item @code{chdir} | |
1419 | Change to the directory containing the item before calling @var{proc}. | |
1420 | When @code{nftw} returns the original current directory is restored. | |
1421 | ||
40296bab KR |
1422 | Under this option, generally the @var{base} parameter to each |
1423 | @var{proc} call should be used to pick out the base part of the | |
1424 | @var{filename}. The @var{filename} is still a path but with a changed | |
1425 | directory it won't be valid (unless the @var{startname} directory was | |
1426 | absolute). | |
6da1534c KR |
1427 | |
1428 | @item @code{depth} | |
1429 | Visit files ``depth first'', meaning @var{proc} is called for the | |
1430 | contents of each directory before it's called for the directory | |
1431 | itself. Normally a directory is reported first, then its contents. | |
1432 | ||
1433 | Under this option, the @var{flag} to @var{proc} for a directory is | |
1434 | @code{directory-processed} instead of @code{directory}. | |
1435 | ||
1436 | @item @code{hash-size @var{n}} | |
1437 | Set the size of the hash table used to track items already visited. | |
1438 | (@pxref{Hash Table Reference}) | |
1439 | ||
1440 | @item @code{mount} | |
1441 | Don't cross a mount point, meaning only visit items on the same | |
c4e84357 | 1442 | file system as @var{startname} (ie.@: the same @code{stat:dev}). |
6da1534c KR |
1443 | |
1444 | @item @code{physical} | |
1445 | Don't follow symbolic links, instead report them to @var{proc} as | |
40296bab KR |
1446 | @code{symlink}. Dangling links (those whose target doesn't exist) are |
1447 | still reported as @code{stale-symlink}. | |
6da1534c KR |
1448 | @end table |
1449 | ||
1450 | The return value from @code{nftw} is @code{#t} if it ran to | |
1451 | completion, or otherwise the non-@code{#t} value from @var{proc} which | |
1452 | caused the stop. | |
1453 | ||
ecb87335 | 1454 | @c For reference, one reason not to escape is that the current |
6da1534c KR |
1455 | @c directory is not saved and restored with dynamic-wind. Maybe |
1456 | @c changing that would be enough to allow escaping. | |
1457 | @c | |
1458 | In the current implementation, returning non-@code{#t} from @var{proc} | |
1459 | is the only valid way to terminate @code{ftw}. @var{proc} must not | |
1460 | use @code{throw} or similar to escape. | |
7948c5d9 | 1461 | @end deffn |
6da1534c KR |
1462 | |
1463 | ||
2370f809 | 1464 | @node Queues |
3229f68b | 1465 | @section Queues |
d10196fc | 1466 | @cindex queues |
2370f809 KR |
1467 | @tindex Queues |
1468 | ||
1469 | @noindent | |
1470 | The functions in this section are provided by | |
1471 | ||
1472 | @example | |
1473 | (use-modules (ice-9 q)) | |
1474 | @end example | |
1475 | ||
1476 | This module implements queues holding arbitrary scheme objects and | |
1477 | designed for efficient first-in / first-out operations. | |
1478 | ||
1479 | @code{make-q} creates a queue, and objects are entered and removed | |
23f2b9a3 | 1480 | with @code{enq!} and @code{deq!}. @code{q-push!} and @code{q-pop!} |
2370f809 KR |
1481 | can be used too, treating the front of the queue like a stack. |
1482 | ||
1483 | @sp 1 | |
1484 | ||
1485 | @deffn {Scheme Procedure} make-q | |
1486 | Return a new queue. | |
1487 | @end deffn | |
1488 | ||
1489 | @deffn {Scheme Procedure} q? obj | |
1490 | Return @code{#t} if @var{obj} is a queue, or @code{#f} if not. | |
1491 | ||
1492 | Note that queues are not a distinct class of objects but are | |
1493 | implemented with cons cells. For that reason certain list structures | |
1494 | can get @code{#t} from @code{q?}. | |
1495 | @end deffn | |
1496 | ||
1497 | @deffn {Scheme Procedure} enq! q obj | |
1498 | Add @var{obj} to the rear of @var{q}, and return @var{q}. | |
1499 | @end deffn | |
1500 | ||
1501 | @deffn {Scheme Procedure} deq! q | |
1502 | @deffnx {Scheme Procedure} q-pop! q | |
1503 | Remove and return the front element from @var{q}. If @var{q} is | |
1504 | empty, a @code{q-empty} exception is thrown. | |
1505 | ||
1506 | @code{deq!} and @code{q-pop!} are the same operation, the two names | |
1507 | just let an application match @code{enq!} with @code{deq!}, or | |
1508 | @code{q-push!} with @code{q-pop!}. | |
1509 | @end deffn | |
1510 | ||
1511 | @deffn {Scheme Procedure} q-push! q obj | |
1512 | Add @var{obj} to the front of @var{q}, and return @var{q}. | |
1513 | @end deffn | |
1514 | ||
1515 | @deffn {Scheme Procedure} q-length q | |
1516 | Return the number of elements in @var{q}. | |
1517 | @end deffn | |
1518 | ||
1519 | @deffn {Scheme Procedure} q-empty? q | |
1520 | Return true if @var{q} is empty. | |
1521 | @end deffn | |
1522 | ||
1523 | @deffn {Scheme Procedure} q-empty-check q | |
1524 | Throw a @code{q-empty} exception if @var{q} is empty. | |
1525 | @end deffn | |
1526 | ||
1527 | @deffn {Scheme Procedure} q-front q | |
1528 | Return the first element of @var{q} (without removing it). If @var{q} | |
1529 | is empty, a @code{q-empty} exception is thrown. | |
1530 | @end deffn | |
1531 | ||
1532 | @deffn {Scheme Procedure} q-rear q | |
1533 | Return the last element of @var{q} (without removing it). If @var{q} | |
1534 | is empty, a @code{q-empty} exception is thrown. | |
1535 | @end deffn | |
1536 | ||
1537 | @deffn {Scheme Procedure} q-remove! q obj | |
72b3aa56 | 1538 | Remove all occurrences of @var{obj} from @var{q}, and return @var{q}. |
2370f809 KR |
1539 | @var{obj} is compared to queue elements using @code{eq?}. |
1540 | @end deffn | |
1541 | ||
1542 | @sp 1 | |
1543 | @cindex @code{q-empty} | |
1544 | The @code{q-empty} exceptions described above are thrown just as | |
1545 | @code{(throw 'q-empty)}, there's no message etc like an error throw. | |
1546 | ||
1547 | A queue is implemented as a cons cell, the @code{car} containing a | |
1548 | list of queued elements, and the @code{cdr} being the last cell in | |
1549 | that list (for ease of enqueuing). | |
1550 | ||
1551 | @example | |
1552 | (@var{list} . @var{last-cell}) | |
1553 | @end example | |
1554 | ||
1555 | @noindent | |
1556 | If the queue is empty, @var{list} is the empty list and | |
1557 | @var{last-cell} is @code{#f}. | |
1558 | ||
1559 | An application can directly access the queue list if desired, for | |
1560 | instance to search the elements or to insert at a specific point. | |
1561 | ||
1562 | @deffn {Scheme Procedure} sync-q! q | |
1563 | Recompute the @var{last-cell} field in @var{q}. | |
1564 | ||
1565 | All the operations above maintain @var{last-cell} as described, so | |
1566 | normally there's no need for @code{sync-q!}. But if an application | |
1567 | modifies the queue @var{list} then it must either maintain | |
1568 | @var{last-cell} similarly, or call @code{sync-q!} to recompute it. | |
1569 | @end deffn | |
1570 | ||
1571 | ||
458dd501 KR |
1572 | @node Streams |
1573 | @section Streams | |
1574 | @cindex streams | |
1575 | ||
80b809f1 MW |
1576 | This section documents Guile's legacy stream module. For a more |
1577 | complete and portable stream library, @pxref{SRFI-41}. | |
1578 | ||
458dd501 KR |
1579 | A stream represents a sequence of values, each of which is calculated |
1580 | only when required. This allows large or even infinite sequences to | |
1581 | be represented and manipulated with familiar operations like ``car'', | |
1582 | ``cdr'', ``map'' or ``fold''. In such manipulations only as much as | |
1583 | needed is actually held in memory at any one time. The functions in | |
1584 | this section are available from | |
1585 | ||
1586 | @example | |
1587 | (use-modules (ice-9 streams)) | |
1588 | @end example | |
1589 | ||
1590 | Streams are implemented using promises (@pxref{Delayed Evaluation}), | |
1591 | which is how the underlying calculation of values is made only when | |
1592 | needed, and the values then retained so the calculation is not | |
1593 | repeated. | |
1594 | ||
1595 | @noindent | |
1596 | Here is a simple example producing a stream of all odd numbers, | |
1597 | ||
1598 | @example | |
1599 | (define odds (make-stream (lambda (state) | |
1600 | (cons state (+ state 2))) | |
1601 | 1)) | |
1602 | (stream-car odds) @result{} 1 | |
1603 | (stream-car (stream-cdr odds)) @result{} 3 | |
1604 | @end example | |
1605 | ||
1606 | @noindent | |
1607 | @code{stream-map} could be used to derive a stream of odd squares, | |
1608 | ||
1609 | @example | |
1610 | (define (square n) (* n n)) | |
1611 | (define oddsquares (stream-map square odds)) | |
1612 | @end example | |
1613 | ||
1614 | These are infinite sequences, so it's not possible to convert them to | |
1615 | a list, but they could be printed (infinitely) with for example | |
1616 | ||
1617 | @example | |
1618 | (stream-for-each (lambda (n sq) | |
1619 | (format #t "~a squared is ~a\n" n sq)) | |
1620 | odds oddsquares) | |
1621 | @print{} | |
1622 | 1 squared is 1 | |
1623 | 3 squared is 9 | |
1624 | 5 squared is 25 | |
1625 | 7 squared is 49 | |
1626 | @dots{} | |
1627 | @end example | |
1628 | ||
1629 | @sp 1 | |
7948c5d9 | 1630 | @deffn {Scheme Procedure} make-stream proc initial-state |
458dd501 KR |
1631 | Return a new stream, formed by calling @var{proc} successively. |
1632 | ||
1633 | Each call is @code{(@var{proc} @var{state})}, it should return a pair, | |
1634 | the @code{car} being the value for the stream, and the @code{cdr} | |
1635 | being the new @var{state} for the next call. For the first call | |
1636 | @var{state} is the given @var{initial-state}. At the end of the | |
1637 | stream, @var{proc} should return some non-pair object. | |
7948c5d9 | 1638 | @end deffn |
458dd501 | 1639 | |
7948c5d9 | 1640 | @deffn {Scheme Procedure} stream-car stream |
458dd501 KR |
1641 | Return the first element from @var{stream}. @var{stream} must not be |
1642 | empty. | |
7948c5d9 | 1643 | @end deffn |
458dd501 | 1644 | |
7948c5d9 | 1645 | @deffn {Scheme Procedure} stream-cdr stream |
458dd501 KR |
1646 | Return a stream which is the second and subsequent elements of |
1647 | @var{stream}. @var{stream} must not be empty. | |
7948c5d9 | 1648 | @end deffn |
458dd501 | 1649 | |
7948c5d9 | 1650 | @deffn {Scheme Procedure} stream-null? stream |
458dd501 | 1651 | Return true if @var{stream} is empty. |
7948c5d9 | 1652 | @end deffn |
458dd501 | 1653 | |
7948c5d9 LC |
1654 | @deffn {Scheme Procedure} list->stream list |
1655 | @deffnx {Scheme Procedure} vector->stream vector | |
458dd501 KR |
1656 | Return a stream with the contents of @var{list} or @var{vector}. |
1657 | ||
1658 | @var{list} or @var{vector} should not be modified subsequently, since | |
1659 | it's unspecified whether changes there will be reflected in the stream | |
1660 | returned. | |
7948c5d9 | 1661 | @end deffn |
458dd501 | 1662 | |
7948c5d9 | 1663 | @deffn {Scheme Procedure} port->stream port readproc |
458dd501 KR |
1664 | Return a stream which is the values obtained by reading from |
1665 | @var{port} using @var{readproc}. Each read call is | |
1666 | @code{(@var{readproc} @var{port})}, and it should return an EOF object | |
1667 | (@pxref{Reading}) at the end of input. | |
1668 | ||
1669 | For example a stream of characters from a file, | |
1670 | ||
1671 | @example | |
1672 | (port->stream (open-input-file "/foo/bar.txt") read-char) | |
1673 | @end example | |
7948c5d9 | 1674 | @end deffn |
458dd501 | 1675 | |
7948c5d9 | 1676 | @deffn {Scheme Procedure} stream->list stream |
458dd501 | 1677 | Return a list which is the entire contents of @var{stream}. |
7948c5d9 | 1678 | @end deffn |
458dd501 | 1679 | |
7948c5d9 | 1680 | @deffn {Scheme Procedure} stream->reversed-list stream |
458dd501 KR |
1681 | Return a list which is the entire contents of @var{stream}, but in |
1682 | reverse order. | |
7948c5d9 | 1683 | @end deffn |
458dd501 | 1684 | |
7948c5d9 | 1685 | @deffn {Scheme Procedure} stream->list&length stream |
5179b0e2 KR |
1686 | Return two values (@pxref{Multiple Values}), being firstly a list |
1687 | which is the entire contents of @var{stream}, and secondly the number | |
1688 | of elements in that list. | |
7948c5d9 | 1689 | @end deffn |
458dd501 | 1690 | |
7948c5d9 | 1691 | @deffn {Scheme Procedure} stream->reversed-list&length stream |
5179b0e2 KR |
1692 | Return two values (@pxref{Multiple Values}) being firstly a list which |
1693 | is the entire contents of @var{stream}, but in reverse order, and | |
1694 | secondly the number of elements in that list. | |
7948c5d9 | 1695 | @end deffn |
458dd501 | 1696 | |
7948c5d9 | 1697 | @deffn {Scheme Procedure} stream->vector stream |
458dd501 | 1698 | Return a vector which is the entire contents of @var{stream}. |
7948c5d9 | 1699 | @end deffn |
458dd501 | 1700 | |
df0a1002 | 1701 | @defun stream-fold proc init stream1 stream2 @dots{} |
458dd501 KR |
1702 | Apply @var{proc} successively over the elements of the given streams, |
1703 | from first to last until the end of the shortest stream is reached. | |
1704 | Return the result from the last @var{proc} call. | |
1705 | ||
df0a1002 | 1706 | Each call is @code{(@var{proc} elem1 elem2 @dots{} prev)}, where each |
458dd501 KR |
1707 | @var{elem} is from the corresponding @var{stream}. @var{prev} is the |
1708 | return from the previous @var{proc} call, or the given @var{init} for | |
1709 | the first call. | |
df0a1002 | 1710 | @end defun |
458dd501 | 1711 | |
df0a1002 | 1712 | @defun stream-for-each proc stream1 stream2 @dots{} |
458dd501 KR |
1713 | Call @var{proc} on the elements from the given @var{stream}s. The |
1714 | return value is unspecified. | |
1715 | ||
df0a1002 | 1716 | Each call is @code{(@var{proc} elem1 elem2 @dots{})}, where each |
458dd501 KR |
1717 | @var{elem} is from the corresponding @var{stream}. |
1718 | @code{stream-for-each} stops when it reaches the end of the shortest | |
1719 | @var{stream}. | |
df0a1002 | 1720 | @end defun |
458dd501 | 1721 | |
df0a1002 | 1722 | @defun stream-map proc stream1 stream2 @dots{} |
458dd501 KR |
1723 | Return a new stream which is the results of applying @var{proc} to the |
1724 | elements of the given @var{stream}s. | |
1725 | ||
df0a1002 | 1726 | Each call is @code{(@var{proc} elem1 elem2 @dots{})}, where each |
458dd501 | 1727 | @var{elem} is from the corresponding @var{stream}. The new stream |
5179b0e2 | 1728 | ends when the end of the shortest given @var{stream} is reached. |
df0a1002 | 1729 | @end defun |
458dd501 KR |
1730 | |
1731 | ||
40296bab KR |
1732 | @node Buffered Input |
1733 | @section Buffered Input | |
1734 | @cindex Buffered input | |
1735 | @cindex Line continuation | |
1736 | ||
1737 | The following functions are provided by | |
1738 | ||
1739 | @example | |
1740 | (use-modules (ice-9 buffered-input)) | |
1741 | @end example | |
1742 | ||
1743 | A buffered input port allows a reader function to return chunks of | |
1744 | characters which are to be handed out on reading the port. A notion | |
1745 | of further input for an application level logical expression is | |
1746 | maintained too, and passed through to the reader. | |
1747 | ||
7948c5d9 | 1748 | @deffn {Scheme Procedure} make-buffered-input-port reader |
40296bab KR |
1749 | Create an input port which returns characters obtained from the given |
1750 | @var{reader} function. @var{reader} is called (@var{reader} cont), | |
1751 | and should return a string or an EOF object. | |
1752 | ||
1753 | The new port gives precisely the characters returned by @var{reader}, | |
1754 | nothing is added, so if any newline characters or other separators are | |
1755 | desired they must come from the reader function. | |
1756 | ||
1757 | The @var{cont} parameter to @var{reader} is @code{#f} for initial | |
1758 | input, or @code{#t} when continuing an expression. This is an | |
1759 | application level notion, set with | |
1760 | @code{set-buffered-input-continuation?!} below. If the user has | |
1761 | entered a partial expression then it allows @var{reader} for instance | |
1762 | to give a different prompt to show more is required. | |
7948c5d9 | 1763 | @end deffn |
40296bab | 1764 | |
7948c5d9 | 1765 | @deffn {Scheme Procedure} make-line-buffered-input-port reader |
40296bab KR |
1766 | @cindex Line buffered input |
1767 | Create an input port which returns characters obtained from the | |
1768 | specified @var{reader} function, similar to | |
1769 | @code{make-buffered-input-port} above, but where @var{reader} is | |
1770 | expected to be a line-oriented. | |
1771 | ||
1772 | @var{reader} is called (@var{reader} cont), and should return a string | |
1773 | or an EOF object as above. Each string is a line of input without a | |
1774 | newline character, the port code inserts a newline after each string. | |
7948c5d9 | 1775 | @end deffn |
40296bab | 1776 | |
7948c5d9 | 1777 | @deffn {Scheme Procedure} set-buffered-input-continuation?! port cont |
40296bab KR |
1778 | Set the input continuation flag for a given buffered input |
1779 | @var{port}. | |
1780 | ||
1781 | An application uses this by calling with a @var{cont} flag of | |
1782 | @code{#f} when beginning to read a new logical expression. For | |
1783 | example with the Scheme @code{read} function (@pxref{Scheme Read}), | |
1784 | ||
1785 | @example | |
1786 | (define my-port (make-buffered-input-port my-reader)) | |
1787 | ||
1788 | (set-buffered-input-continuation?! my-port #f) | |
1789 | (let ((obj (read my-port))) | |
1790 | ... | |
1791 | @end example | |
7948c5d9 | 1792 | @end deffn |
40296bab KR |
1793 | |
1794 | ||
a0e07ba4 NJ |
1795 | @c Local Variables: |
1796 | @c TeX-master: "guile.texi" | |
1797 | @c End: |