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.
9 @section Pretty Printing
11 @c FIXME::martin: Review me!
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.
19 The module is loaded by simply saying.
22 (use-modules (ice-9 pretty-print))
25 This makes the procedure @code{pretty-print} available. As an example
26 how @code{pretty-print} will format the output, see the following:
29 (pretty-print '(define (foo) (lambda (x)
30 (cond ((zero? x) #t) ((negative? x) -x) (else
31 (if (= x 1) 2 (* x x x)))))))
37 (else (if (= x 1) 2 (* x x x))))))
40 @deffn {Scheme Procedure} pretty-print obj [port] [keyword-options]
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
45 The further @var{keyword-options} are keywords and parameters as
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})
53 @item @nicode{#:per-line-prefix} @var{string}
54 Print the given @var{string} as a prefix on each line. The default is
57 @item @nicode{#:width} @var{columns}
58 Print within the given @var{columns}. The default is 79.
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.
67 (write (lambda (x) x))
71 (pretty-print (lambda (x) x))
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}.
83 @node Formatted Output
84 @section Formatted Output
85 @cindex formatted output
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
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).
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
101 (use-modules (ice-9 format))
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
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.
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.
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
126 @var{fmt} can contain literal text to be output, and @nicode{~}
127 escapes. Each escape has the form
130 ~ [param [, param@dots{}] [:] [@@] code
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
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}
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.
150 The number of arguments remaining. (See @nicode{~*} below for some
154 Parameters are separated by commas (@nicode{,}). A parameter can be
155 left empty to keep its default value when supplying later parameters.
158 The following escapes are available. The code letters are not
159 case-sensitive, upper and lower case are the same.
164 Object output. Parameters: @var{minwidth}, @var{padinc},
165 @var{minpad}, @var{padchar}.
167 @nicode{~a} outputs an argument like @code{display}, @nicode{~s}
168 outputs an argument like @code{write} (@pxref{Writing}).
171 (format #t "~a" "foo") @print{} foo
172 (format #t "~s" "foo") @print{} "foo"
175 With the @nicode{:} modifier, objects which don't have an external
176 representation are put in quotes like a string.
179 (format #t "~:a" car) @print{} "#<primitive-procedure car>"
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.
187 (format #f "~5a" 'abc) @result{} "abc "
188 (format #f "~5,,,'-@@a" 'abc) @result{} "--abc"
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).
199 (format #f "~5,1,4a" 'abc) @result{} "abc "
203 Character. Parameter: @var{charnum}.
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.
211 (format #t "~c" #\z) @print{} z
212 (format #t "~@@c" #\z) @print{} #\z
213 (format #t "~:c" #\newline) @print{} ^J
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.
222 (format #t "~65c") @print{} A
229 Integer. Parameters: @var{minwidth}, @var{padchar}, @var{commachar},
232 Output an integer argument as a decimal, hexadecimal, octal or binary
233 integer (respectively).
236 (format #t "~d" 123) @print{} 123
239 With the @nicode{@@} modifier, a @nicode{+} sign is shown on positive
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?
247 (format #t "~@@b" 12) @print{} +1100
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
255 (format #t "~5,'*d" 12) @print{} ***12
256 (format #t "~5,'0d" 12) @print{} 00012
257 (format #t "~3d" 1234) @print{} 1234
260 The @nicode{:} modifier adds commas (or the @var{commachar} parameter)
261 every three digits (or the @var{commawidth} parameter many).
264 (format #t "~:d" 1234567) @print{} 1,234,567
265 (format #t "~10,'*,'/,2:d" 12345) @print{} ***1/23/45
268 Hexadecimal @nicode{~x} output is in lower case, but the @nicode{~(}
269 and @nicode{~)} case conversion directives described below can be used
273 (format #t "~x" 65261) @print{} feed
274 (format #t "~:@@(~x~)" 65261) @print{} FEED
278 Integer in words, roman numerals, or a specified radix. Parameters:
279 @var{radix}, @var{minwidth}, @var{padchar}, @var{commachar},
282 With no parameters output is in words as a cardinal like ``ten'', or
283 with the @nicode{:} modifier as an ordinal like ``tenth''.
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
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.
298 (format #t "~@@r" 89) @print{} LXXXIX ;; roman
299 (format #t "~@@:r" 89) @print{} LXXXVIIII ;; old roman
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.
307 (format #f "~3r" 27) @result{} "1000" ;; base 3
308 (format #f "~3,5r" 26) @result{} " 222" ;; base 3 width 5
312 Fixed-point float. Parameters: @var{width}, @var{decimals},
313 @var{scale}, @var{overflowchar}, @var{padchar}.
315 Output a number or number string in fixed-point format, ie.@: with a
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
324 With the @nicode{@@} modifier a @nicode{+} sign is shown on positive
325 numbers (including zero).
328 (format #t "~@@f" 0) @print{} +0.0
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.
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"
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.)
347 (format #t "~1,2f" 3.125) @print{} 3.13
348 (format #t "~1,2f" 1.5) @print{} 1.50
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.
356 (format #t "~,,2f" 1234) @print{} 123400.0
357 (format #t "~,,-2f" 1234) @print{} 12.34
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.
365 (format #t "~5,,,'xf" 12345) @print{} 12345
366 (format #t "~4,,,'xf" 12345) @print{} xxxx
370 Exponential float. Parameters: @var{width}, @var{mantdigits},
371 @var{expdigits}, @var{intdigits}, @var{overflowchar}, @var{padchar},
374 Output a number or number string in exponential notation.
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
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.)
387 (format #t "~@@e" 5000.0) @print{} +5.0E+3
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.
395 (format #f "~10e" 1234.0) @result{} " 1.234E+3"
396 (format #f "~10,,,,,'*e" 0.5) @result{} "****5.0E-1"
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
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
409 (format #f "~,3e" 11111.0) @result{} "1.111E+4"
410 (format #f "~,8e" 123.0) @result{} "1.23000000E+2"
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.
419 (format #f "~,,1e" 1.0e99) @result{} "1.0E+99"
420 (format #f "~,,6e" 1.0e99) @result{} "1.0E+000099"
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.
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?
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
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
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.
449 (format #f "~6,,,,'xe" 100.0) @result{} "1.0E+2"
450 (format #f "~3,,,,'xe" 100.0) @result{} "xxx"
453 @var{expchar} is the exponent marker character (default @nicode{E}).
456 (format #t "~,,,,,,'ee" 100.0) @print{} 1.0e+2
460 General float. Parameters: @var{width}, @var{mantdigits},
461 @var{expdigits}, @var{intdigits}, @var{overflowchar}, @var{padchar},
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.
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.
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.
480 (format #f "~12,4,2g" 999.0) @result{} " 999.0 "
481 (format #f "~12,4,2g" "100000") @result{} " 1.0000E+05"
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.
490 Monetary style fixed-point float. Parameters: @var{decimals},
491 @var{intdigits}, @var{width}, @var{padchar}.
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.
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
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
508 With the @nicode{@@} modifier a @nicode{+} sign is shown on positive
509 numbers (including zero).
512 (format #t "~@@$" 0) @print{} +0.00
515 @var{intdigits} is a minimum number of digits to show in the integer
516 part of the value (default 1).
519 (format #t "~,3$" 9.5) @print{} 009.50
520 (format #t "~,0$" 0.125) @print{} .13
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.
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"
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
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.
548 Complex fixed-point float. Parameters: @var{width}, @var{decimals},
549 @var{scale}, @var{overflowchar}, @var{padchar}.
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.
554 Output the argument as a complex number, with both real and imaginary
555 part shown (even if one or both are zero).
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.
564 (format #t "~i" 1) @print{} 1.0+0.0i
568 Plural. No parameters.
570 Output nothing if the argument is 1, or @samp{s} for any other
574 (format #t "enter name~p" 1) @print{} enter name
575 (format #t "enter name~p" 2) @print{} enter names
578 With the @nicode{@@} modifier, the output is @samp{y} for 1 or
579 @samp{ies} otherwise.
582 (format #t "pupp~@@p" 1) @print{} puppy
583 (format #t "pupp~@@p" 2) @print{} puppies
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
591 (format #t "~d cat~:p" 9) @print{} 9 cats
595 Pretty print. No parameters.
597 Output an argument with @code{pretty-print} (@pxref{Pretty Printing}).
601 Sub-format. No parameters.
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
609 (format #t "~?" "~d ~d" '(1 2)) @print{} 1 2
610 (format #t "~@@? ~s" "~d ~d" 1 2 "foo") @print{} 1 2 "foo"
613 @nicode{~?} and @nicode{~k} are the same, @nicode{~k} is provided for
614 T-Scheme compatibility.
617 Argument jumping. Parameter: @var{N}.
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
624 (format #f "~d ~:*~d" 6) @result{} "6 6"
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}).
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"
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).
642 (format #t "~2*~d" 1 2 3 4) ;; error
643 (format #t "~2*~d~#*" 1 2 3 4) @result{} 3
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.
651 Advance to a column position. Parameters: @var{colnum}, @var{colinc},
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.
659 (format #f "~tX") @result{} " X"
660 (format #f "~3tX") @result{} " X"
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).
670 (format #f "abcd~2,5,'.tx") @result{} "abcd...x"
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
679 (format #f "a~3,5'*@@tx") @result{} "a****x"
683 Tilde character. Parameter: @var{n}.
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.
690 Newline. Parameter: @var{n}.
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.
697 Start a new line. Parameter: @var{n}.
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.
705 Space character. Parameter: @var{n}.
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.
710 Output a space character, or @var{n} many if a parameter is given.
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
717 (format #f "~v_foo" 4) @result{} " foo"
721 Tab character. Parameter: @var{n}.
723 Output a tab character, or @var{n} many if a parameter is given.
726 Formfeed character. Parameter: @var{n}.
728 Output a formfeed character, or @var{n} many if a parameter is given.
731 Force output. No parameters.
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.
737 When output is to a string (destination @code{#f}), @nicode{~!} does
740 @item @nicode{~newline} (ie.@: newline character)
741 Continuation line. No parameters.
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
749 This escape can be used to break up a long format string into multiple
750 lines for readability, but supress that extra whitespace.
755 ~d" 1 2) @result{} "abc1 def2"
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
765 no modifiers --- lower case.
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.
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
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
785 @c @nicode{@@} --- first letter of just the first word upper case, the
789 @nicode{:} and @nicode{@@} together --- upper case.
795 (format #t "~(Hello~)") @print{} hello
796 (format #t "~@@:(Hello~)") @print{} HELLO
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.
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
809 @item @nicode{~@{} @nicode{~@}}
810 Iteration. Parameter: @var{maxreps} (for @nicode{~@{}).
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.
818 (format #t "~@{~d~@}" '(1 2 3)) @print{} 123
819 (format #t "~@{~s=~d ~@}" '("x" 1 "y" 2)) @print{} "x"=1 "y"=2
822 With the @nicode{:} modifier a list of lists argument is taken, each
823 of those lists gives the arguments for the iterated format.
826 (format #t "~:@{~dx~d ~@}" '((1 2) (3 4) (5 6))) @print{} 1x2 3x4 5x6
829 With the @nicode{@@} modifier, the remaining arguments are used, each
830 iteration successively consuming elements.
833 (format #t "~@@@{~d~@}" 1 2 3) @print{} 123
834 (format #t "~@@@{~s=~d ~@}" "x" 1 "y" 2) @print{} "x"=1 "y"=2
837 With both @nicode{:} and @nicode{@@} modifiers, the remaining
838 arguments are used, each is a list of arguments for the format.
841 (format #t "~:@@@{~dx~d ~@}" '(1 2) '(3 4) '(5 6)) @print{} 1x2 3x4 5x6
844 Iterating stops when there are no more arguments or when the
845 @var{maxreps} parameter to @nicode{~@{} is reached (default no
849 (format #t "~2@{~d~@}" '(1 2 3 4)) @print{} 12
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
858 (format #t "~@{~@}" "~d" '(1 2 3)) @print{} 123
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.
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.
872 (format #t "~@{~@{~d~@}x~@}" '((1 2) (3 4 5))) @print{} 12x345x
875 @item @nicode{~[} @nicode{~;} @nicode{~]}
876 Conditional. Parameter: @var{selector}.
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
884 (format #f "~[peach~;banana~;mango~]" 1) @result{} "banana"
887 The @var{selector} parameter can be used for the clause number,
888 instead of taking an argument.
891 (format #f "~2[peach~;banana~;mango~]") @result{} "mango"
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.
899 (format #f "~[banana~;mango~]" 99) @result{} ""
900 (format #f "~[banana~;mango~:;fruit~]" 99) @result{} "fruit"
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.
908 (format #f "~:[false~;not false~]" #f) @result{} "false"
909 (format #f "~:[false~;not false~]" 'abc) @result{} "not false"
912 (format #t "~d gnu~:[s are~; is~] here" n (= 1 n)))
913 @print{} 3 gnus are here
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.
924 (format #f "~@@[temperature=~d~]" 27) @result{} "temperature=27"
925 (format #f "~@@[temperature=~d~]" #f) @result{} ""
929 Escape. Parameters: @var{val1}, @var{val2}, @var{val3}.
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
936 (format #t "~d~^ ~d" 1) @print{} 1
937 (format #t "~d~^ ~d" 1 2) @print{} 1 2
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.
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"
950 @c For reference, format.scm doesn't implement that Common Lisp ~:^
951 @c modifier which stops the entire iterating of ~:{ or ~@:{.
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
958 @c (format #f "~[abc~^def~;ghi~] blah" 0)
959 @c @result{} "abc blah" ;; looks wrong
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.
966 @c (format #f "~d ~^ ~d" 1) @result{} "1 "
967 @c (format #f "~(~d ~^ ~d~)" 1) @result{} ERROR
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.
974 (format #t "~? items" "~d~^ ~d" '(1)) @print{} 1 items
975 (format #t "~? items" "~d~^ ~d" '(1 2)) @print{} 1 2 items
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}}.
985 @c FIXME: Good examples of these?
988 Inquiry message. Insert a copyright message into the output. With
989 the @nicode{:} modifier insert the format implementation version.
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.)
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
1004 (format #t "~@{ ~[ ... ~] ~@}" ...) ;; good
1005 (format #t "~@{ ~[ ... ~@} ... ~]" ...) ;; bad
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
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.
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.
1031 @section The Rx Regular Expression Library
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!]
1037 @cindex finite automaton
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
1045 For example, given the regular expression @samp{abc.} (which matches any
1046 string containing @samp{abc} followed by any single character):
1049 guile> @kbd{(define r (regcomp "abc."))}
1052 guile> @kbd{(regexec r "abc")}
1054 guile> @kbd{(regexec r "abcd")}
1059 The definitions of @code{regcomp} and @code{regexec} are as follows:
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
1068 use case-insensitive matching
1071 allow anchors to match after newline characters in the
1072 string and prevents @code{.} or @code{[^...]} from matching newlines.
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{\+}
1079 operators. Backslashes in @var{pattern} must be escaped if specified in a
1080 literal string e.g., @code{"\\(a\\)\\?"}.
1083 @deffn {Scheme Procedure} regexec regex string [match-pick] [flags]
1084 Match @var{string} against the compiled POSIX regular expression
1086 @var{match-pick} and @var{flags} are optional. Possible flags (which can be
1087 combined using the logior procedure) are:
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)
1095 Similar to REG_NOTBOL, but prevents the end of line operator
1096 from matching the end of @var{string}.
1099 If no match is possible, regexec returns #f. Otherwise @var{match-pick}
1100 determines the return value:
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
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}.
1111 @code{#f}: regexec returns #t if a match is made, otherwise #f.
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).
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:
1121 a number: the numbered matching substring (0 for the entire match).
1123 @code{#\<}: the beginning of @var{string} to the beginning of the part matched
1126 @code{#\>}: the end of the matched part of @var{string} to the end of
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
1133 e.g., @code{(list #\< 0 1 #\>)}. The returned substrings share memory with
1137 Here are some other procedures that might be used when using regular
1140 @deffn {Scheme Procedure} compiled-regexp? obj
1141 Test whether obj is a compiled regular expression.
1144 @deffn {Scheme Procedure} regexp->dfa regex [flags]
1147 @deffn {Scheme Procedure} dfa-fork dfa
1150 @deffn {Scheme Procedure} reset-dfa! dfa
1153 @deffn {Scheme Procedure} dfa-final-tag dfa
1156 @deffn {Scheme Procedure} dfa-continuable? dfa
1159 @deffn {Scheme Procedure} advance-dfa! dfa string
1163 @node File Tree Walk
1164 @section File Tree Walk
1165 @cindex file tree walk
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
1173 (use-modules (ice-9 ftw))
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.
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.
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.
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,
1196 @var{filename} is a file, this includes special files like devices,
1200 @var{filename} is a directory.
1203 An error occurred when calling @code{stat}, so nothing is known.
1204 @var{statinfo} is @code{#f} in this case.
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.
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.
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
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})
1224 @c Actually, it's probably safe to escape from ftw, just need to
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.
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.
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.
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.
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,
1257 @var{filename} is a file, this includes special files like devices,
1261 @var{filename} is a directory.
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.
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.
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.
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.
1281 Under the @code{physical} option described below, @code{symlink} is
1282 instead given for symbolic links whose target does exist.
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}
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).
1297 Change to the directory containing the item before calling @var{proc}.
1298 When @code{nftw} returns the original current directory is restored.
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.
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.
1310 Under this option, the @var{flag} to @var{proc} for a directory is
1311 @code{directory-processed} instead of @code{directory}.
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})
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}.)
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}.
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
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.
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.
1346 The functions in this section are provided by
1349 (use-modules (ice-9 q))
1352 This module implements queues holding arbitrary scheme objects and
1353 designed for efficient first-in / first-out operations.
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.
1361 @deffn {Scheme Procedure} make-q
1365 @deffn {Scheme Procedure} q? obj
1366 Return @code{#t} if @var{obj} is a queue, or @code{#f} if not.
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?}.
1373 @deffn {Scheme Procedure} enq! q obj
1374 Add @var{obj} to the rear of @var{q}, and return @var{q}.
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.
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!}.
1387 @deffn {Scheme Procedure} q-push! q obj
1388 Add @var{obj} to the front of @var{q}, and return @var{q}.
1391 @deffn {Scheme Procedure} q-length q
1392 Return the number of elements in @var{q}.
1395 @deffn {Scheme Procedure} q-empty? q
1396 Return true if @var{q} is empty.
1399 @deffn {Scheme Procedure} q-empty-check q
1400 Throw a @code{q-empty} exception if @var{q} is empty.
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.
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.
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?}.
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.
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).
1428 (@var{list} . @var{last-cell})
1432 If the queue is empty, @var{list} is the empty list and
1433 @var{last-cell} is @code{#f}.
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.
1438 @deffn {Scheme Procedure} sync-q! q
1439 Recompute the @var{last-cell} field in @var{q}.
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.
1449 @c TeX-master: "guile.texi"