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.
64 @node Formatted Output
65 @section Formatted Output
66 @cindex formatted output
68 @c For reference, in this section escapes like ~a are given in
69 @c @nicode, to give code font in TeX etc, but leave them unadorned in
72 @c The idea is to reduce clutter around what's shown, and avoid any
73 @c possible confusion over whether the ` ' quotes are part of what
74 @c should be entered. (In particular for instance of course ' is
75 @c meaningful in a format string, introducing a char parameter).
77 The @code{format} function is a powerful way to print numbers, strings
78 and other objects together with literal text under the control of a
79 format string. This function is available from
82 (use-modules (ice-9 format))
85 A format string is generally more compact and easier than using just
86 the standard procedures like @code{display}, @code{write} and
87 @code{newline}. Parameters in the output string allow various output
88 styles, and parameters can be taken from the arguments for runtime
91 @code{format} is similar to the Common Lisp procedure of the same
92 name, but it's not identical and doesn't have quite all the features
95 C programmers will note the similarity between @code{format} and
96 @code{printf}, though escape sequences are marked with @nicode{~}
97 instead of @nicode{%}, and are more powerful.
100 @deffn {Scheme Procedure} format dest fmt [args@dots{}]
101 Write output specified by the @var{fmt} string to @var{dest}.
102 @var{dest} can be an output port, @code{#t} for
103 @code{current-output-port} (@pxref{Default Ports}), a number for
104 @code{current-error-port}, or @code{#f} to return the output as a
107 @var{fmt} can contain literal text to be output, and @nicode{~}
108 escapes. Each escape has the form
111 ~ [param [, param@dots{}] [:] [@@] code
114 @nicode{code} is a character determining the escape sequence. The
115 @nicode{:} and @nicode{@@} characters are optional modifiers, one or
116 both of which change the way various codes operate. Optional
117 parameters are accepted by some codes too. Parameters have the
121 @item @nicode{[+/-] number}
122 An integer, with optional @nicode{+} or @nicode{-}.
123 @item @nicode{'} (apostrophe)
124 The following character in the format string, for instance @nicode{'z}
127 The next function argument as the parameter. @nicode{v} stands for
128 ``variable'', a parameter can be calculated at runtime and included in
129 the arguments. Upper case @nicode{V} can be used too.
131 The number of arguments remaining. (See @nicode{~*} below for some
135 Parameters are separated by commas (@nicode{,}). A parameter can be
136 left empty to keep its default value when supplying later parameters.
139 The following escapes are available. The code letters are not
140 case-sensitive, upper and lower case are the same.
145 Object output. Parameters: @var{minwidth}, @var{padinc},
146 @var{minpad}, @var{padchar}.
148 @nicode{~a} outputs an argument like @code{display}, @nicode{~s}
149 outputs an argument like @code{write} (@pxref{Writing}).
152 (format #t "~a" "foo") @print{} foo
153 (format #t "~s" "foo") @print{} "foo"
156 With the @nicode{:} modifier, objects which don't have an external
157 representation are put in quotes like a string.
160 (format #t "~:a" car) @print{} "#<primitive-procedure car>"
163 If the output is less than @var{minwidth} characters (default 0), it's
164 padded on the right with @var{padchar} (default space). The
165 @nicode{@@} modifier puts the padding on the left instead.
168 (format #f "~5a" 'abc) @result{} "abc "
169 (format #f "~5,,,'-@@a" 'abc) @result{} "--abc"
172 @var{minpad} is a minimum for the padding then plus a multiple of
173 @var{padinc}. Ie.@: the padding is @math{@var{minpad} + @var{N} *
174 @var{padinc}}, where @var{n} is the smallest integer making the total
175 object plus padding greater than or equal to @var{minwidth}. The
176 default @var{minpad} is 0 and the default @var{padinc} is 1 (imposing
177 no minimum or multiple).
180 (format #f "~5,1,4a" 'abc) @result{} "abc "
184 Character. Parameter: @var{charnum}.
186 Output a character. The default is to simply output, as per
187 @code{write-char} (@pxref{Writing}). With the @nicode{@@} modifier
188 output is in @code{write} style. Or with the @nicode{:} modifier
189 control characters (ASCII 0 to 31) are printed in @nicode{^X} form.
192 (format #t "~c" #\z) @print{} z
193 (format #t "~@@c" #\z) @print{} #\z
194 (format #t "~:c" #\newline) @print{} ^J
197 If the @var{charnum} parameter is given then an argument is not taken
198 but instead the character is @code{(integer->char @var{charnum})}
199 (@pxref{Characters}). This can be used for instance to output
200 characters given by their ASCII code.
203 (format #t "~65c") @print{} A
210 Integer. Parameters: @var{minwidth}, @var{padchar}, @var{commachar},
213 Output an integer argument as a decimal, hexadecimal, octal or binary
214 integer (respectively).
217 (format #t "~d" 123) @print{} 123
220 With the @nicode{@@} modifier, a @nicode{+} sign is shown on positive
223 @c FIXME: "+" is not shown on zero, unlike in Common Lisp. Should
224 @c that be changed in the code, or is it too late and should just be
225 @c documented that way?
228 (format #t "~@@b" 12) @print{} +1100
231 If the output is less than the @var{minwidth} parameter (default no
232 minimum), it's padded on the left with the @var{padchar} parameter
236 (format #t "~5,'*d" 12) @print{} ***12
237 (format #t "~5,'0d" 12) @print{} 00012
238 (format #t "~3d" 1234) @print{} 1234
241 The @nicode{:} modifier adds commas (or the @var{commachar} parameter)
242 every three digits (or the @var{commawidth} parameter many).
245 (format #t "~:d" 1234567) @print{} 1,234,567
246 (format #t "~10,'*,'/,2:d" 12345) @print{} ***1/23/45
249 Hexadecimal @nicode{~x} output is in lower case, but the @nicode{~(}
250 and @nicode{~)} case conversion directives described below can be used
254 (format #t "~x" 65261) @print{} feed
255 (format #t "~:@@(~x~)" 65261) @print{} FEED
259 Integer in words, roman numerals, or a specified radix. Parameters:
260 @var{radix}, @var{minwidth}, @var{padchar}, @var{commachar},
263 With no parameters output is in words as a cardinal like ``ten'', or
264 with the @nicode{:} modifier as an ordinal like ``tenth''.
267 (format #t "~r" 9) @print{} nine ;; cardinal
268 (format #t "~r" -9) @print{} minus nine ;; cardinal
269 (format #t "~:r" 9) @print{} ninth ;; ordinal
272 And also with no parameters, the @nicode{@@} modifier gives roman
273 numerals and @nicode{@@} and @nicode{:} together give old roman
274 numerals. In old roman numerals there's no ``subtraction'', so 9 is
275 @nicode{VIIII} instead of @nicode{IX}. In both cases only positive
276 numbers can be output.
279 (format #t "~@@r" 89) @print{} LXXXIX ;; roman
280 (format #t "~@@:r" 89) @print{} LXXXVIIII ;; old roman
283 When a parameter is given it means numeric output in the specified
284 @var{radix}. The modifiers and parameters following the radix are the
285 same as described for @nicode{~d} etc above.
288 (format #f "~3r" 27) @result{} "1000" ;; base 3
289 (format #f "~3,5r" 26) @result{} " 222" ;; base 3 width 5
293 Fixed-point float. Parameters: @var{width}, @var{decimals},
294 @var{scale}, @var{overflowchar}, @var{padchar}.
296 Output a number or number string in fixed-point format, ie.@: with a
300 (format #t "~f" 5) @print{} 5.0
301 (format #t "~f" "123") @print{} 123.0
302 (format #t "~f" "1e-1") @print{} 0.1
305 With the @nicode{@@} modifier a @nicode{+} sign is shown on positive
306 numbers (including zero).
309 (format #t "~@@f" 0) @print{} +0.0
312 If the output is less than @var{width} characters it's padded on the
313 left with @var{padchar} (space by default). If the output equals or
314 exceeds @var{width} then there's no padding. The default for
315 @var{width} is no padding.
318 (format #f "~6f" -1.5) @result{} " -1.5"
319 (format #f "~6,,,,'*f" 23) @result{} "**23.0"
320 (format #f "~6f" 1234567.0) @result{} "1234567.0"
323 @var{decimals} is how many digits to print after the decimal point,
324 with the value rounded or padded with zeros as necessary. (The
325 default is to output as many decimals as required.)
328 (format #t "~1,2f" 3.125) @print{} 3.13
329 (format #t "~1,2f" 1.5) @print{} 1.50
332 @var{scale} is a power of 10 applied to the value, moving the decimal
333 point that many places. A positive @var{scale} increases the value
334 shown, a negative decreases it.
337 (format #t "~,,2f" 1234) @print{} 123400.0
338 (format #t "~,,-2f" 1234) @print{} 12.34
341 If @var{overflowchar} and @var{width} are both given and if the output
342 would exceed @var{width}, then that many @var{overflowchar}s are
343 printed instead of the value.
346 (format #t "~5,,,'xf" 12345) @print{} 12345
347 (format #t "~4,,,'xf" 12345) @print{} xxxx
351 Exponential float. Parameters: @var{width}, @var{mantdigits},
352 @var{expdigits}, @var{intdigits}, @var{overflowchar}, @var{padchar},
355 Output a number or number string in exponential notation.
358 (format #t "~e" 5000.25) @print{} 5.00025E+3
359 (format #t "~e" "123.4") @print{} 1.234E+2
360 (format #t "~e" "1e4") @print{} 1.0E+4
363 With the @nicode{@@} modifier a @nicode{+} sign is shown on positive
364 numbers (including zero). (This is for the mantissa, a @nicode{+} or
365 @nicode{-} sign is always shown on the exponent.)
368 (format #t "~@@e" 5000.0) @print{} +5.0E+3
371 If the output is less than @var{width} characters it's padded on the
372 left with @var{padchar} (space by default). The default for
373 @var{width} is to output with no padding.
376 (format #f "~10e" 1234.0) @result{} " 1.234E+3"
377 (format #f "~10,,,,,'*e" 0.5) @result{} "****5.0E-1"
380 @c FIXME: Describe what happens when the number is bigger than WIDTH.
381 @c There seems to be a bit of dodginess about this, or some deviation
384 @var{mantdigits} is the number of digits shown in the mantissa after
385 the decimal point. The value is rounded or trailing zeros are added
386 as necessary. The default @var{mantdigits} is to show as much as
390 (format #f "~,3e" 11111.0) @result{} "1.111E+4"
391 (format #f "~,8e" 123.0) @result{} "1.23000000E+2"
394 @var{expdigits} is the minimum number of digits shown for the
395 exponent, with leading zeros added if necessary. The default for
396 @var{expdigits} is to show only as many digits as required. At least
397 1 digit is always shown.
400 (format #f "~,,1e" 1.0e99) @result{} "1.0E+99"
401 (format #f "~,,6e" 1.0e99) @result{} "1.0E+000099"
404 @var{intdigits} (default 1) is the number of digits to show before the
405 decimal point in the mantissa. @var{intdigits} can be zero, in which
406 case the integer part is a single @nicode{0}, or it can be negative,
407 in which case leading zeros are shown after the decimal point.
409 @c FIXME: When INTDIGITS is 0, Common Lisp format apparently only
410 @c shows the single 0 digit if it fits in WIDTH. format.scm seems to
411 @c show it always. Is it meant to?
414 (format #t "~,,,3e" 12345.0) @print{} 123.45E+2
415 (format #t "~,,,0e" 12345.0) @print{} 0.12345E+5
416 (format #t "~,,,-3e" 12345.0) @print{} 0.00012345E+8
419 @c FIXME: MANTDIGITS with negative INTDIGITS doesn't match CL spec,
420 @c believe the spec says it ought to still show mantdigits+1 sig
421 @c figures, ie. leading zeros don't count towards MANTDIGITS, but it
422 @c seems to just treat MANTDIGITS as how many digits after the
425 If @var{overflowchar} is given then @var{width} is a hard limit. If
426 the output would exceed @var{width} then instead that many
427 @var{overflowchar}s are printed.
430 (format #f "~6,,,,'xe" 100.0) @result{} "1.0E+2"
431 (format #f "~3,,,,'xe" 100.0) @result{} "xxx"
434 @var{expchar} is the exponent marker character (default @nicode{E}).
437 (format #t "~,,,,,,'ee" 100.0) @print{} 1.0e+2
441 General float. Parameters: @var{width}, @var{mantdigits},
442 @var{expdigits}, @var{intdigits}, @var{overflowchar}, @var{padchar},
445 Output a number or number string in either exponential format the same
446 as @nicode{~e}, or fixed-point format like @nicode{~f} but aligned
447 where the mantissa would have been and followed by padding where the
448 exponent would have been.
450 @c FIXME: The default MANTDIGITS is apparently max(needed,min(n,7))
451 @c where 10^(n-1)<=abs(x)<=10^n. But the Common Lisp spec seems to
452 @c ask for "needed" to be without leading or trailing zeros, whereas
453 @c format.scm seems to include trailing zeros, ending up with it
454 @c using fixed format for bigger values than it should.
456 Fixed-point is used when the absolute value is 0.1 or more and it
457 takes no more space than the mantissa in exponential format, ie.@:
458 basically up to @var{mantdigits} digits.
461 (format #f "~12,4,2g" 999.0) @result{} " 999.0 "
462 (format #f "~12,4,2g" "100000") @result{} " 1.0000E+05"
465 The parameters are interpreted as per @nicode{~e} above. When
466 fixed-point is used, the @var{decimals} parameter to @nicode{~f} is
467 established from @var{mantdigits}, so as to give a total
468 @math{@var{mantdigits}+1} figures.
471 Monetary style fixed-point float. Parameters: @var{decimals},
472 @var{intdigits}, @var{width}, @var{padchar}.
474 @c For reference, fmtdoc.txi from past versions of slib showed the
475 @c INTDIGITS parameter as SCALE. That looks like a typo, in the code
476 @c and in the Common Lisp spec it's a minimum digits for the integer
477 @c part, it isn't a power of 10 like in ~f.
479 Output a number or number string in fixed-point format, ie.@: with a
480 decimal point. @var{decimals} is the number of decimal places to
484 (format #t "~$" 5) @print{} 5.00
485 (format #t "~4$" "2.25") @print{} 2.2500
486 (format #t "~4$" "1e-2") @print{} 0.0100
489 With the @nicode{@@} modifier a @nicode{+} sign is shown on positive
490 numbers (including zero).
493 (format #t "~@@$" 0) @print{} +0.00
496 @var{intdigits} is a minimum number of digits to show in the integer
497 part of the value (default 1).
500 (format #t "~,3$" 9.5) @print{} 009.50
501 (format #t "~,0$" 0.125) @print{} .13
504 If the output is less than @var{width} characters (default 0), it's
505 padded on the left with @var{padchar} (default space). With the
506 @nicode{:} modifier the padding is output after the sign.
509 (format #f "~,,8$" -1.5) @result{} " -1.50"
510 (format #f "~,,8:$" -1.5) @result{} "- 1.50"
511 (format #f "~,,8,'.@@:$" 3) @result{} "+...3.00"
514 Note that floating point for dollar amounts is generally not a good
515 idea, because a cent @math{0.01} cannot be represented exactly in the
516 binary floating point Guile uses, which leads to slowly accumulating
517 rounding errors. Keeping values as cents (or fractions of a cent) in
518 integers then printing with the scale option in @nicode{~f} may be a
521 @c For reference, fractions don't work with ~$ (or any of the float
522 @c conversions) currently. If they did work then we could perhaps
523 @c suggest keeping dollar amounts as rationals, which would of course
524 @c give exact cents. An integer as cents is probably still a better
525 @c recommendation though, since it forces one to think about where
526 @c and when rounding can or should occur.
529 Complex fixed-point float. Parameters: @var{width}, @var{decimals},
530 @var{scale}, @var{overflowchar}, @var{padchar}.
532 @c For reference, in Common Lisp ~i is an indent, but slib fmtdoc.txi
533 @c described it as complex number output, so we keep that.
535 Output the argument as a complex number, with both real and imaginary
536 part shown (even if one or both are zero).
538 The parameters and modifiers are the same as for fixed-point
539 @nicode{~f} described above. The real and imaginary parts are both
540 output with the same given parameters and modifiers, except that for
541 the imaginary part the @nicode{@@} modifier is always enabled, so as
542 to print a @nicode{+} sign between the real and imaginary parts.
545 (format #t "~i" 1) @print{} 1.0+0.0i
549 Plural. No parameters.
551 Output nothing if the argument is 1, or @samp{s} for any other
555 (format #t "enter name~p" 1) @print{} enter name
556 (format #t "enter name~p" 2) @print{} enter names
559 With the @nicode{@@} modifier, the output is @samp{y} for 1 or
560 @samp{ies} otherwise.
563 (format #t "pupp~@@p" 1) @print{} puppy
564 (format #t "pupp~@@p" 2) @print{} puppies
567 The @nicode{:} modifier means re-use the preceding argument instead of
568 taking a new one, which can be convenient when printing some sort of
572 (format #t "~d cat~:p" 9) @print{} 9 cats
576 Pretty print. No parameters.
578 Output an argument with @code{pretty-print} (@pxref{Pretty Printing}).
582 Sub-format. No parameters.
584 Take a format string argument and a second argument which is a list of
585 arguments for it, and output the result. With the @nicode{@@}
586 modifier, the arguments for the sub-format are taken directly rather
590 (format #t "~?" "~d ~d" '(1 2)) @print{} 1 2
591 (format #t "~@@? ~s" "~d ~d" 1 2 "foo") @print{} 1 2 "foo"
594 @nicode{~?} and @nicode{~k} are the same, @nicode{~k} is provided for
595 T-Scheme compatibility.
598 Argument jumping. Parameter: @var{N}.
600 Move forward @var{N} arguments (default 1) in the argument list. With
601 the @nicode{:} modifier move backwards. @var{N} can be negative to
605 (format #f "~d ~:*~d" 6) @result{} "6 6"
608 With the @nicode{@@} modifier, move to argument number @var{N}. The
609 first argument is number 0 (and that's the default for @var{N}).
612 (format #f "~d~d again ~@@*~d~d" 1 2) @result{} "12 again 12"
613 (format #f "~d~d~d ~1@@*~d~d" 1 2 3) @result{} "123 23"
616 At the end of the format string the last argument must have been
617 consumed, or a ``too many arguments'' error results. If the last
618 argument is not the last to be printed, then a move to skip the
619 remaining must be given. This can be done with the @nicode{#}
620 parameter (count of remaining arguments).
623 (format #t "~2*~d" 1 2 3 4) ;; error
624 (format #t "~2*~d~#*" 1 2 3 4) @result{} 3
627 A @nicode{#} move to the end followed by a @nicode{:} modifier move
628 back can be used for an absolute position relative to the end of the
629 argument list, a reverse of what the @nicode{@@} modifier does.
632 Advance to a column position. Parameters: @var{colnum}, @var{colinc},
635 Output @var{padchar} (space by default) to move to the given
636 @var{colnum} column. The start of the line is column 0, the default
637 for @var{colnum} is 1.
640 (format #f "~tX") @result{} " X"
641 (format #f "~3tX") @result{} " X"
644 If the current column is already past @var{colnum}, then the move is
645 to there plus a multiple of @var{colinc}, ie.@: column
646 @math{@var{colnum} + @var{N} * @var{colinc}} for the smallest @var{N}
647 which makes that value greater than or equal to the current column.
648 The default @var{colinc} is 1 (which means no further move).
651 (format #f "abcd~2,5,'.tx") @result{} "abcd...x"
654 With the @nicode{@@} modifier, @var{colnum} is relative to the current
655 column. @var{colnum} many padding characters are output, then further
656 padding to make the current column a multiple of @var{colinc}, if it
660 (format #f "a~3,5'*@@tx") @result{} "a****x"
664 Tilde character. Parameter: @var{n}.
666 Output a tilde character @nicode{~}, or @var{n} many if a parameter is
667 given. Normally @nicode{~} introduces an escape sequence, @nicode{~~}
668 is the way to output a literal tilde.
671 Newline. Parameter: @var{n}.
673 Output a newline character, or @var{n} many if a parameter is given.
674 A newline (or a few newlines) can of course be output just by
675 including them in the format string.
678 Start a new line. Parameter: @var{n}.
680 Output a newline if not already at the start of a line. With a
681 parameter, output that many newlines, but with the first only if not
682 already at the start of a line. So for instance 3 would be a newline
683 if not already at the start of a line, and 2 further newlines.
686 Space character. Parameter: @var{n}.
688 @c For reference, in Common Lisp ~_ is a conditional newline, but
689 @c slib fmtdoc.txi described it as a space, so we keep that.
691 Output a space character, or @var{n} many if a parameter is given.
693 With a variable parameter this is one way to insert runtime calculated
694 padding (@nicode{~t} or the various field widths can do similar
698 (format #f "~v_foo" 4) @result{} " foo"
702 Tab character. Parameter: @var{n}.
704 Output a tab character, or @var{n} many if a parameter is given.
707 Formfeed character. Parameter: @var{n}.
709 Output a formfeed character, or @var{n} many if a parameter is given.
712 Force output. No parameters.
714 At the end of output, call @code{force-output} to flush any buffers on
715 the destination (@pxref{Writing}). @nicode{~!} can occur anywhere in
716 the format string, but the force is done at the end of output.
718 When output is to a string (destination @code{#f}), @nicode{~!} does
721 @item @nicode{~newline} (ie.@: newline character)
722 Continuation line. No parameters.
724 Skip this newline and any following whitespace in the format string,
725 don't send it to the output. With the @nicode{:} modifier the newline
726 is not output but any further following whitespace is. With the
727 @nicode{@@} modifier the newline is output but not any following
730 This escape can be used to break up a long format string into multiple
731 lines for readability, but supress that extra whitespace.
736 ~d" 1 2) @result{} "abc1 def2"
739 @item @nicode{~(} @nicode{~)}
740 Case conversion. Between @nicode{~(} and @nicode{~)} the case of all
741 output is changed. The modifiers on @nicode{~(} control the
746 no modifiers --- lower case.
748 @c FIXME: The : and @ modifiers are not yet documented because the
749 @c code applies string-capitalize and string-capitalize-first to each
750 @c separate format:out-str call, which has various subtly doubtful
751 @c effects. And worse they're applied to individual characters,
752 @c including literal characters in the format string, which has the
753 @c silly effect of being always an upcase.
755 @c The Common Lisp spec is apparently for the capitalization to be
756 @c applied in one hit to the whole of the output between ~( and ~).
757 @c (This can no doubt be implemented without accumulating all that
758 @c text, just by keeping a state or the previous char to tell whether
762 @c @nicode{:} --- first letter of each word upper case, the rest lower
763 @c case, as per the @code{string-capitalize} function (@pxref{Alphabetic
766 @c @nicode{@@} --- first letter of just the first word upper case, the
770 @nicode{:} and @nicode{@@} together --- upper case.
776 (format #t "~(Hello~)") @print{} hello
777 (format #t "~@@:(Hello~)") @print{} HELLO
780 In the future it's intended the modifiers @nicode{:} and @nicode{@@}
781 alone will capitalize the first letters of words, as per Common Lisp
782 @code{format}, but the current implementation of this is flawed and
783 not recommended for use.
785 Case conversions do not nest, currently. This might change in the
786 future, but if it does then it will be to Common Lisp style where the
787 outermost conversion has priority, overriding inner ones (making those
790 @item @nicode{~@{} @nicode{~@}}
791 Iteration. Parameter: @var{maxreps} (for @nicode{~@{}).
793 The format between @nicode{~@{} and @nicode{~@}} is iterated. The
794 modifiers to @nicode{~@{} determine how arguments are taken. The
795 default is a list argument with each iteration successively consuming
796 elements from it. This is a convenient way to output a whole list.
799 (format #t "~@{~d~@}" '(1 2 3)) @print{} 123
800 (format #t "~@{~s=~d ~@}" '("x" 1 "y" 2)) @print{} "x"=1 "y"=2
803 With the @nicode{:} modifier a list of lists argument is taken, each
804 of those lists gives the arguments for the iterated format.
807 (format #t "~:@{~dx~d ~@}" '((1 2) (3 4) (5 6))) @print{} 1x2 3x4 5x6
810 With the @nicode{@@} modifier, the remaining arguments are used, each
811 iteration successively consuming elements.
814 (format #t "~@@@{~d~@}" 1 2 3) @print{} 123
815 (format #t "~@@@{~s=~d ~@}" "x" 1 "y" 2) @print{} "x"=1 "y"=2
818 With both @nicode{:} and @nicode{@@} modifiers, the remaining
819 arguments are used, each is a list of arguments for the format.
822 (format #t "~:@@@{~dx~d ~@}" '(1 2) '(3 4) '(5 6)) @print{} 1x2 3x4 5x6
825 Iterating stops when there are no more arguments or when the
826 @var{maxreps} parameter to @nicode{~@{} is reached (default no
830 (format #t "~2@{~d~@}" '(1 2 3 4)) @print{} 12
833 If the format between @nicode{~@{} and @nicode{~@}} is empty, then a
834 format string argument is taken (before iteration argument(s)) and
835 used instead. This allows a sub-format (like @nicode{~?} above) to be
839 (format #t "~@{~@}" "~d" '(1 2 3)) @print{} 123
842 @c FIXME: What is the @nicode{:} modifier to ~} meant to do? The
843 @c Common Lisp spec says it's a minimum of 1 iteration, but the
844 @c format.scm code seems to merely make it have MAXREPS default to 1.
846 Iterations can be nested, an inner iteration operates in the same way
847 as described, but of course on the arguments the outer iteration
848 provides it. This can be used to work into nested list structures.
849 For example in the following the inner @nicode{~@{~d~@}x} is applied
850 to @code{(1 2)} then @code{(3 4 5)} etc.
853 (format #t "~@{~@{~d~@}x~@}" '((1 2) (3 4 5))) @print{} 12x345x
856 @item @nicode{~[} @nicode{~;} @nicode{~]}
857 Conditional. Parameter: @var{selector}.
859 A conditional block is delimited by @nicode{~[} and @nicode{~]}, and
860 @nicode{~;} separates clauses within the block. @nicode{~[} takes an
861 integer argument and that number clause is used. The first clause is
865 (format #f "~[peach~;banana~;mango~]" 1) @result{} "banana"
868 The @var{selector} parameter can be used for the clause number,
869 instead of taking an argument.
872 (format #f "~2[peach~;banana~;mango~]") @result{} "mango"
875 If the clause number is out of range then nothing is output. Or the
876 last @nicode{~;} can have a @nicode{:} modifier to make it the default
877 for a number out of range.
880 (format #f "~[banana~;mango~]" 99) @result{} ""
881 (format #f "~[banana~;mango~:;fruit~]" 99) @result{} "fruit"
884 The @nicode{:} modifier to @nicode{~[} treats the argument as a flag,
885 and expects two clauses. The first used if the argument is @code{#f}
886 or the second otherwise.
889 (format #f "~:[false~;not false~]" #f) @result{} "false"
890 (format #f "~:[false~;not false~]" 'abc) @result{} "not false"
893 (format #t "~d gnu~:[s are~; is~] here" n (= 1 n)))
894 @print{} 3 gnus are here
897 The @nicode{@@} modifier to @nicode{~[} also treats the argument as a
898 flag, and expects one clause. If the argument is @code{#f} then no
899 output is produced and the argument is consumed, otherwise the clause
900 is used and the argument is not consumed by @nicode{~[}, it's left for
901 the clause. This can be used for instance to suppress output if
902 @code{#f} means something not available.
905 (format #f "~@@[temperature=~d~]" 27) @result{} "temperature=27"
906 (format #f "~@@[temperature=~d~]" #f) @result{} ""
910 Escape. Parameters: @var{val1}, @var{val2}, @var{val3}.
912 Stop formatting if there are no more arguments. This can be used for
913 instance to let a format string adapt to a variable number of
917 (format #t "~d~^ ~d" 1) @print{} 1
918 (format #t "~d~^ ~d" 1 2) @print{} 1 2
921 Within a @nicode{~@{} @nicode{~@}} iteration, @nicode{~^} stops the
922 current iteration step if there are no more arguments to that step,
923 continuing with possible further steps (for instance in the case of
924 the @nicode{:} modifier to @nicode{~@{}) and the rest of the format.
927 (format #f "~@{~d~^/~@} go" '(1 2 3)) @result{} "1/2/3 go"
928 (format #f "~:@{ ~d~^~d~@} go" '((1) (2 3))) @result{} " 1 23 go"
931 @c For reference, format.scm doesn't implement that Common Lisp ~:^
932 @c modifier which stops the entire iterating of ~:{ or ~@:{.
934 @c FIXME: Believe the Common Lisp spec is for ~^ within ~[ ~]
935 @c conditional to terminate the whole format (or iteration step if in
936 @c an iteration). But format.scm seems to terminate just the
939 @c (format #f "~[abc~^def~;ghi~] blah" 0)
940 @c @result{} "abc blah" ;; looks wrong
942 @c FIXME: Believe the Common Lisp spec is for ~^ within ~( ~) to end
943 @c that case conversion and then also terminate the whole format (or
944 @c iteration step if in an iteration). But format.scm doesn't seem
945 @c to do that quite right.
947 @c (format #f "~d ~^ ~d" 1) @result{} "1 "
948 @c (format #f "~(~d ~^ ~d~)" 1) @result{} ERROR
950 Within a @nicode{~?} sub-format, @nicode{~^} operates just on that
951 sub-format. If it terminates the sub-format then the originating
952 format will still continue.
955 (format #t "~? items" "~d~^ ~d" '(1)) @print{} 1 items
956 (format #t "~? items" "~d~^ ~d" '(1 2)) @print{} 1 2 items
959 The parameters to @nicode{~^} (which are numbers) change the condition
960 used to terminate. For a single parameter, termination is when that
961 value is zero (notice this makes plain @nicode{~^} equivalent to
962 @nicode{~#^}). For two parameters, termination is when those two are
963 equal. For three parameters, termination is when @math{@var{val1}
964 @le{} @var{val2}} and @math{@var{val2} @le{} @var{val3}}.
966 @c FIXME: Good examples of these?
969 Inquiry message. Insert a copyright message into the output. With
970 the @nicode{:} modifier insert the format implementation version.
974 It's an error if there are too many or not enough arguments for the
975 escapes in the format string. (Unwanted arguments can be skipped with
976 an argument jump @nicode{~#*} described above if desired.)
978 Iterations @nicode{~@{} @nicode{~@}} and conditionals @nicode{~[}
979 @nicode{~;} @nicode{~]} can be nested, but must be properly nested,
980 meaning the inner form must be entirely within the outer form. So
981 it's not possible, for instance, to try to conditionalize the endpoint
985 (format #t "~@{ ~[ ... ~] ~@}" ...) ;; good
986 (format #t "~@{ ~[ ... ~@} ... ~]" ...) ;; bad
989 The same applies to case conversions @nicode{~(} @nicode{~)}, they
990 must properly nest with respect to iterations and conditionals (though
991 currently a case conversion cannot nest within another case
994 When a sub-format (@nicode{~?}) is used, that sub-format string must
995 be self-contained. It cannot for instance give a @nicode{~@{} to
996 begin an iteration form and have the @nicode{~@}} up in the
997 originating format, or similar.
1001 Guile contains a @code{format} procedure even when the module
1002 @code{(ice-9 format)} is not loaded. The default @code{format} is
1003 @code{simple-format} (@pxref{Writing}), it doesn't support all escape
1004 sequences documented in this section, and will signal an error if you
1005 try to use one of them. The reason for two versions is that the full
1006 @code{format} is fairly large and requires some time to load.
1007 @code{simple-format} is often adequate too.
1012 @section The Rx Regular Expression Library
1014 [FIXME: this is taken from Gary and Mark's quick summaries and should be
1015 reviewed and expanded. Rx is pretty stable, so could already be done!]
1018 @cindex finite automaton
1020 The @file{guile-lang-allover} package provides an interface to Tom
1021 Lord's Rx library (currently only to POSIX regular expressions). Use of
1022 the library requires a two step process: compile a regular expression
1023 into an efficient structure, then use the structure in any number of
1026 For example, given the regular expression @samp{abc.} (which matches any
1027 string containing @samp{abc} followed by any single character):
1030 guile> @kbd{(define r (regcomp "abc."))}
1033 guile> @kbd{(regexec r "abc")}
1035 guile> @kbd{(regexec r "abcd")}
1040 The definitions of @code{regcomp} and @code{regexec} are as follows:
1042 @deffn {Scheme Procedure} regcomp pattern [flags]
1043 Compile the regular expression pattern using POSIX rules. Flags is
1044 optional and should be specified using symbolic names:
1045 @defvar REG_EXTENDED
1046 use extended POSIX syntax
1049 use case-insensitive matching
1052 allow anchors to match after newline characters in the
1053 string and prevents @code{.} or @code{[^...]} from matching newlines.
1056 The @code{logior} procedure can be used to combine multiple flags.
1057 The default is to use
1058 POSIX basic syntax, which makes @code{+} and @code{?} literals and @code{\+}
1060 operators. Backslashes in @var{pattern} must be escaped if specified in a
1061 literal string e.g., @code{"\\(a\\)\\?"}.
1064 @deffn {Scheme Procedure} regexec regex string [match-pick] [flags]
1065 Match @var{string} against the compiled POSIX regular expression
1067 @var{match-pick} and @var{flags} are optional. Possible flags (which can be
1068 combined using the logior procedure) are:
1071 The beginning of line operator won't match the beginning of
1072 @var{string} (presumably because it's not the beginning of a line)
1076 Similar to REG_NOTBOL, but prevents the end of line operator
1077 from matching the end of @var{string}.
1080 If no match is possible, regexec returns #f. Otherwise @var{match-pick}
1081 determines the return value:
1083 @code{#t} or unspecified: a newly-allocated vector is returned,
1084 containing pairs with the indices of the matched part of @var{string} and any
1087 @code{""}: a list is returned: the first element contains a nested list
1088 with the matched part of @var{string} surrounded by the the unmatched parts.
1089 Remaining elements are matched substrings (if any). All returned
1090 substrings share memory with @var{string}.
1092 @code{#f}: regexec returns #t if a match is made, otherwise #f.
1094 vector: the supplied vector is returned, with the first element replaced
1095 by a pair containing the indices of the matched portion of @var{string} and
1096 further elements replaced by pairs containing the indices of matched
1097 substrings (if any).
1099 list: a list will be returned, with each member of the list
1100 specified by a code in the corresponding position of the supplied list:
1102 a number: the numbered matching substring (0 for the entire match).
1104 @code{#\<}: the beginning of @var{string} to the beginning of the part matched
1107 @code{#\>}: the end of the matched part of @var{string} to the end of
1110 @code{#\c}: the "final tag", which seems to be associated with the "cut
1111 operator", which doesn't seem to be available through the posix
1114 e.g., @code{(list #\< 0 1 #\>)}. The returned substrings share memory with
1118 Here are some other procedures that might be used when using regular
1121 @deffn {Scheme Procedure} compiled-regexp? obj
1122 Test whether obj is a compiled regular expression.
1125 @deffn {Scheme Procedure} regexp->dfa regex [flags]
1128 @deffn {Scheme Procedure} dfa-fork dfa
1131 @deffn {Scheme Procedure} reset-dfa! dfa
1134 @deffn {Scheme Procedure} dfa-final-tag dfa
1137 @deffn {Scheme Procedure} dfa-continuable? dfa
1140 @deffn {Scheme Procedure} advance-dfa! dfa string
1144 @node File Tree Walk
1145 @section File Tree Walk
1146 @cindex file tree walk
1148 The functions in this section traverse a tree of files and
1149 directories, in a fashion similar to the C @code{ftw} and @code{nftw}
1150 routines (@pxref{Working with Directory Trees,,, libc, GNU C Library
1154 (use-modules (ice-9 ftw))
1158 @defun ftw startname proc ['hash-size n]
1159 Walk the filesystem tree descending from @var{startname}, calling
1160 @var{proc} for each file and directory.
1162 Hard links and symbolic links are followed. A file or directory is
1163 reported to @var{proc} only once, and skipped if seen again in another
1164 place. One consequence of this is that @code{ftw} is safe against
1165 circularly linked directory structures.
1167 Each @var{proc} call is @code{(@var{proc} filename statinfo flag)} and
1168 it should return @code{#t} to continue, or any other value to stop.
1170 @var{filename} is the item visited, being @var{startname} plus a
1171 further path and the name of the item. @var{statinfo} is the return
1172 from @code{stat} (@pxref{File System}) on @var{filename}. @var{flag}
1173 is one of the following symbols,
1177 @var{filename} is a file, this includes special files like devices,
1181 @var{filename} is a directory.
1184 An error occurred when calling @code{stat}, so nothing is known.
1185 @var{statinfo} is @code{#f} in this case.
1187 @item directory-not-readable
1188 @var{filename} is a directory, but one which cannot be read and hence
1189 won't be recursed into.
1192 @var{filename} is a dangling symbolic link. Symbolic links are
1193 normally followed and their target reported, the link itself is
1194 reported if the target does not exist.
1197 The return value from @code{ftw} is @code{#t} if it ran to completion,
1198 or otherwise the non-@code{#t} value from @var{proc} which caused the
1201 Optional argument symbol @code{hash-size} and an integer can be given
1202 to set the size of the hash table used to track items already visited.
1203 (@pxref{Hash Table Reference})
1205 @c Actually, it's probably safe to escape from ftw, just need to
1208 In the current implementation, returning non-@code{#t} from @var{proc}
1209 is the only valid way to terminate @code{ftw}. @var{proc} must not
1210 use @code{throw} or similar to escape.
1214 @defun nftw startname proc ['chdir] ['depth] ['hash-size n] ['mount] ['physical]
1215 Walk the filesystem tree starting at @var{startname}, calling
1216 @var{proc} for each file and directory. @code{nftw} has extra
1217 features over the basic @code{ftw} described above.
1219 Hard links and symbolic links are followed, but a file or directory is
1220 reported to @var{proc} only once, and skipped if seen again in another
1221 place. One consequence of this is that @code{nftw} is safe against
1222 circular linked directory structures.
1224 Each @var{proc} call is @code{(@var{proc} filename statinfo flag
1225 basename level)} and it should return @code{#t} to continue, or any
1226 other value to stop.
1228 @var{filename} is the item visited, being @var{startname} plus a
1229 further path and the name of the item. @var{statinfo} is the return
1230 from @code{stat} on @var{filename} (@pxref{File System}).
1231 @var{basename} it the item name without any path. @var{level} is an
1232 integer giving the directory nesting level, starting from 0 for the
1233 contents of @var{startname} (or that item itself if it's a file).
1234 @var{flag} is one of the following symbols,
1238 @var{filename} is a file, this includes special files like devices,
1242 @var{filename} is a directory.
1244 @item directory-processed
1245 @var{filename} is a directory, and its contents have all been visited.
1246 This flag is given instead of @code{directory} when the @code{depth}
1247 option below is used.
1250 An error occurred when applying @code{stat} to @var{filename}, so
1251 nothing is known about it. @var{statinfo} is @code{#f} in this case.
1253 @item directory-not-readable
1254 @var{filename} is a directory, but one which cannot be read and hence
1255 won't be recursed into.
1258 @var{filename} is a dangling symbolic link. Symbolic links are
1259 normally followed and their target reported, the link itself is
1260 reported if the target does not exist.
1262 Under the @code{physical} option described below, @code{symlink} is
1263 instead given for symbolic links whose target does exist.
1266 Under the @code{physical} option described below, this indicates
1267 @var{filename} is a dangling symbolic link, meaning its target does
1268 not exist. Without the @code{physical} option plain @code{symlink}
1272 The following optional arguments can be given to modify the way
1273 @code{nftw} works. Each is passed as a symbol (and @code{hash-size}
1274 takes a following integer value).
1278 Change to the directory containing the item before calling @var{proc}.
1279 When @code{nftw} returns the original current directory is restored.
1281 Under this option, generally the @var{basename} parameter should be
1282 used to access the item in each @var{proc} call. The @var{filename}
1283 parameter still has a path as normal and this will only be valid if
1284 the @var{startname} directory was absolute.
1287 Visit files ``depth first'', meaning @var{proc} is called for the
1288 contents of each directory before it's called for the directory
1289 itself. Normally a directory is reported first, then its contents.
1291 Under this option, the @var{flag} to @var{proc} for a directory is
1292 @code{directory-processed} instead of @code{directory}.
1294 @item @code{hash-size @var{n}}
1295 Set the size of the hash table used to track items already visited.
1296 (@pxref{Hash Table Reference})
1299 Don't cross a mount point, meaning only visit items on the same
1300 filesystem as @var{startname}. (Ie.@: the same @code{stat:dev}.)
1302 @item @code{physical}
1303 Don't follow symbolic links, instead report them to @var{proc} as
1304 @code{symlink}, and report dangling links as @code{stale-symlink}.
1307 The return value from @code{nftw} is @code{#t} if it ran to
1308 completion, or otherwise the non-@code{#t} value from @var{proc} which
1311 @c For reference, one reason not to esacpe is that the current
1312 @c directory is not saved and restored with dynamic-wind. Maybe
1313 @c changing that would be enough to allow escaping.
1315 In the current implementation, returning non-@code{#t} from @var{proc}
1316 is the only valid way to terminate @code{ftw}. @var{proc} must not
1317 use @code{throw} or similar to escape.
1327 The functions in this section are provided by
1330 (use-modules (ice-9 q))
1333 This module implements queues holding arbitrary scheme objects and
1334 designed for efficient first-in / first-out operations.
1336 @code{make-q} creates a queue, and objects are entered and removed
1337 with @code{enq!} and @code{deq!}. @code{q-push!} and @code{q-pop!}
1338 can be used too, treating the front of the queue like a stack.
1342 @deffn {Scheme Procedure} make-q
1346 @deffn {Scheme Procedure} q? obj
1347 Return @code{#t} if @var{obj} is a queue, or @code{#f} if not.
1349 Note that queues are not a distinct class of objects but are
1350 implemented with cons cells. For that reason certain list structures
1351 can get @code{#t} from @code{q?}.
1354 @deffn {Scheme Procedure} enq! q obj
1355 Add @var{obj} to the rear of @var{q}, and return @var{q}.
1358 @deffn {Scheme Procedure} deq! q
1359 @deffnx {Scheme Procedure} q-pop! q
1360 Remove and return the front element from @var{q}. If @var{q} is
1361 empty, a @code{q-empty} exception is thrown.
1363 @code{deq!} and @code{q-pop!} are the same operation, the two names
1364 just let an application match @code{enq!} with @code{deq!}, or
1365 @code{q-push!} with @code{q-pop!}.
1368 @deffn {Scheme Procedure} q-push! q obj
1369 Add @var{obj} to the front of @var{q}, and return @var{q}.
1372 @deffn {Scheme Procedure} q-length q
1373 Return the number of elements in @var{q}.
1376 @deffn {Scheme Procedure} q-empty? q
1377 Return true if @var{q} is empty.
1380 @deffn {Scheme Procedure} q-empty-check q
1381 Throw a @code{q-empty} exception if @var{q} is empty.
1384 @deffn {Scheme Procedure} q-front q
1385 Return the first element of @var{q} (without removing it). If @var{q}
1386 is empty, a @code{q-empty} exception is thrown.
1389 @deffn {Scheme Procedure} q-rear q
1390 Return the last element of @var{q} (without removing it). If @var{q}
1391 is empty, a @code{q-empty} exception is thrown.
1394 @deffn {Scheme Procedure} q-remove! q obj
1395 Remove all occurences of @var{obj} from @var{q}, and return @var{q}.
1396 @var{obj} is compared to queue elements using @code{eq?}.
1400 @cindex @code{q-empty}
1401 The @code{q-empty} exceptions described above are thrown just as
1402 @code{(throw 'q-empty)}, there's no message etc like an error throw.
1404 A queue is implemented as a cons cell, the @code{car} containing a
1405 list of queued elements, and the @code{cdr} being the last cell in
1406 that list (for ease of enqueuing).
1409 (@var{list} . @var{last-cell})
1413 If the queue is empty, @var{list} is the empty list and
1414 @var{last-cell} is @code{#f}.
1416 An application can directly access the queue list if desired, for
1417 instance to search the elements or to insert at a specific point.
1419 @deffn {Scheme Procedure} sync-q! q
1420 Recompute the @var{last-cell} field in @var{q}.
1422 All the operations above maintain @var{last-cell} as described, so
1423 normally there's no need for @code{sync-q!}. But if an application
1424 modifies the queue @var{list} then it must either maintain
1425 @var{last-cell} similarly, or call @code{sync-q!} to recompute it.
1430 @c TeX-master: "guile.texi"