Commit | Line | Data |
---|---|---|
2da09c3f MV |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004 | |
4 | @c Free Software Foundation, Inc. | |
5 | @c See the file guile.texi for copying conditions. | |
6 | ||
a0e07ba4 NJ |
7 | @page |
8 | @node Pretty Printing | |
3229f68b | 9 | @section Pretty Printing |
a0e07ba4 NJ |
10 | |
11 | @c FIXME::martin: Review me! | |
12 | ||
13 | @cindex pretty printing | |
14 | The module @code{(ice-9 pretty-print)} provides the procedure | |
15 | @code{pretty-print}, which provides nicely formatted output of Scheme | |
16 | objects. This is especially useful for deeply nested or complex data | |
17 | structures, such as lists and vectors. | |
18 | ||
19 | The module is loaded by simply saying. | |
20 | ||
21 | @lisp | |
22 | (use-modules (ice-9 pretty-print)) | |
23 | @end lisp | |
24 | ||
25 | This makes the procedure @code{pretty-print} available. As an example | |
26 | how @code{pretty-print} will format the output, see the following: | |
27 | ||
28 | @lisp | |
29 | (pretty-print '(define (foo) (lambda (x) | |
385dbc8b KR |
30 | (cond ((zero? x) #t) ((negative? x) -x) (else |
31 | (if (= x 1) 2 (* x x x))))))) | |
a0e07ba4 NJ |
32 | @print{} |
33 | (define (foo) | |
34 | (lambda (x) | |
35 | (cond ((zero? x) #t) | |
36 | ((negative? x) -x) | |
37 | (else (if (= x 1) 2 (* x x x)))))) | |
38 | @end lisp | |
39 | ||
385dbc8b | 40 | @deffn {Scheme Procedure} pretty-print obj [port] [keyword-options] |
a0e07ba4 NJ |
41 | Print the textual representation of the Scheme object @var{obj} to |
42 | @var{port}. @var{port} defaults to the current output port, if not | |
43 | given. | |
385dbc8b KR |
44 | |
45 | The further @var{keyword-options} are keywords and parameters as | |
46 | follows, | |
47 | ||
48 | @table @asis | |
49 | @item @nicode{#:display?} @var{flag} | |
50 | If @var{flag} is true then print using @code{display}. The default is | |
51 | @code{#f} which means use @code{write} style. (@pxref{Writing}) | |
52 | ||
53 | @item @nicode{#:per-line-prefix} @var{string} | |
54 | Print the given @var{string} as a prefix on each line. The default is | |
55 | no prefix. | |
56 | ||
57 | @item @nicode{#:width} @var{columns} | |
58 | Print within the given @var{columns}. The default is 79. | |
59 | @end table | |
a0e07ba4 NJ |
60 | @end deffn |
61 | ||
62 | Beware: Since @code{pretty-print} uses it's own write procedure, it's | |
63 | output will not be the same as for example the output of @code{write}. | |
64 | Consider the following example. | |
65 | ||
66 | @lisp | |
67 | (write (lambda (x) x)) | |
68 | @print{} | |
69 | #<procedure #f (x)> | |
70 | ||
71 | (pretty-print (lambda (x) x)) | |
72 | @print{} | |
73 | #[procedure] | |
74 | @end lisp | |
75 | ||
76 | The reason is that @code{pretty-print} does not know as much about | |
77 | Guile's object types as the builtin procedures. This is particularly | |
78 | important for smobs, for which a write procedure can be defined and be | |
79 | used by @code{write}, but not by @code{pretty-print}. | |
80 | ||
2a946b44 | 81 | |
a0e07ba4 NJ |
82 | @page |
83 | @node Formatted Output | |
3229f68b | 84 | @section Formatted Output |
a0e07ba4 | 85 | @cindex formatted output |
a0e07ba4 | 86 | |
76d3f3d4 KR |
87 | @c For reference, in this section escapes like ~a are given in |
88 | @c @nicode, to give code font in TeX etc, but leave them unadorned in | |
89 | @c Info. | |
90 | @c | |
91 | @c The idea is to reduce clutter around what's shown, and avoid any | |
92 | @c possible confusion over whether the ` ' quotes are part of what | |
93 | @c should be entered. (In particular for instance of course ' is | |
94 | @c meaningful in a format string, introducing a char parameter). | |
95 | ||
96 | The @code{format} function is a powerful way to print numbers, strings | |
97 | and other objects together with literal text under the control of a | |
98 | format string. This function is available from | |
99 | ||
100 | @example | |
101 | (use-modules (ice-9 format)) | |
102 | @end example | |
103 | ||
104 | A format string is generally more compact and easier than using just | |
105 | the standard procedures like @code{display}, @code{write} and | |
106 | @code{newline}. Parameters in the output string allow various output | |
107 | styles, and parameters can be taken from the arguments for runtime | |
108 | flexibility. | |
109 | ||
110 | @code{format} is similar to the Common Lisp procedure of the same | |
111 | name, but it's not identical and doesn't have quite all the features | |
112 | found in Common Lisp. | |
113 | ||
114 | C programmers will note the similarity between @code{format} and | |
115 | @code{printf}, though escape sequences are marked with @nicode{~} | |
116 | instead of @nicode{%}, and are more powerful. | |
117 | ||
118 | @sp 1 | |
119 | @deffn {Scheme Procedure} format dest fmt [args@dots{}] | |
120 | Write output specified by the @var{fmt} string to @var{dest}. | |
121 | @var{dest} can be an output port, @code{#t} for | |
122 | @code{current-output-port} (@pxref{Default Ports}), a number for | |
123 | @code{current-error-port}, or @code{#f} to return the output as a | |
124 | string. | |
125 | ||
126 | @var{fmt} can contain literal text to be output, and @nicode{~} | |
127 | escapes. Each escape has the form | |
128 | ||
129 | @example | |
130 | ~ [param [, param@dots{}] [:] [@@] code | |
131 | @end example | |
132 | ||
133 | @nicode{code} is a character determining the escape sequence. The | |
134 | @nicode{:} and @nicode{@@} characters are optional modifiers, one or | |
135 | both of which change the way various codes operate. Optional | |
136 | parameters are accepted by some codes too. Parameters have the | |
137 | following forms, | |
a0e07ba4 | 138 | |
76d3f3d4 KR |
139 | @table @asis |
140 | @item @nicode{[+/-] number} | |
141 | An integer, with optional @nicode{+} or @nicode{-}. | |
142 | @item @nicode{'} (apostrophe) | |
143 | The following character in the format string, for instance @nicode{'z} | |
144 | for @nicode{z}. | |
145 | @item @nicode{v} | |
146 | The next function argument as the parameter. @nicode{v} stands for | |
147 | ``variable'', a parameter can be calculated at runtime and included in | |
148 | the arguments. Upper case @nicode{V} can be used too. | |
149 | @item @nicode{#} | |
150 | The number of arguments remaining. (See @nicode{~*} below for some | |
151 | usages.) | |
a0e07ba4 NJ |
152 | @end table |
153 | ||
76d3f3d4 KR |
154 | Parameters are separated by commas (@nicode{,}). A parameter can be |
155 | left empty to keep its default value when supplying later parameters. | |
a0e07ba4 | 156 | |
76d3f3d4 KR |
157 | @sp 1 |
158 | The following escapes are available. The code letters are not | |
159 | case-sensitive, upper and lower case are the same. | |
a0e07ba4 | 160 | |
76d3f3d4 KR |
161 | @table @asis |
162 | @item @nicode{~a} | |
163 | @itemx @nicode{~s} | |
164 | Object output. Parameters: @var{minwidth}, @var{padinc}, | |
165 | @var{minpad}, @var{padchar}. | |
166 | ||
167 | @nicode{~a} outputs an argument like @code{display}, @nicode{~s} | |
168 | outputs an argument like @code{write} (@pxref{Writing}). | |
169 | ||
170 | @example | |
171 | (format #t "~a" "foo") @print{} foo | |
172 | (format #t "~s" "foo") @print{} "foo" | |
173 | @end example | |
174 | ||
175 | With the @nicode{:} modifier, objects which don't have an external | |
176 | representation are put in quotes like a string. | |
177 | ||
178 | @example | |
179 | (format #t "~:a" car) @print{} "#<primitive-procedure car>" | |
180 | @end example | |
181 | ||
182 | If the output is less than @var{minwidth} characters (default 0), it's | |
183 | padded on the right with @var{padchar} (default space). The | |
184 | @nicode{@@} modifier puts the padding on the left instead. | |
185 | ||
186 | @example | |
187 | (format #f "~5a" 'abc) @result{} "abc " | |
188 | (format #f "~5,,,'-@@a" 'abc) @result{} "--abc" | |
189 | @end example | |
190 | ||
191 | @var{minpad} is a minimum for the padding then plus a multiple of | |
192 | @var{padinc}. Ie.@: the padding is @math{@var{minpad} + @var{N} * | |
193 | @var{padinc}}, where @var{n} is the smallest integer making the total | |
194 | object plus padding greater than or equal to @var{minwidth}. The | |
195 | default @var{minpad} is 0 and the default @var{padinc} is 1 (imposing | |
196 | no minimum or multiple). | |
197 | ||
198 | @example | |
199 | (format #f "~5,1,4a" 'abc) @result{} "abc " | |
200 | @end example | |
201 | ||
202 | @item @nicode{~c} | |
203 | Character. Parameter: @var{charnum}. | |
204 | ||
205 | Output a character. The default is to simply output, as per | |
206 | @code{write-char} (@pxref{Writing}). With the @nicode{@@} modifier | |
207 | output is in @code{write} style. Or with the @nicode{:} modifier | |
208 | control characters (ASCII 0 to 31) are printed in @nicode{^X} form. | |
209 | ||
210 | @example | |
211 | (format #t "~c" #\z) @print{} z | |
212 | (format #t "~@@c" #\z) @print{} #\z | |
213 | (format #t "~:c" #\newline) @print{} ^J | |
214 | @end example | |
215 | ||
216 | If the @var{charnum} parameter is given then an argument is not taken | |
217 | but instead the character is @code{(integer->char @var{charnum})} | |
218 | (@pxref{Characters}). This can be used for instance to output | |
219 | characters given by their ASCII code. | |
220 | ||
221 | @example | |
222 | (format #t "~65c") @print{} A | |
223 | @end example | |
224 | ||
225 | @item @nicode{~d} | |
226 | @itemx @nicode{~x} | |
227 | @itemx @nicode{~o} | |
228 | @itemx @nicode{~b} | |
229 | Integer. Parameters: @var{minwidth}, @var{padchar}, @var{commachar}, | |
230 | @var{commawidth}. | |
231 | ||
232 | Output an integer argument as a decimal, hexadecimal, octal or binary | |
233 | integer (respectively). | |
234 | ||
235 | @example | |
236 | (format #t "~d" 123) @print{} 123 | |
237 | @end example | |
238 | ||
239 | With the @nicode{@@} modifier, a @nicode{+} sign is shown on positive | |
240 | numbers. | |
241 | ||
242 | @c FIXME: "+" is not shown on zero, unlike in Common Lisp. Should | |
243 | @c that be changed in the code, or is it too late and should just be | |
244 | @c documented that way? | |
245 | ||
246 | @example | |
247 | (format #t "~@@b" 12) @print{} +1100 | |
248 | @end example | |
249 | ||
250 | If the output is less than the @var{minwidth} parameter (default no | |
251 | minimum), it's padded on the left with the @var{padchar} parameter | |
252 | (default space). | |
253 | ||
254 | @example | |
255 | (format #t "~5,'*d" 12) @print{} ***12 | |
256 | (format #t "~5,'0d" 12) @print{} 00012 | |
257 | (format #t "~3d" 1234) @print{} 1234 | |
258 | @end example | |
259 | ||
260 | The @nicode{:} modifier adds commas (or the @var{commachar} parameter) | |
261 | every three digits (or the @var{commawidth} parameter many). | |
262 | ||
263 | @example | |
264 | (format #t "~:d" 1234567) @print{} 1,234,567 | |
265 | (format #t "~10,'*,'/,2:d" 12345) @print{} ***1/23/45 | |
266 | @end example | |
267 | ||
268 | Hexadecimal @nicode{~x} output is in lower case, but the @nicode{~(} | |
269 | and @nicode{~)} case conversion directives described below can be used | |
270 | to get upper case. | |
271 | ||
272 | @example | |
273 | (format #t "~x" 65261) @print{} feed | |
274 | (format #t "~:@@(~x~)" 65261) @print{} FEED | |
275 | @end example | |
276 | ||
277 | @item @nicode{~r} | |
278 | Integer in words, roman numerals, or a specified radix. Parameters: | |
279 | @var{radix}, @var{minwidth}, @var{padchar}, @var{commachar}, | |
280 | @var{commawidth}. | |
281 | ||
282 | With no parameters output is in words as a cardinal like ``ten'', or | |
283 | with the @nicode{:} modifier as an ordinal like ``tenth''. | |
284 | ||
285 | @example | |
286 | (format #t "~r" 9) @print{} nine ;; cardinal | |
287 | (format #t "~r" -9) @print{} minus nine ;; cardinal | |
288 | (format #t "~:r" 9) @print{} ninth ;; ordinal | |
289 | @end example | |
290 | ||
291 | And also with no parameters, the @nicode{@@} modifier gives roman | |
292 | numerals and @nicode{@@} and @nicode{:} together give old roman | |
293 | numerals. In old roman numerals there's no ``subtraction'', so 9 is | |
294 | @nicode{VIIII} instead of @nicode{IX}. In both cases only positive | |
295 | numbers can be output. | |
296 | ||
297 | @example | |
298 | (format #t "~@@r" 89) @print{} LXXXIX ;; roman | |
299 | (format #t "~@@:r" 89) @print{} LXXXVIIII ;; old roman | |
300 | @end example | |
301 | ||
302 | When a parameter is given it means numeric output in the specified | |
303 | @var{radix}. The modifiers and parameters following the radix are the | |
304 | same as described for @nicode{~d} etc above. | |
305 | ||
306 | @example | |
307 | (format #f "~3r" 27) @result{} "1000" ;; base 3 | |
308 | (format #f "~3,5r" 26) @result{} " 222" ;; base 3 width 5 | |
309 | @end example | |
310 | ||
311 | @item @nicode{~f} | |
312 | Fixed-point float. Parameters: @var{width}, @var{decimals}, | |
313 | @var{scale}, @var{overflowchar}, @var{padchar}. | |
314 | ||
315 | Output a number or number string in fixed-point format, ie.@: with a | |
316 | decimal point. | |
317 | ||
318 | @example | |
319 | (format #t "~f" 5) @print{} 5.0 | |
320 | (format #t "~f" "123") @print{} 123.0 | |
321 | (format #t "~f" "1e-1") @print{} 0.1 | |
322 | @end example | |
323 | ||
324 | With the @nicode{@@} modifier a @nicode{+} sign is shown on positive | |
325 | numbers (including zero). | |
326 | ||
327 | @example | |
328 | (format #t "~@@f" 0) @print{} +0.0 | |
329 | @end example | |
330 | ||
331 | If the output is less than @var{width} characters it's padded on the | |
332 | left with @var{padchar} (space by default). If the output equals or | |
333 | exceeds @var{width} then there's no padding. The default for | |
334 | @var{width} is no padding. | |
335 | ||
336 | @example | |
337 | (format #f "~6f" -1.5) @result{} " -1.5" | |
338 | (format #f "~6,,,,'*f" 23) @result{} "**23.0" | |
339 | (format #f "~6f" 1234567.0) @result{} "1234567.0" | |
340 | @end example | |
341 | ||
342 | @var{decimals} is how many digits to print after the decimal point, | |
343 | with the value rounded or padded with zeros as necessary. (The | |
344 | default is to output as many decimals as required.) | |
345 | ||
346 | @example | |
347 | (format #t "~1,2f" 3.125) @print{} 3.13 | |
348 | (format #t "~1,2f" 1.5) @print{} 1.50 | |
349 | @end example | |
350 | ||
351 | @var{scale} is a power of 10 applied to the value, moving the decimal | |
352 | point that many places. A positive @var{scale} increases the value | |
353 | shown, a negative decreases it. | |
354 | ||
355 | @example | |
356 | (format #t "~,,2f" 1234) @print{} 123400.0 | |
357 | (format #t "~,,-2f" 1234) @print{} 12.34 | |
358 | @end example | |
359 | ||
360 | If @var{overflowchar} and @var{width} are both given and if the output | |
361 | would exceed @var{width}, then that many @var{overflowchar}s are | |
362 | printed instead of the value. | |
363 | ||
364 | @example | |
365 | (format #t "~5,,,'xf" 12345) @print{} 12345 | |
366 | (format #t "~4,,,'xf" 12345) @print{} xxxx | |
367 | @end example | |
368 | ||
369 | @item @nicode{~e} | |
370 | Exponential float. Parameters: @var{width}, @var{mantdigits}, | |
371 | @var{expdigits}, @var{intdigits}, @var{overflowchar}, @var{padchar}, | |
372 | @var{expchar}. | |
373 | ||
374 | Output a number or number string in exponential notation. | |
375 | ||
376 | @example | |
377 | (format #t "~e" 5000.25) @print{} 5.00025E+3 | |
378 | (format #t "~e" "123.4") @print{} 1.234E+2 | |
379 | (format #t "~e" "1e4") @print{} 1.0E+4 | |
380 | @end example | |
381 | ||
382 | With the @nicode{@@} modifier a @nicode{+} sign is shown on positive | |
383 | numbers (including zero). (This is for the mantissa, a @nicode{+} or | |
384 | @nicode{-} sign is always shown on the exponent.) | |
385 | ||
386 | @example | |
387 | (format #t "~@@e" 5000.0) @print{} +5.0E+3 | |
388 | @end example | |
389 | ||
390 | If the output is less than @var{width} characters it's padded on the | |
391 | left with @var{padchar} (space by default). The default for | |
392 | @var{width} is to output with no padding. | |
393 | ||
394 | @example | |
395 | (format #f "~10e" 1234.0) @result{} " 1.234E+3" | |
396 | (format #f "~10,,,,,'*e" 0.5) @result{} "****5.0E-1" | |
397 | @end example | |
398 | ||
399 | @c FIXME: Describe what happens when the number is bigger than WIDTH. | |
400 | @c There seems to be a bit of dodginess about this, or some deviation | |
401 | @c from Common Lisp. | |
402 | ||
403 | @var{mantdigits} is the number of digits shown in the mantissa after | |
404 | the decimal point. The value is rounded or trailing zeros are added | |
405 | as necessary. The default @var{mantdigits} is to show as much as | |
406 | needed by the value. | |
407 | ||
408 | @example | |
409 | (format #f "~,3e" 11111.0) @result{} "1.111E+4" | |
410 | (format #f "~,8e" 123.0) @result{} "1.23000000E+2" | |
411 | @end example | |
412 | ||
413 | @var{expdigits} is the minimum number of digits shown for the | |
414 | exponent, with leading zeros added if necessary. The default for | |
415 | @var{expdigits} is to show only as many digits as required. At least | |
416 | 1 digit is always shown. | |
417 | ||
418 | @example | |
419 | (format #f "~,,1e" 1.0e99) @result{} "1.0E+99" | |
420 | (format #f "~,,6e" 1.0e99) @result{} "1.0E+000099" | |
421 | @end example | |
422 | ||
423 | @var{intdigits} (default 1) is the number of digits to show before the | |
424 | decimal point in the mantissa. @var{intdigits} can be zero, in which | |
425 | case the integer part is a single @nicode{0}, or it can be negative, | |
426 | in which case leading zeros are shown after the decimal point. | |
427 | ||
428 | @c FIXME: When INTDIGITS is 0, Common Lisp format apparently only | |
429 | @c shows the single 0 digit if it fits in WIDTH. format.scm seems to | |
430 | @c show it always. Is it meant to? | |
431 | ||
432 | @example | |
433 | (format #t "~,,,3e" 12345.0) @print{} 123.45E+2 | |
434 | (format #t "~,,,0e" 12345.0) @print{} 0.12345E+5 | |
435 | (format #t "~,,,-3e" 12345.0) @print{} 0.00012345E+8 | |
436 | @end example | |
437 | ||
438 | @c FIXME: MANTDIGITS with negative INTDIGITS doesn't match CL spec, | |
439 | @c believe the spec says it ought to still show mantdigits+1 sig | |
440 | @c figures, ie. leading zeros don't count towards MANTDIGITS, but it | |
441 | @c seems to just treat MANTDIGITS as how many digits after the | |
442 | @c decimal point. | |
443 | ||
444 | If @var{overflowchar} is given then @var{width} is a hard limit. If | |
445 | the output would exceed @var{width} then instead that many | |
446 | @var{overflowchar}s are printed. | |
447 | ||
448 | @example | |
449 | (format #f "~6,,,,'xe" 100.0) @result{} "1.0E+2" | |
450 | (format #f "~3,,,,'xe" 100.0) @result{} "xxx" | |
451 | @end example | |
452 | ||
453 | @var{expchar} is the exponent marker character (default @nicode{E}). | |
454 | ||
455 | @example | |
456 | (format #t "~,,,,,,'ee" 100.0) @print{} 1.0e+2 | |
457 | @end example | |
458 | ||
459 | @item @nicode{~g} | |
460 | General float. Parameters: @var{width}, @var{mantdigits}, | |
461 | @var{expdigits}, @var{intdigits}, @var{overflowchar}, @var{padchar}, | |
462 | @var{expchar}. | |
463 | ||
464 | Output a number or number string in either exponential format the same | |
465 | as @nicode{~e}, or fixed-point format like @nicode{~f} but aligned | |
466 | where the mantissa would have been and followed by padding where the | |
467 | exponent would have been. | |
468 | ||
469 | @c FIXME: The default MANTDIGITS is apparently max(needed,min(n,7)) | |
470 | @c where 10^(n-1)<=abs(x)<=10^n. But the Common Lisp spec seems to | |
471 | @c ask for "needed" to be without leading or trailing zeros, whereas | |
472 | @c format.scm seems to include trailing zeros, ending up with it | |
473 | @c using fixed format for bigger values than it should. | |
474 | ||
475 | Fixed-point is used when the absolute value is 0.1 or more and it | |
476 | takes no more space than the mantissa in exponential format, ie.@: | |
477 | basically up to @var{mantdigits} digits. | |
478 | ||
479 | @example | |
480 | (format #f "~12,4,2g" 999.0) @result{} " 999.0 " | |
481 | (format #f "~12,4,2g" "100000") @result{} " 1.0000E+05" | |
482 | @end example | |
483 | ||
484 | The parameters are interpreted as per @nicode{~e} above. When | |
485 | fixed-point is used, the @var{decimals} parameter to @nicode{~f} is | |
486 | established from @var{mantdigits}, so as to give a total | |
487 | @math{@var{mantdigits}+1} figures. | |
488 | ||
489 | @item @nicode{~$} | |
490 | Monetary style fixed-point float. Parameters: @var{decimals}, | |
491 | @var{intdigits}, @var{width}, @var{padchar}. | |
492 | ||
493 | @c For reference, fmtdoc.txi from past versions of slib showed the | |
494 | @c INTDIGITS parameter as SCALE. That looks like a typo, in the code | |
495 | @c and in the Common Lisp spec it's a minimum digits for the integer | |
496 | @c part, it isn't a power of 10 like in ~f. | |
497 | ||
498 | Output a number or number string in fixed-point format, ie.@: with a | |
499 | decimal point. @var{decimals} is the number of decimal places to | |
500 | show, default 2. | |
501 | ||
502 | @example | |
503 | (format #t "~$" 5) @print{} 5.00 | |
504 | (format #t "~4$" "2.25") @print{} 2.2500 | |
505 | (format #t "~4$" "1e-2") @print{} 0.0100 | |
506 | @end example | |
507 | ||
508 | With the @nicode{@@} modifier a @nicode{+} sign is shown on positive | |
509 | numbers (including zero). | |
510 | ||
511 | @example | |
512 | (format #t "~@@$" 0) @print{} +0.00 | |
513 | @end example | |
514 | ||
515 | @var{intdigits} is a minimum number of digits to show in the integer | |
516 | part of the value (default 1). | |
517 | ||
518 | @example | |
519 | (format #t "~,3$" 9.5) @print{} 009.50 | |
520 | (format #t "~,0$" 0.125) @print{} .13 | |
521 | @end example | |
522 | ||
523 | If the output is less than @var{width} characters (default 0), it's | |
524 | padded on the left with @var{padchar} (default space). With the | |
525 | @nicode{:} modifier the padding is output after the sign. | |
526 | ||
527 | @example | |
528 | (format #f "~,,8$" -1.5) @result{} " -1.50" | |
529 | (format #f "~,,8:$" -1.5) @result{} "- 1.50" | |
530 | (format #f "~,,8,'.@@:$" 3) @result{} "+...3.00" | |
531 | @end example | |
532 | ||
533 | Note that floating point for dollar amounts is generally not a good | |
534 | idea, because a cent @math{0.01} cannot be represented exactly in the | |
535 | binary floating point Guile uses, which leads to slowly accumulating | |
536 | rounding errors. Keeping values as cents (or fractions of a cent) in | |
537 | integers then printing with the scale option in @nicode{~f} may be a | |
538 | better approach. | |
539 | ||
540 | @c For reference, fractions don't work with ~$ (or any of the float | |
541 | @c conversions) currently. If they did work then we could perhaps | |
542 | @c suggest keeping dollar amounts as rationals, which would of course | |
543 | @c give exact cents. An integer as cents is probably still a better | |
544 | @c recommendation though, since it forces one to think about where | |
545 | @c and when rounding can or should occur. | |
546 | ||
547 | @item @nicode{~i} | |
548 | Complex fixed-point float. Parameters: @var{width}, @var{decimals}, | |
549 | @var{scale}, @var{overflowchar}, @var{padchar}. | |
550 | ||
551 | @c For reference, in Common Lisp ~i is an indent, but slib fmtdoc.txi | |
552 | @c described it as complex number output, so we keep that. | |
553 | ||
554 | Output the argument as a complex number, with both real and imaginary | |
555 | part shown (even if one or both are zero). | |
556 | ||
557 | The parameters and modifiers are the same as for fixed-point | |
558 | @nicode{~f} described above. The real and imaginary parts are both | |
559 | output with the same given parameters and modifiers, except that for | |
560 | the imaginary part the @nicode{@@} modifier is always enabled, so as | |
561 | to print a @nicode{+} sign between the real and imaginary parts. | |
562 | ||
563 | @example | |
564 | (format #t "~i" 1) @print{} 1.0+0.0i | |
565 | @end example | |
566 | ||
567 | @item @nicode{~p} | |
568 | Plural. No parameters. | |
569 | ||
570 | Output nothing if the argument is 1, or @samp{s} for any other | |
571 | value. | |
572 | ||
573 | @example | |
574 | (format #t "enter name~p" 1) @print{} enter name | |
575 | (format #t "enter name~p" 2) @print{} enter names | |
576 | @end example | |
577 | ||
578 | With the @nicode{@@} modifier, the output is @samp{y} for 1 or | |
579 | @samp{ies} otherwise. | |
580 | ||
581 | @example | |
582 | (format #t "pupp~@@p" 1) @print{} puppy | |
583 | (format #t "pupp~@@p" 2) @print{} puppies | |
584 | @end example | |
585 | ||
586 | The @nicode{:} modifier means re-use the preceding argument instead of | |
587 | taking a new one, which can be convenient when printing some sort of | |
588 | count. | |
589 | ||
590 | @example | |
591 | (format #t "~d cat~:p" 9) @print{} 9 cats | |
592 | @end example | |
593 | ||
594 | @item @nicode{~y} | |
595 | Pretty print. No parameters. | |
596 | ||
597 | Output an argument with @code{pretty-print} (@pxref{Pretty Printing}). | |
598 | ||
599 | @item @nicode{~?} | |
600 | @itemx @nicode{~k} | |
601 | Sub-format. No parameters. | |
602 | ||
603 | Take a format string argument and a second argument which is a list of | |
604 | arguments for it, and output the result. With the @nicode{@@} | |
605 | modifier, the arguments for the sub-format are taken directly rather | |
606 | than from a list. | |
607 | ||
608 | @example | |
609 | (format #t "~?" "~d ~d" '(1 2)) @print{} 1 2 | |
610 | (format #t "~@@? ~s" "~d ~d" 1 2 "foo") @print{} 1 2 "foo" | |
611 | @end example | |
612 | ||
613 | @nicode{~?} and @nicode{~k} are the same, @nicode{~k} is provided for | |
614 | T-Scheme compatibility. | |
615 | ||
616 | @item @nicode{~*} | |
617 | Argument jumping. Parameter: @var{N}. | |
618 | ||
619 | Move forward @var{N} arguments (default 1) in the argument list. With | |
620 | the @nicode{:} modifier move backwards. @var{N} can be negative to | |
621 | move backwards too. | |
a0e07ba4 | 622 | |
76d3f3d4 KR |
623 | @example |
624 | (format #f "~d ~:*~d" 6) @result{} "6 6" | |
625 | @end example | |
a0e07ba4 | 626 | |
76d3f3d4 KR |
627 | With the @nicode{@@} modifier, move to argument number @var{N}. The |
628 | first argument is number 0 (and that's the default for @var{N}). | |
a0e07ba4 | 629 | |
76d3f3d4 KR |
630 | @example |
631 | (format #f "~d~d again ~@@*~d~d" 1 2) @result{} "12 again 12" | |
632 | (format #f "~d~d~d ~1@@*~d~d" 1 2 3) @result{} "123 23" | |
633 | @end example | |
a0e07ba4 | 634 | |
76d3f3d4 KR |
635 | At the end of the format string the last argument must have been |
636 | consumed, or a ``too many arguments'' error results. If the last | |
637 | argument is not the last to be printed, then a move to skip the | |
638 | remaining must be given. This can be done with the @nicode{#} | |
639 | parameter (count of remaining arguments). | |
a0e07ba4 | 640 | |
76d3f3d4 KR |
641 | @example |
642 | (format #t "~2*~d" 1 2 3 4) ;; error | |
643 | (format #t "~2*~d~#*" 1 2 3 4) @result{} 3 | |
644 | @end example | |
a0e07ba4 | 645 | |
76d3f3d4 KR |
646 | A @nicode{#} move to the end followed by a @nicode{:} modifier move |
647 | back can be used for an absolute position relative to the end of the | |
648 | argument list, a reverse of what the @nicode{@@} modifier does. | |
a0e07ba4 | 649 | |
76d3f3d4 KR |
650 | @item @nicode{~t} |
651 | Advance to a column position. Parameters: @var{colnum}, @var{colinc}, | |
652 | @var{padchar}. | |
a0e07ba4 | 653 | |
76d3f3d4 KR |
654 | Output @var{padchar} (space by default) to move to the given |
655 | @var{colnum} column. The start of the line is column 0, the default | |
656 | for @var{colnum} is 1. | |
a0e07ba4 | 657 | |
76d3f3d4 KR |
658 | @example |
659 | (format #f "~tX") @result{} " X" | |
660 | (format #f "~3tX") @result{} " X" | |
661 | @end example | |
a0e07ba4 | 662 | |
76d3f3d4 KR |
663 | If the current column is already past @var{colnum}, then the move is |
664 | to there plus a multiple of @var{colinc}, ie.@: column | |
665 | @math{@var{colnum} + @var{N} * @var{colinc}} for the smallest @var{N} | |
666 | which makes that value greater than or equal to the current column. | |
667 | The default @var{colinc} is 1 (which means no further move). | |
a0e07ba4 | 668 | |
76d3f3d4 KR |
669 | @example |
670 | (format #f "abcd~2,5,'.tx") @result{} "abcd...x" | |
671 | @end example | |
a0e07ba4 | 672 | |
76d3f3d4 KR |
673 | With the @nicode{@@} modifier, @var{colnum} is relative to the current |
674 | column. @var{colnum} many padding characters are output, then further | |
675 | padding to make the current column a multiple of @var{colinc}, if it | |
676 | isn't already so. | |
677 | ||
678 | @example | |
679 | (format #f "a~3,5'*@@tx") @result{} "a****x" | |
680 | @end example | |
681 | ||
682 | @item @nicode{~~} | |
683 | Tilde character. Parameter: @var{n}. | |
684 | ||
685 | Output a tilde character @nicode{~}, or @var{n} many if a parameter is | |
686 | given. Normally @nicode{~} introduces an escape sequence, @nicode{~~} | |
687 | is the way to output a literal tilde. | |
688 | ||
689 | @item @nicode{~%} | |
690 | Newline. Parameter: @var{n}. | |
691 | ||
692 | Output a newline character, or @var{n} many if a parameter is given. | |
693 | A newline (or a few newlines) can of course be output just by | |
694 | including them in the format string. | |
695 | ||
696 | @item @nicode{~&} | |
697 | Start a new line. Parameter: @var{n}. | |
698 | ||
699 | Output a newline if not already at the start of a line. With a | |
700 | parameter, output that many newlines, but with the first only if not | |
701 | already at the start of a line. So for instance 3 would be a newline | |
702 | if not already at the start of a line, and 2 further newlines. | |
703 | ||
704 | @item @nicode{~_} | |
705 | Space character. Parameter: @var{n}. | |
706 | ||
707 | @c For reference, in Common Lisp ~_ is a conditional newline, but | |
708 | @c slib fmtdoc.txi described it as a space, so we keep that. | |
709 | ||
710 | Output a space character, or @var{n} many if a parameter is given. | |
711 | ||
712 | With a variable parameter this is one way to insert runtime calculated | |
713 | padding (@nicode{~t} or the various field widths can do similar | |
714 | things). | |
715 | ||
716 | @example | |
717 | (format #f "~v_foo" 4) @result{} " foo" | |
718 | @end example | |
719 | ||
720 | @item @nicode{~/} | |
721 | Tab character. Parameter: @var{n}. | |
722 | ||
723 | Output a tab character, or @var{n} many if a parameter is given. | |
724 | ||
725 | @item @nicode{~|} | |
726 | Formfeed character. Parameter: @var{n}. | |
727 | ||
728 | Output a formfeed character, or @var{n} many if a parameter is given. | |
729 | ||
730 | @item @nicode{~!} | |
731 | Force output. No parameters. | |
732 | ||
733 | At the end of output, call @code{force-output} to flush any buffers on | |
734 | the destination (@pxref{Writing}). @nicode{~!} can occur anywhere in | |
735 | the format string, but the force is done at the end of output. | |
736 | ||
737 | When output is to a string (destination @code{#f}), @nicode{~!} does | |
738 | nothing. | |
739 | ||
740 | @item @nicode{~newline} (ie.@: newline character) | |
741 | Continuation line. No parameters. | |
742 | ||
743 | Skip this newline and any following whitespace in the format string, | |
744 | don't send it to the output. With the @nicode{:} modifier the newline | |
745 | is not output but any further following whitespace is. With the | |
746 | @nicode{@@} modifier the newline is output but not any following | |
747 | whitespace. | |
748 | ||
749 | This escape can be used to break up a long format string into multiple | |
750 | lines for readability, but supress that extra whitespace. | |
751 | ||
752 | @example | |
753 | (format #f "abc~ | |
754 | ~d def~ | |
755 | ~d" 1 2) @result{} "abc1 def2" | |
756 | @end example | |
757 | ||
758 | @item @nicode{~(} @nicode{~)} | |
759 | Case conversion. Between @nicode{~(} and @nicode{~)} the case of all | |
760 | output is changed. The modifiers on @nicode{~(} control the | |
761 | conversion. | |
762 | ||
763 | @itemize @w | |
764 | @item | |
765 | no modifiers --- lower case. | |
766 | @c | |
767 | @c FIXME: The : and @ modifiers are not yet documented because the | |
768 | @c code applies string-capitalize and string-capitalize-first to each | |
769 | @c separate format:out-str call, which has various subtly doubtful | |
770 | @c effects. And worse they're applied to individual characters, | |
771 | @c including literal characters in the format string, which has the | |
772 | @c silly effect of being always an upcase. | |
773 | @c | |
774 | @c The Common Lisp spec is apparently for the capitalization to be | |
775 | @c applied in one hit to the whole of the output between ~( and ~). | |
776 | @c (This can no doubt be implemented without accumulating all that | |
777 | @c text, just by keeping a state or the previous char to tell whether | |
778 | @c within a word.) | |
779 | @c | |
780 | @c @item | |
781 | @c @nicode{:} --- first letter of each word upper case, the rest lower | |
782 | @c case, as per the @code{string-capitalize} function (@pxref{Alphabetic | |
783 | @c Case Mapping}). | |
784 | @c @item | |
785 | @c @nicode{@@} --- first letter of just the first word upper case, the | |
786 | @c rest lower case. | |
787 | @c | |
788 | @item | |
789 | @nicode{:} and @nicode{@@} together --- upper case. | |
790 | @end itemize | |
791 | ||
792 | For example, | |
793 | ||
794 | @example | |
795 | (format #t "~(Hello~)") @print{} hello | |
796 | (format #t "~@@:(Hello~)") @print{} HELLO | |
797 | @end example | |
798 | ||
799 | In the future it's intended the modifiers @nicode{:} and @nicode{@@} | |
800 | alone will capitalize the first letters of words, as per Common Lisp | |
801 | @code{format}, but the current implementation of this is flawed and | |
802 | not recommended for use. | |
803 | ||
804 | Case conversions do not nest, currently. This might change in the | |
805 | future, but if it does then it will be to Common Lisp style where the | |
806 | outermost conversion has priority, overriding inner ones (making those | |
807 | fairly pointless). | |
808 | ||
809 | @item @nicode{~@{} @nicode{~@}} | |
810 | Iteration. Parameter: @var{maxreps} (for @nicode{~@{}). | |
811 | ||
812 | The format between @nicode{~@{} and @nicode{~@}} is iterated. The | |
813 | modifiers to @nicode{~@{} determine how arguments are taken. The | |
814 | default is a list argument with each iteration successively consuming | |
815 | elements from it. This is a convenient way to output a whole list. | |
816 | ||
817 | @example | |
818 | (format #t "~@{~d~@}" '(1 2 3)) @print{} 123 | |
819 | (format #t "~@{~s=~d ~@}" '("x" 1 "y" 2)) @print{} "x"=1 "y"=2 | |
820 | @end example | |
821 | ||
822 | With the @nicode{:} modifier a list of lists argument is taken, each | |
823 | of those lists gives the arguments for the iterated format. | |
824 | ||
825 | @example | |
826 | (format #t "~:@{~dx~d ~@}" '((1 2) (3 4) (5 6))) @print{} 1x2 3x4 5x6 | |
827 | @end example | |
828 | ||
829 | With the @nicode{@@} modifier, the remaining arguments are used, each | |
830 | iteration successively consuming elements. | |
831 | ||
832 | @example | |
833 | (format #t "~@@@{~d~@}" 1 2 3) @print{} 123 | |
834 | (format #t "~@@@{~s=~d ~@}" "x" 1 "y" 2) @print{} "x"=1 "y"=2 | |
835 | @end example | |
836 | ||
837 | With both @nicode{:} and @nicode{@@} modifiers, the remaining | |
838 | arguments are used, each is a list of arguments for the format. | |
839 | ||
840 | @example | |
841 | (format #t "~:@@@{~dx~d ~@}" '(1 2) '(3 4) '(5 6)) @print{} 1x2 3x4 5x6 | |
842 | @end example | |
843 | ||
844 | Iterating stops when there are no more arguments or when the | |
845 | @var{maxreps} parameter to @nicode{~@{} is reached (default no | |
846 | maximum). | |
847 | ||
848 | @example | |
849 | (format #t "~2@{~d~@}" '(1 2 3 4)) @print{} 12 | |
850 | @end example | |
851 | ||
852 | If the format between @nicode{~@{} and @nicode{~@}} is empty, then a | |
853 | format string argument is taken (before iteration argument(s)) and | |
854 | used instead. This allows a sub-format (like @nicode{~?} above) to be | |
855 | iterated. | |
856 | ||
857 | @example | |
858 | (format #t "~@{~@}" "~d" '(1 2 3)) @print{} 123 | |
859 | @end example | |
860 | ||
861 | @c FIXME: What is the @nicode{:} modifier to ~} meant to do? The | |
862 | @c Common Lisp spec says it's a minimum of 1 iteration, but the | |
863 | @c format.scm code seems to merely make it have MAXREPS default to 1. | |
864 | ||
865 | Iterations can be nested, an inner iteration operates in the same way | |
866 | as described, but of course on the arguments the outer iteration | |
867 | provides it. This can be used to work into nested list structures. | |
868 | For example in the following the inner @nicode{~@{~d~@}x} is applied | |
869 | to @code{(1 2)} then @code{(3 4 5)} etc. | |
870 | ||
871 | @example | |
872 | (format #t "~@{~@{~d~@}x~@}" '((1 2) (3 4 5))) @print{} 12x345x | |
873 | @end example | |
874 | ||
875 | @item @nicode{~[} @nicode{~;} @nicode{~]} | |
876 | Conditional. Parameter: @var{selector}. | |
877 | ||
878 | A conditional block is delimited by @nicode{~[} and @nicode{~]}, and | |
879 | @nicode{~;} separates clauses within the block. @nicode{~[} takes an | |
880 | integer argument and that number clause is used. The first clause is | |
881 | number 0. | |
882 | ||
883 | @example | |
884 | (format #f "~[peach~;banana~;mango~]" 1) @result{} "banana" | |
885 | @end example | |
886 | ||
887 | The @var{selector} parameter can be used for the clause number, | |
888 | instead of taking an argument. | |
889 | ||
890 | @example | |
891 | (format #f "~2[peach~;banana~;mango~]") @result{} "mango" | |
892 | @end example | |
893 | ||
894 | If the clause number is out of range then nothing is output. Or the | |
895 | last @nicode{~;} can have a @nicode{:} modifier to make it the default | |
896 | for a number out of range. | |
897 | ||
898 | @example | |
899 | (format #f "~[banana~;mango~]" 99) @result{} "" | |
900 | (format #f "~[banana~;mango~:;fruit~]" 99) @result{} "fruit" | |
901 | @end example | |
902 | ||
903 | The @nicode{:} modifier to @nicode{~[} treats the argument as a flag, | |
904 | and expects two clauses. The first used if the argument is @code{#f} | |
905 | or the second otherwise. | |
906 | ||
907 | @example | |
908 | (format #f "~:[false~;not false~]" #f) @result{} "false" | |
909 | (format #f "~:[false~;not false~]" 'abc) @result{} "not false" | |
910 | ||
911 | (let ((n 3)) | |
912 | (format #t "~d gnu~:[s are~; is~] here" n (= 1 n))) | |
913 | @print{} 3 gnus are here | |
914 | @end example | |
915 | ||
916 | The @nicode{@@} modifier to @nicode{~[} also treats the argument as a | |
917 | flag, and expects one clause. If the argument is @code{#f} then no | |
918 | output is produced and the argument is consumed, otherwise the clause | |
919 | is used and the argument is not consumed by @nicode{~[}, it's left for | |
920 | the clause. This can be used for instance to suppress output if | |
921 | @code{#f} means something not available. | |
922 | ||
923 | @example | |
924 | (format #f "~@@[temperature=~d~]" 27) @result{} "temperature=27" | |
925 | (format #f "~@@[temperature=~d~]" #f) @result{} "" | |
926 | @end example | |
927 | ||
928 | @item @nicode{~^} | |
929 | Escape. Parameters: @var{val1}, @var{val2}, @var{val3}. | |
930 | ||
931 | Stop formatting if there are no more arguments. This can be used for | |
932 | instance to let a format string adapt to a variable number of | |
933 | arguments. | |
934 | ||
935 | @example | |
936 | (format #t "~d~^ ~d" 1) @print{} 1 | |
937 | (format #t "~d~^ ~d" 1 2) @print{} 1 2 | |
938 | @end example | |
939 | ||
940 | Within a @nicode{~@{} @nicode{~@}} iteration, @nicode{~^} stops the | |
941 | current iteration step if there are no more arguments to that step, | |
942 | continuing with possible further steps (for instance in the case of | |
943 | the @nicode{:} modifier to @nicode{~@{}) and the rest of the format. | |
944 | ||
945 | @example | |
946 | (format #f "~@{~d~^/~@} go" '(1 2 3)) @result{} "1/2/3 go" | |
947 | (format #f "~:@{ ~d~^~d~@} go" '((1) (2 3))) @result{} " 1 23 go" | |
948 | @end example | |
949 | ||
950 | @c For reference, format.scm doesn't implement that Common Lisp ~:^ | |
951 | @c modifier which stops the entire iterating of ~:{ or ~@:{. | |
952 | ||
953 | @c FIXME: Believe the Common Lisp spec is for ~^ within ~[ ~] | |
954 | @c conditional to terminate the whole format (or iteration step if in | |
955 | @c an iteration). But format.scm seems to terminate just the | |
956 | @c conditional form. | |
957 | @c | |
958 | @c (format #f "~[abc~^def~;ghi~] blah" 0) | |
959 | @c @result{} "abc blah" ;; looks wrong | |
960 | ||
961 | @c FIXME: Believe the Common Lisp spec is for ~^ within ~( ~) to end | |
962 | @c that case conversion and then also terminate the whole format (or | |
963 | @c iteration step if in an iteration). But format.scm doesn't seem | |
964 | @c to do that quite right. | |
965 | @c | |
966 | @c (format #f "~d ~^ ~d" 1) @result{} "1 " | |
967 | @c (format #f "~(~d ~^ ~d~)" 1) @result{} ERROR | |
968 | ||
969 | Within a @nicode{~?} sub-format, @nicode{~^} operates just on that | |
970 | sub-format. If it terminates the sub-format then the originating | |
971 | format will still continue. | |
972 | ||
973 | @example | |
974 | (format #t "~? items" "~d~^ ~d" '(1)) @print{} 1 items | |
975 | (format #t "~? items" "~d~^ ~d" '(1 2)) @print{} 1 2 items | |
976 | @end example | |
977 | ||
978 | The parameters to @nicode{~^} (which are numbers) change the condition | |
979 | used to terminate. For a single parameter, termination is when that | |
980 | value is zero (notice this makes plain @nicode{~^} equivalent to | |
981 | @nicode{~#^}). For two parameters, termination is when those two are | |
982 | equal. For three parameters, termination is when @math{@var{val1} | |
983 | @le{} @var{val2}} and @math{@var{val2} @le{} @var{val3}}. | |
984 | ||
985 | @c FIXME: Good examples of these? | |
986 | ||
987 | @item @nicode{~q} | |
988 | Inquiry message. Insert a copyright message into the output. With | |
989 | the @nicode{:} modifier insert the format implementation version. | |
a0e07ba4 NJ |
990 | @end table |
991 | ||
76d3f3d4 KR |
992 | @sp 1 |
993 | It's an error if there are too many or not enough arguments for the | |
994 | escapes in the format string. (Unwanted arguments can be skipped with | |
995 | an argument jump @nicode{~#*} described above if desired.) | |
996 | ||
997 | Iterations @nicode{~@{} @nicode{~@}} and conditionals @nicode{~[} | |
998 | @nicode{~;} @nicode{~]} can be nested, but must be properly nested, | |
999 | meaning the inner form must be entirely within the outer form. So | |
1000 | it's not possible, for instance, to try to conditionalize the endpoint | |
1001 | of an iteration. | |
1002 | ||
1003 | @example | |
1004 | (format #t "~@{ ~[ ... ~] ~@}" ...) ;; good | |
1005 | (format #t "~@{ ~[ ... ~@} ... ~]" ...) ;; bad | |
1006 | @end example | |
1007 | ||
1008 | The same applies to case conversions @nicode{~(} @nicode{~)}, they | |
1009 | must properly nest with respect to iterations and conditionals (though | |
1010 | currently a case conversion cannot nest within another case | |
1011 | conversion). | |
1012 | ||
1013 | When a sub-format (@nicode{~?}) is used, that sub-format string must | |
1014 | be self-contained. It cannot for instance give a @nicode{~@{} to | |
1015 | begin an iteration form and have the @nicode{~@}} up in the | |
1016 | originating format, or similar. | |
a0e07ba4 NJ |
1017 | @end deffn |
1018 | ||
76d3f3d4 KR |
1019 | @sp 1 |
1020 | Guile contains a @code{format} procedure even when the module | |
1021 | @code{(ice-9 format)} is not loaded. The default @code{format} is | |
1022 | @code{simple-format} (@pxref{Writing}), it doesn't support all escape | |
1023 | sequences documented in this section, and will signal an error if you | |
1024 | try to use one of them. The reason for two versions is that the full | |
1025 | @code{format} is fairly large and requires some time to load. | |
1026 | @code{simple-format} is often adequate too. | |
a0e07ba4 NJ |
1027 | |
1028 | ||
2a946b44 NJ |
1029 | @page |
1030 | @node Rx Regexps | |
3229f68b | 1031 | @section The Rx Regular Expression Library |
2a946b44 NJ |
1032 | |
1033 | [FIXME: this is taken from Gary and Mark's quick summaries and should be | |
1034 | reviewed and expanded. Rx is pretty stable, so could already be done!] | |
1035 | ||
1036 | @cindex rx | |
1037 | @cindex finite automaton | |
1038 | ||
1039 | The @file{guile-lang-allover} package provides an interface to Tom | |
1040 | Lord's Rx library (currently only to POSIX regular expressions). Use of | |
1041 | the library requires a two step process: compile a regular expression | |
1042 | into an efficient structure, then use the structure in any number of | |
1043 | string comparisons. | |
1044 | ||
1045 | For example, given the regular expression @samp{abc.} (which matches any | |
1046 | string containing @samp{abc} followed by any single character): | |
1047 | ||
1048 | @smalllisp | |
1049 | guile> @kbd{(define r (regcomp "abc."))} | |
1050 | guile> @kbd{r} | |
1051 | #<rgx abc.> | |
1052 | guile> @kbd{(regexec r "abc")} | |
1053 | #f | |
1054 | guile> @kbd{(regexec r "abcd")} | |
1055 | #((0 . 4)) | |
1056 | guile> | |
1057 | @end smalllisp | |
1058 | ||
1059 | The definitions of @code{regcomp} and @code{regexec} are as follows: | |
1060 | ||
1061 | @deffn {Scheme Procedure} regcomp pattern [flags] | |
1062 | Compile the regular expression pattern using POSIX rules. Flags is | |
1063 | optional and should be specified using symbolic names: | |
1064 | @defvar REG_EXTENDED | |
1065 | use extended POSIX syntax | |
1066 | @end defvar | |
1067 | @defvar REG_ICASE | |
1068 | use case-insensitive matching | |
1069 | @end defvar | |
1070 | @defvar REG_NEWLINE | |
1071 | allow anchors to match after newline characters in the | |
1072 | string and prevents @code{.} or @code{[^...]} from matching newlines. | |
1073 | @end defvar | |
1074 | ||
1075 | The @code{logior} procedure can be used to combine multiple flags. | |
1076 | The default is to use | |
1077 | POSIX basic syntax, which makes @code{+} and @code{?} literals and @code{\+} | |
1078 | and @code{\?} | |
1079 | operators. Backslashes in @var{pattern} must be escaped if specified in a | |
1080 | literal string e.g., @code{"\\(a\\)\\?"}. | |
1081 | @end deffn | |
1082 | ||
1083 | @deffn {Scheme Procedure} regexec regex string [match-pick] [flags] | |
1084 | Match @var{string} against the compiled POSIX regular expression | |
1085 | @var{regex}. | |
1086 | @var{match-pick} and @var{flags} are optional. Possible flags (which can be | |
1087 | combined using the logior procedure) are: | |
1088 | ||
1089 | @defvar REG_NOTBOL | |
1090 | The beginning of line operator won't match the beginning of | |
1091 | @var{string} (presumably because it's not the beginning of a line) | |
1092 | @end defvar | |
1093 | ||
1094 | @defvar REG_NOTEOL | |
1095 | Similar to REG_NOTBOL, but prevents the end of line operator | |
1096 | from matching the end of @var{string}. | |
1097 | @end defvar | |
1098 | ||
1099 | If no match is possible, regexec returns #f. Otherwise @var{match-pick} | |
1100 | determines the return value: | |
1101 | ||
1102 | @code{#t} or unspecified: a newly-allocated vector is returned, | |
1103 | containing pairs with the indices of the matched part of @var{string} and any | |
1104 | substrings. | |
1105 | ||
1106 | @code{""}: a list is returned: the first element contains a nested list | |
1107 | with the matched part of @var{string} surrounded by the the unmatched parts. | |
1108 | Remaining elements are matched substrings (if any). All returned | |
1109 | substrings share memory with @var{string}. | |
1110 | ||
1111 | @code{#f}: regexec returns #t if a match is made, otherwise #f. | |
1112 | ||
1113 | vector: the supplied vector is returned, with the first element replaced | |
1114 | by a pair containing the indices of the matched portion of @var{string} and | |
1115 | further elements replaced by pairs containing the indices of matched | |
1116 | substrings (if any). | |
1117 | ||
1118 | list: a list will be returned, with each member of the list | |
1119 | specified by a code in the corresponding position of the supplied list: | |
1120 | ||
1121 | a number: the numbered matching substring (0 for the entire match). | |
1122 | ||
1123 | @code{#\<}: the beginning of @var{string} to the beginning of the part matched | |
1124 | by regex. | |
1125 | ||
1126 | @code{#\>}: the end of the matched part of @var{string} to the end of | |
1127 | @var{string}. | |
1128 | ||
1129 | @code{#\c}: the "final tag", which seems to be associated with the "cut | |
1130 | operator", which doesn't seem to be available through the posix | |
1131 | interface. | |
1132 | ||
1133 | e.g., @code{(list #\< 0 1 #\>)}. The returned substrings share memory with | |
1134 | @var{string}. | |
1135 | @end deffn | |
1136 | ||
1137 | Here are some other procedures that might be used when using regular | |
1138 | expressions: | |
1139 | ||
1140 | @deffn {Scheme Procedure} compiled-regexp? obj | |
1141 | Test whether obj is a compiled regular expression. | |
1142 | @end deffn | |
1143 | ||
1144 | @deffn {Scheme Procedure} regexp->dfa regex [flags] | |
1145 | @end deffn | |
1146 | ||
1147 | @deffn {Scheme Procedure} dfa-fork dfa | |
1148 | @end deffn | |
1149 | ||
1150 | @deffn {Scheme Procedure} reset-dfa! dfa | |
1151 | @end deffn | |
1152 | ||
1153 | @deffn {Scheme Procedure} dfa-final-tag dfa | |
1154 | @end deffn | |
1155 | ||
1156 | @deffn {Scheme Procedure} dfa-continuable? dfa | |
1157 | @end deffn | |
1158 | ||
1159 | @deffn {Scheme Procedure} advance-dfa! dfa string | |
1160 | @end deffn | |
1161 | ||
1162 | ||
6da1534c | 1163 | @node File Tree Walk |
3229f68b | 1164 | @section File Tree Walk |
6da1534c KR |
1165 | @cindex file tree walk |
1166 | ||
1167 | The functions in this section traverse a tree of files and | |
1168 | directories, in a fashion similar to the C @code{ftw} and @code{nftw} | |
1169 | routines (@pxref{Working with Directory Trees,,, libc, GNU C Library | |
1170 | Reference Manual}). | |
1171 | ||
1172 | @example | |
1173 | (use-modules (ice-9 ftw)) | |
1174 | @end example | |
1175 | @sp 1 | |
1176 | ||
1177 | @defun ftw startname proc ['hash-size n] | |
1178 | Walk the filesystem tree descending from @var{startname}, calling | |
1179 | @var{proc} for each file and directory. | |
1180 | ||
1181 | Hard links and symbolic links are followed. A file or directory is | |
1182 | reported to @var{proc} only once, and skipped if seen again in another | |
1183 | place. One consequence of this is that @code{ftw} is safe against | |
1184 | circularly linked directory structures. | |
1185 | ||
1186 | Each @var{proc} call is @code{(@var{proc} filename statinfo flag)} and | |
1187 | it should return @code{#t} to continue, or any other value to stop. | |
1188 | ||
1189 | @var{filename} is the item visited, being @var{startname} plus a | |
1190 | further path and the name of the item. @var{statinfo} is the return | |
1191 | from @code{stat} (@pxref{File System}) on @var{filename}. @var{flag} | |
1192 | is one of the following symbols, | |
1193 | ||
1194 | @table @code | |
1195 | @item regular | |
1196 | @var{filename} is a file, this includes special files like devices, | |
1197 | named pipes, etc. | |
1198 | ||
1199 | @item directory | |
1200 | @var{filename} is a directory. | |
1201 | ||
1202 | @item invalid-stat | |
1203 | An error occurred when calling @code{stat}, so nothing is known. | |
1204 | @var{statinfo} is @code{#f} in this case. | |
1205 | ||
1206 | @item directory-not-readable | |
1207 | @var{filename} is a directory, but one which cannot be read and hence | |
1208 | won't be recursed into. | |
1209 | ||
1210 | @item symlink | |
1211 | @var{filename} is a dangling symbolic link. Symbolic links are | |
1212 | normally followed and their target reported, the link itself is | |
1213 | reported if the target does not exist. | |
1214 | @end table | |
1215 | ||
1216 | The return value from @code{ftw} is @code{#t} if it ran to completion, | |
1217 | or otherwise the non-@code{#t} value from @var{proc} which caused the | |
1218 | stop. | |
1219 | ||
1220 | Optional argument symbol @code{hash-size} and an integer can be given | |
1221 | to set the size of the hash table used to track items already visited. | |
1222 | (@pxref{Hash Table Reference}) | |
1223 | ||
1224 | @c Actually, it's probably safe to escape from ftw, just need to | |
1225 | @c check it. | |
1226 | @c | |
1227 | In the current implementation, returning non-@code{#t} from @var{proc} | |
1228 | is the only valid way to terminate @code{ftw}. @var{proc} must not | |
1229 | use @code{throw} or similar to escape. | |
1230 | @end defun | |
1231 | ||
1232 | ||
1233 | @defun nftw startname proc ['chdir] ['depth] ['hash-size n] ['mount] ['physical] | |
1234 | Walk the filesystem tree starting at @var{startname}, calling | |
1235 | @var{proc} for each file and directory. @code{nftw} has extra | |
1236 | features over the basic @code{ftw} described above. | |
1237 | ||
1238 | Hard links and symbolic links are followed, but a file or directory is | |
1239 | reported to @var{proc} only once, and skipped if seen again in another | |
1240 | place. One consequence of this is that @code{nftw} is safe against | |
1241 | circular linked directory structures. | |
1242 | ||
1243 | Each @var{proc} call is @code{(@var{proc} filename statinfo flag | |
1244 | basename level)} and it should return @code{#t} to continue, or any | |
1245 | other value to stop. | |
1246 | ||
1247 | @var{filename} is the item visited, being @var{startname} plus a | |
1248 | further path and the name of the item. @var{statinfo} is the return | |
1249 | from @code{stat} on @var{filename} (@pxref{File System}). | |
1250 | @var{basename} it the item name without any path. @var{level} is an | |
1251 | integer giving the directory nesting level, starting from 0 for the | |
1252 | contents of @var{startname} (or that item itself if it's a file). | |
1253 | @var{flag} is one of the following symbols, | |
1254 | ||
1255 | @table @code | |
1256 | @item regular | |
1257 | @var{filename} is a file, this includes special files like devices, | |
1258 | named pipes, etc. | |
1259 | ||
1260 | @item directory | |
1261 | @var{filename} is a directory. | |
1262 | ||
1263 | @item directory-processed | |
1264 | @var{filename} is a directory, and its contents have all been visited. | |
1265 | This flag is given instead of @code{directory} when the @code{depth} | |
1266 | option below is used. | |
1267 | ||
1268 | @item invalid-stat | |
1269 | An error occurred when applying @code{stat} to @var{filename}, so | |
1270 | nothing is known about it. @var{statinfo} is @code{#f} in this case. | |
1271 | ||
1272 | @item directory-not-readable | |
1273 | @var{filename} is a directory, but one which cannot be read and hence | |
1274 | won't be recursed into. | |
1275 | ||
1276 | @item symlink | |
1277 | @var{filename} is a dangling symbolic link. Symbolic links are | |
1278 | normally followed and their target reported, the link itself is | |
1279 | reported if the target does not exist. | |
1280 | ||
1281 | Under the @code{physical} option described below, @code{symlink} is | |
1282 | instead given for symbolic links whose target does exist. | |
1283 | ||
1284 | @item stale-symlink | |
1285 | Under the @code{physical} option described below, this indicates | |
1286 | @var{filename} is a dangling symbolic link, meaning its target does | |
1287 | not exist. Without the @code{physical} option plain @code{symlink} | |
1288 | indicates this. | |
1289 | @end table | |
1290 | ||
1291 | The following optional arguments can be given to modify the way | |
1292 | @code{nftw} works. Each is passed as a symbol (and @code{hash-size} | |
1293 | takes a following integer value). | |
1294 | ||
1295 | @table @asis | |
1296 | @item @code{chdir} | |
1297 | Change to the directory containing the item before calling @var{proc}. | |
1298 | When @code{nftw} returns the original current directory is restored. | |
1299 | ||
1300 | Under this option, generally the @var{basename} parameter should be | |
1301 | used to access the item in each @var{proc} call. The @var{filename} | |
1302 | parameter still has a path as normal and this will only be valid if | |
1303 | the @var{startname} directory was absolute. | |
1304 | ||
1305 | @item @code{depth} | |
1306 | Visit files ``depth first'', meaning @var{proc} is called for the | |
1307 | contents of each directory before it's called for the directory | |
1308 | itself. Normally a directory is reported first, then its contents. | |
1309 | ||
1310 | Under this option, the @var{flag} to @var{proc} for a directory is | |
1311 | @code{directory-processed} instead of @code{directory}. | |
1312 | ||
1313 | @item @code{hash-size @var{n}} | |
1314 | Set the size of the hash table used to track items already visited. | |
1315 | (@pxref{Hash Table Reference}) | |
1316 | ||
1317 | @item @code{mount} | |
1318 | Don't cross a mount point, meaning only visit items on the same | |
1319 | filesystem as @var{startname}. (Ie.@: the same @code{stat:dev}.) | |
1320 | ||
1321 | @item @code{physical} | |
1322 | Don't follow symbolic links, instead report them to @var{proc} as | |
1323 | @code{symlink}, and report dangling links as @code{stale-symlink}. | |
1324 | @end table | |
1325 | ||
1326 | The return value from @code{nftw} is @code{#t} if it ran to | |
1327 | completion, or otherwise the non-@code{#t} value from @var{proc} which | |
1328 | caused the stop. | |
1329 | ||
1330 | @c For reference, one reason not to esacpe is that the current | |
1331 | @c directory is not saved and restored with dynamic-wind. Maybe | |
1332 | @c changing that would be enough to allow escaping. | |
1333 | @c | |
1334 | In the current implementation, returning non-@code{#t} from @var{proc} | |
1335 | is the only valid way to terminate @code{ftw}. @var{proc} must not | |
1336 | use @code{throw} or similar to escape. | |
1337 | @end defun | |
1338 | ||
1339 | ||
2370f809 | 1340 | @node Queues |
3229f68b | 1341 | @section Queues |
2370f809 KR |
1342 | @cindex Queues |
1343 | @tindex Queues | |
1344 | ||
1345 | @noindent | |
1346 | The functions in this section are provided by | |
1347 | ||
1348 | @example | |
1349 | (use-modules (ice-9 q)) | |
1350 | @end example | |
1351 | ||
1352 | This module implements queues holding arbitrary scheme objects and | |
1353 | designed for efficient first-in / first-out operations. | |
1354 | ||
1355 | @code{make-q} creates a queue, and objects are entered and removed | |
1356 | with @code{enq!} and @code{deq!}. @code{q-push!} and @code{q-pop!} | |
1357 | can be used too, treating the front of the queue like a stack. | |
1358 | ||
1359 | @sp 1 | |
1360 | ||
1361 | @deffn {Scheme Procedure} make-q | |
1362 | Return a new queue. | |
1363 | @end deffn | |
1364 | ||
1365 | @deffn {Scheme Procedure} q? obj | |
1366 | Return @code{#t} if @var{obj} is a queue, or @code{#f} if not. | |
1367 | ||
1368 | Note that queues are not a distinct class of objects but are | |
1369 | implemented with cons cells. For that reason certain list structures | |
1370 | can get @code{#t} from @code{q?}. | |
1371 | @end deffn | |
1372 | ||
1373 | @deffn {Scheme Procedure} enq! q obj | |
1374 | Add @var{obj} to the rear of @var{q}, and return @var{q}. | |
1375 | @end deffn | |
1376 | ||
1377 | @deffn {Scheme Procedure} deq! q | |
1378 | @deffnx {Scheme Procedure} q-pop! q | |
1379 | Remove and return the front element from @var{q}. If @var{q} is | |
1380 | empty, a @code{q-empty} exception is thrown. | |
1381 | ||
1382 | @code{deq!} and @code{q-pop!} are the same operation, the two names | |
1383 | just let an application match @code{enq!} with @code{deq!}, or | |
1384 | @code{q-push!} with @code{q-pop!}. | |
1385 | @end deffn | |
1386 | ||
1387 | @deffn {Scheme Procedure} q-push! q obj | |
1388 | Add @var{obj} to the front of @var{q}, and return @var{q}. | |
1389 | @end deffn | |
1390 | ||
1391 | @deffn {Scheme Procedure} q-length q | |
1392 | Return the number of elements in @var{q}. | |
1393 | @end deffn | |
1394 | ||
1395 | @deffn {Scheme Procedure} q-empty? q | |
1396 | Return true if @var{q} is empty. | |
1397 | @end deffn | |
1398 | ||
1399 | @deffn {Scheme Procedure} q-empty-check q | |
1400 | Throw a @code{q-empty} exception if @var{q} is empty. | |
1401 | @end deffn | |
1402 | ||
1403 | @deffn {Scheme Procedure} q-front q | |
1404 | Return the first element of @var{q} (without removing it). If @var{q} | |
1405 | is empty, a @code{q-empty} exception is thrown. | |
1406 | @end deffn | |
1407 | ||
1408 | @deffn {Scheme Procedure} q-rear q | |
1409 | Return the last element of @var{q} (without removing it). If @var{q} | |
1410 | is empty, a @code{q-empty} exception is thrown. | |
1411 | @end deffn | |
1412 | ||
1413 | @deffn {Scheme Procedure} q-remove! q obj | |
1414 | Remove all occurences of @var{obj} from @var{q}, and return @var{q}. | |
1415 | @var{obj} is compared to queue elements using @code{eq?}. | |
1416 | @end deffn | |
1417 | ||
1418 | @sp 1 | |
1419 | @cindex @code{q-empty} | |
1420 | The @code{q-empty} exceptions described above are thrown just as | |
1421 | @code{(throw 'q-empty)}, there's no message etc like an error throw. | |
1422 | ||
1423 | A queue is implemented as a cons cell, the @code{car} containing a | |
1424 | list of queued elements, and the @code{cdr} being the last cell in | |
1425 | that list (for ease of enqueuing). | |
1426 | ||
1427 | @example | |
1428 | (@var{list} . @var{last-cell}) | |
1429 | @end example | |
1430 | ||
1431 | @noindent | |
1432 | If the queue is empty, @var{list} is the empty list and | |
1433 | @var{last-cell} is @code{#f}. | |
1434 | ||
1435 | An application can directly access the queue list if desired, for | |
1436 | instance to search the elements or to insert at a specific point. | |
1437 | ||
1438 | @deffn {Scheme Procedure} sync-q! q | |
1439 | Recompute the @var{last-cell} field in @var{q}. | |
1440 | ||
1441 | All the operations above maintain @var{last-cell} as described, so | |
1442 | normally there's no need for @code{sync-q!}. But if an application | |
1443 | modifies the queue @var{list} then it must either maintain | |
1444 | @var{last-cell} similarly, or call @code{sync-q!} to recompute it. | |
1445 | @end deffn | |
1446 | ||
1447 | ||
a0e07ba4 NJ |
1448 | @c Local Variables: |
1449 | @c TeX-master: "guile.texi" | |
1450 | @c End: |