2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2009,
4 @c 2010, 2011, 2012 Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
8 @section Pretty Printing
10 @c FIXME::martin: Review me!
12 @cindex pretty printing
13 The module @code{(ice-9 pretty-print)} provides the procedure
14 @code{pretty-print}, which provides nicely formatted output of Scheme
15 objects. This is especially useful for deeply nested or complex data
16 structures, such as lists and vectors.
18 The module is loaded by entering the following:
21 (use-modules (ice-9 pretty-print))
24 This makes the procedure @code{pretty-print} available. As an example
25 how @code{pretty-print} will format the output, see the following:
28 (pretty-print '(define (foo) (lambda (x)
29 (cond ((zero? x) #t) ((negative? x) -x) (else
30 (if (= x 1) 2 (* x x x)))))))
36 (else (if (= x 1) 2 (* x x x))))))
39 @deffn {Scheme Procedure} pretty-print obj [port] [keyword-options]
40 Print the textual representation of the Scheme object @var{obj} to
41 @var{port}. @var{port} defaults to the current output port, if not
44 The further @var{keyword-options} are keywords and parameters as
48 @item @nicode{#:display?} @var{flag}
49 If @var{flag} is true then print using @code{display}. The default is
50 @code{#f} which means use @code{write} style. (@pxref{Writing})
52 @item @nicode{#:per-line-prefix} @var{string}
53 Print the given @var{string} as a prefix on each line. The default is
56 @item @nicode{#:width} @var{columns}
57 Print within the given @var{columns}. The default is 79.
62 @cindex truncated printing
63 Also exported by the @code{(ice-9 pretty-print)} module is
64 @code{truncated-print}, a procedure to print Scheme datums, truncating
65 the output to a certain number of characters. This is useful when you
66 need to present an arbitrary datum to the user, but you only have one
67 line in which to do so.
70 (define exp '(a b #(c d e) f . g))
71 (truncated-print exp #:width 10) (newline)
73 (truncated-print exp #:width 15) (newline)
74 @print{} (a b # f . g)
75 (truncated-print exp #:width 18) (newline)
76 @print{} (a b #(c ...) . #)
77 (truncated-print exp #:width 20) (newline)
78 @print{} (a b #(c d e) f . g)
79 (truncated-print "The quick brown fox" #:width 20) (newline)
80 @print{} "The quick brown..."
81 (truncated-print (current-module) #:width 20) (newline)
82 @print{} #<directory (gui...>
85 @code{truncated-print} will not output a trailing newline. If an expression does
86 not fit in the given width, it will be truncated -- possibly
87 ellipsized@footnote{On Unicode-capable ports, the ellipsis is represented by
88 character `HORIZONTAL ELLIPSIS' (U+2026), otherwise it is represented by three
89 dots.}, or in the worst case, displayed as @nicode{#}.
91 @deffn {Scheme Procedure} truncated-print obj [port] [keyword-options]
92 Print @var{obj}, truncating the output, if necessary, to make it fit
93 into @var{width} characters. By default, @var{obj} will be printed using
94 @code{write}, though that behavior can be overridden via the
95 @var{display?} keyword argument.
97 The default behaviour is to print depth-first, meaning that the entire
98 remaining width will be available to each sub-expression of @var{obj} --
99 e.g., if @var{obj} is a vector, each member of @var{obj}. One can attempt to
100 ``ration'' the available width, trying to allocate it equally to each
101 sub-expression, via the @var{breadth-first?} keyword argument.
103 The further @var{keyword-options} are keywords and parameters as
107 @item @nicode{#:display?} @var{flag}
108 If @var{flag} is true then print using @code{display}. The default is
109 @code{#f} which means use @code{write} style. (@pxref{Writing})
111 @item @nicode{#:width} @var{columns}
112 Print within the given @var{columns}. The default is 79.
114 @item @nicode{#:breadth-first?} @var{flag}
115 If @var{flag} is true, then allocate the available width breadth-first
116 among elements of a compound data structure (list, vector, pair,
117 etc.). The default is @code{#f} which means that any element is
118 allowed to consume all of the available width.
123 @node Formatted Output
124 @section Formatted Output
125 @cindex formatted output
127 @c For reference, in this section escapes like ~a are given in
128 @c @nicode, to give code font in TeX etc, but leave them unadorned in
131 @c The idea is to reduce clutter around what's shown, and avoid any
132 @c possible confusion over whether the ` ' quotes are part of what
133 @c should be entered. (In particular for instance of course ' is
134 @c meaningful in a format string, introducing a char parameter).
136 The @code{format} function is a powerful way to print numbers, strings
137 and other objects together with literal text under the control of a
138 format string. This function is available from
141 (use-modules (ice-9 format))
144 A format string is generally more compact and easier than using just
145 the standard procedures like @code{display}, @code{write} and
146 @code{newline}. Parameters in the output string allow various output
147 styles, and parameters can be taken from the arguments for runtime
150 @code{format} is similar to the Common Lisp procedure of the same
151 name, but it's not identical and doesn't have quite all the features
152 found in Common Lisp.
154 C programmers will note the similarity between @code{format} and
155 @code{printf}, though escape sequences are marked with @nicode{~}
156 instead of @nicode{%}, and are more powerful.
159 @deffn {Scheme Procedure} format dest fmt arg @dots{}
160 Write output specified by the @var{fmt} string to @var{dest}.
161 @var{dest} can be an output port, @code{#t} for
162 @code{current-output-port} (@pxref{Default Ports}), or @code{#f} to
163 return the output as a string.
165 @var{fmt} can contain literal text to be output, and @nicode{~}
166 escapes. Each escape has the form
169 ~ [param [, param@dots{}] [:] [@@] code
172 @nicode{code} is a character determining the escape sequence. The
173 @nicode{:} and @nicode{@@} characters are optional modifiers, one or
174 both of which change the way various codes operate. Optional
175 parameters are accepted by some codes too. Parameters have the
179 @item @nicode{[+/-]number}
180 An integer, with optional @nicode{+} or @nicode{-}.
181 @item @nicode{'} (apostrophe)
182 The following character in the format string, for instance @nicode{'z}
185 The next function argument as the parameter. @nicode{v} stands for
186 ``variable'', a parameter can be calculated at runtime and included in
187 the arguments. Upper case @nicode{V} can be used too.
189 The number of arguments remaining. (See @nicode{~*} below for some
193 Parameters are separated by commas (@nicode{,}). A parameter can be
194 left empty to keep its default value when supplying later parameters.
197 The following escapes are available. The code letters are not
198 case-sensitive, upper and lower case are the same.
203 Object output. Parameters: @var{minwidth}, @var{padinc},
204 @var{minpad}, @var{padchar}.
206 @nicode{~a} outputs an argument like @code{display}, @nicode{~s}
207 outputs an argument like @code{write} (@pxref{Writing}).
210 (format #t "~a" "foo") @print{} foo
211 (format #t "~s" "foo") @print{} "foo"
214 @nicode{~:a} and @nicode{~:s} put objects that don't have an external
215 representation in quotes like a string.
218 (format #t "~:a" car) @print{} "#<primitive-procedure car>"
221 If the output is less than @var{minwidth} characters (default 0), it's
222 padded on the right with @var{padchar} (default space). @nicode{~@@a}
223 and @nicode{~@@s} put the padding on the left instead.
226 (format #f "~5a" 'abc) @result{} "abc "
227 (format #f "~5,,,'-@@a" 'abc) @result{} "--abc"
230 @var{minpad} is a minimum for the padding then plus a multiple of
231 @var{padinc}. Ie.@: the padding is @math{@var{minpad} + @var{N} *
232 @var{padinc}}, where @var{n} is the smallest integer making the total
233 object plus padding greater than or equal to @var{minwidth}. The
234 default @var{minpad} is 0 and the default @var{padinc} is 1 (imposing
235 no minimum or multiple).
238 (format #f "~5,1,4a" 'abc) @result{} "abc "
242 Character. Parameter: @var{charnum}.
244 Output a character. The default is to simply output, as per
245 @code{write-char} (@pxref{Writing}). @nicode{~@@c} prints in
246 @code{write} style. @nicode{~:c} prints control characters (ASCII 0
247 to 31) in @nicode{^X} form.
250 (format #t "~c" #\z) @print{} z
251 (format #t "~@@c" #\z) @print{} #\z
252 (format #t "~:c" #\newline) @print{} ^J
255 If the @var{charnum} parameter is given then an argument is not taken
256 but instead the character is @code{(integer->char @var{charnum})}
257 (@pxref{Characters}). This can be used for instance to output
258 characters given by their ASCII code.
261 (format #t "~65c") @print{} A
268 Integer. Parameters: @var{minwidth}, @var{padchar}, @var{commachar},
271 Output an integer argument as a decimal, hexadecimal, octal or binary
272 integer (respectively), in a locale-independent way.
275 (format #t "~d" 123) @print{} 123
278 @nicode{~@@d} etc shows a @nicode{+} sign is shown on positive
281 @c FIXME: "+" is not shown on zero, unlike in Common Lisp. Should
282 @c that be changed in the code, or is it too late and should just be
283 @c documented that way?
286 (format #t "~@@b" 12) @print{} +1100
289 If the output is less than the @var{minwidth} parameter (default no
290 minimum), it's padded on the left with the @var{padchar} parameter
294 (format #t "~5,'*d" 12) @print{} ***12
295 (format #t "~5,'0d" 12) @print{} 00012
296 (format #t "~3d" 1234) @print{} 1234
299 @nicode{~:d} adds commas (or the @var{commachar} parameter) every
300 three digits (or the @var{commawidth} parameter many). However, when
301 your intent is to write numbers in a way that follows typographical
302 conventions, using @nicode{~h} is recommended.
305 (format #t "~:d" 1234567) @print{} 1,234,567
306 (format #t "~10,'*,'/,2:d" 12345) @print{} ***1/23/45
309 Hexadecimal @nicode{~x} output is in lower case, but the @nicode{~(}
310 and @nicode{~)} case conversion directives described below can be used
314 (format #t "~x" 65261) @print{} feed
315 (format #t "~:@@(~x~)" 65261) @print{} FEED
319 Integer in words, roman numerals, or a specified radix. Parameters:
320 @var{radix}, @var{minwidth}, @var{padchar}, @var{commachar},
323 With no parameters output is in words as a cardinal like ``ten'', or
324 @nicode{~:r} prints an ordinal like ``tenth''.
327 (format #t "~r" 9) @print{} nine ;; cardinal
328 (format #t "~r" -9) @print{} minus nine ;; cardinal
329 (format #t "~:r" 9) @print{} ninth ;; ordinal
332 And also with no parameters, @nicode{~@@r} gives roman numerals and
333 @nicode{~:@@r} gives old roman numerals. In old roman numerals
334 there's no ``subtraction'', so 9 is @nicode{VIIII} instead of
335 @nicode{IX}. In both cases only positive numbers can be output.
338 (format #t "~@@r" 89) @print{} LXXXIX ;; roman
339 (format #t "~:@@r" 89) @print{} LXXXVIIII ;; old roman
342 When a parameter is given it means numeric output in the specified
343 @var{radix}. The modifiers and parameters following the radix are the
344 same as described for @nicode{~d} etc above.
347 (format #f "~3r" 27) @result{} "1000" ;; base 3
348 (format #f "~3,5r" 26) @result{} " 222" ;; base 3 width 5
352 Fixed-point float. Parameters: @var{width}, @var{decimals},
353 @var{scale}, @var{overflowchar}, @var{padchar}.
355 Output a number or number string in fixed-point format, ie.@: with a
359 (format #t "~f" 5) @print{} 5.0
360 (format #t "~f" "123") @print{} 123.0
361 (format #t "~f" "1e-1") @print{} 0.1
364 @nicode{~@@f} prints a @nicode{+} sign on positive numbers (including
368 (format #t "~@@f" 0) @print{} +0.0
371 If the output is less than @var{width} characters it's padded on the
372 left with @var{padchar} (space by default). If the output equals or
373 exceeds @var{width} then there's no padding. The default for
374 @var{width} is no padding.
377 (format #f "~6f" -1.5) @result{} " -1.5"
378 (format #f "~6,,,,'*f" 23) @result{} "**23.0"
379 (format #f "~6f" 1234567.0) @result{} "1234567.0"
382 @var{decimals} is how many digits to print after the decimal point,
383 with the value rounded or padded with zeros as necessary. (The
384 default is to output as many decimals as required.)
387 (format #t "~1,2f" 3.125) @print{} 3.13
388 (format #t "~1,2f" 1.5) @print{} 1.50
391 @var{scale} is a power of 10 applied to the value, moving the decimal
392 point that many places. A positive @var{scale} increases the value
393 shown, a negative decreases it.
396 (format #t "~,,2f" 1234) @print{} 123400.0
397 (format #t "~,,-2f" 1234) @print{} 12.34
400 If @var{overflowchar} and @var{width} are both given and if the output
401 would exceed @var{width}, then that many @var{overflowchar}s are
402 printed instead of the value.
405 (format #t "~6,,,'xf" 12345) @print{} 12345.
406 (format #t "~5,,,'xf" 12345) @print{} xxxxx
410 Localized number@footnote{The @nicode{~h} format specifier first
411 appeared in Guile version 2.0.6.}. Parameters: @var{width},
412 @var{decimals}, @var{padchar}.
414 Like @nicode{~f}, output an exact or floating point number, but do so
415 according to the current locale, or according to the given locale object
416 when the @code{:} modifier is used (@pxref{Number Input and Output,
417 @code{number->locale-string}}).
420 (format #t "~h" 12345.5678) ; with "C" as the current locale
423 (format #t "~14,,'*:h" 12345.5678
424 (make-locale LC_ALL "en_US"))
425 @print{} ***12,345.5678
427 (format #t "~,2:h" 12345.5678
428 (make-locale LC_NUMERIC "fr_FR"))
433 Exponential float. Parameters: @var{width}, @var{mantdigits},
434 @var{expdigits}, @var{intdigits}, @var{overflowchar}, @var{padchar},
437 Output a number or number string in exponential notation.
440 (format #t "~e" 5000.25) @print{} 5.00025E+3
441 (format #t "~e" "123.4") @print{} 1.234E+2
442 (format #t "~e" "1e4") @print{} 1.0E+4
445 @nicode{~@@e} prints a @nicode{+} sign on positive numbers (including
446 zero). (This is for the mantissa, a @nicode{+} or @nicode{-} sign is
447 always shown on the exponent.)
450 (format #t "~@@e" 5000.0) @print{} +5.0E+3
453 If the output is less than @var{width} characters it's padded on the
454 left with @var{padchar} (space by default). The default for
455 @var{width} is to output with no padding.
458 (format #f "~10e" 1234.0) @result{} " 1.234E+3"
459 (format #f "~10,,,,,'*e" 0.5) @result{} "****5.0E-1"
462 @c FIXME: Describe what happens when the number is bigger than WIDTH.
463 @c There seems to be a bit of dodginess about this, or some deviation
466 @var{mantdigits} is the number of digits shown in the mantissa after
467 the decimal point. The value is rounded or trailing zeros are added
468 as necessary. The default @var{mantdigits} is to show as much as
472 (format #f "~,3e" 11111.0) @result{} "1.111E+4"
473 (format #f "~,8e" 123.0) @result{} "1.23000000E+2"
476 @var{expdigits} is the minimum number of digits shown for the
477 exponent, with leading zeros added if necessary. The default for
478 @var{expdigits} is to show only as many digits as required. At least
479 1 digit is always shown.
482 (format #f "~,,1e" 1.0e99) @result{} "1.0E+99"
483 (format #f "~,,6e" 1.0e99) @result{} "1.0E+000099"
486 @var{intdigits} (default 1) is the number of digits to show before the
487 decimal point in the mantissa. @var{intdigits} can be zero, in which
488 case the integer part is a single @nicode{0}, or it can be negative,
489 in which case leading zeros are shown after the decimal point.
491 @c FIXME: When INTDIGITS is 0, Common Lisp format apparently only
492 @c shows the single 0 digit if it fits in WIDTH. format.scm seems to
493 @c show it always. Is it meant to?
496 (format #t "~,,,3e" 12345.0) @print{} 123.45E+2
497 (format #t "~,,,0e" 12345.0) @print{} 0.12345E+5
498 (format #t "~,,,-3e" 12345.0) @print{} 0.00012345E+8
501 @c FIXME: MANTDIGITS with negative INTDIGITS doesn't match CL spec,
502 @c believe the spec says it ought to still show mantdigits+1 sig
503 @c figures, i.e. leading zeros don't count towards MANTDIGITS, but it
504 @c seems to just treat MANTDIGITS as how many digits after the
507 If @var{overflowchar} is given then @var{width} is a hard limit. If
508 the output would exceed @var{width} then instead that many
509 @var{overflowchar}s are printed.
512 (format #f "~6,,,,'xe" 100.0) @result{} "1.0E+2"
513 (format #f "~3,,,,'xe" 100.0) @result{} "xxx"
516 @var{expchar} is the exponent marker character (default @nicode{E}).
519 (format #t "~,,,,,,'ee" 100.0) @print{} 1.0e+2
523 General float. Parameters: @var{width}, @var{mantdigits},
524 @var{expdigits}, @var{intdigits}, @var{overflowchar}, @var{padchar},
527 Output a number or number string in either exponential format the same
528 as @nicode{~e}, or fixed-point format like @nicode{~f} but aligned
529 where the mantissa would have been and followed by padding where the
530 exponent would have been.
532 @c FIXME: The default MANTDIGITS is apparently max(needed,min(n,7))
533 @c where 10^(n-1)<=abs(x)<=10^n. But the Common Lisp spec seems to
534 @c ask for "needed" to be without leading or trailing zeros, whereas
535 @c format.scm seems to include trailing zeros, ending up with it
536 @c using fixed format for bigger values than it should.
538 Fixed-point is used when the absolute value is 0.1 or more and it
539 takes no more space than the mantissa in exponential format, ie.@:
540 basically up to @var{mantdigits} digits.
543 (format #f "~12,4,2g" 999.0) @result{} " 999.0 "
544 (format #f "~12,4,2g" "100000") @result{} " 1.0000E+05"
547 The parameters are interpreted as per @nicode{~e} above. When
548 fixed-point is used, the @var{decimals} parameter to @nicode{~f} is
549 established from @var{mantdigits}, so as to give a total
550 @math{@var{mantdigits}+1} figures.
553 Monetary style fixed-point float. Parameters: @var{decimals},
554 @var{intdigits}, @var{width}, @var{padchar}.
556 @c For reference, fmtdoc.txi from past versions of slib showed the
557 @c INTDIGITS parameter as SCALE. That looks like a typo, in the code
558 @c and in the Common Lisp spec it's a minimum digits for the integer
559 @c part, it isn't a power of 10 like in ~f.
561 Output a number or number string in fixed-point format, ie.@: with a
562 decimal point. @var{decimals} is the number of decimal places to
566 (format #t "~$" 5) @print{} 5.00
567 (format #t "~4$" "2.25") @print{} 2.2500
568 (format #t "~4$" "1e-2") @print{} 0.0100
571 @nicode{~@@$} prints a @nicode{+} sign on positive numbers (including
575 (format #t "~@@$" 0) @print{} +0.00
578 @var{intdigits} is a minimum number of digits to show in the integer
579 part of the value (default 1).
582 (format #t "~,3$" 9.5) @print{} 009.50
583 (format #t "~,0$" 0.125) @print{} .13
586 If the output is less than @var{width} characters (default 0), it's
587 padded on the left with @var{padchar} (default space). @nicode{~:$}
588 puts the padding after the sign.
591 (format #f "~,,8$" -1.5) @result{} " -1.50"
592 (format #f "~,,8:$" -1.5) @result{} "- 1.50"
593 (format #f "~,,8,'.:@@$" 3) @result{} "+...3.00"
596 Note that floating point for dollar amounts is generally not a good
597 idea, because a cent @math{0.01} cannot be represented exactly in the
598 binary floating point Guile uses, which leads to slowly accumulating
599 rounding errors. Keeping values as cents (or fractions of a cent) in
600 integers then printing with the scale option in @nicode{~f} may be a
603 @c For reference, fractions don't work with ~$ (or any of the float
604 @c conversions) currently. If they did work then we could perhaps
605 @c suggest keeping dollar amounts as rationals, which would of course
606 @c give exact cents. An integer as cents is probably still a better
607 @c recommendation though, since it forces one to think about where
608 @c and when rounding can or should occur.
611 Complex fixed-point float. Parameters: @var{width}, @var{decimals},
612 @var{scale}, @var{overflowchar}, @var{padchar}.
614 @c For reference, in Common Lisp ~i is an indent, but slib fmtdoc.txi
615 @c described it as complex number output, so we keep that.
617 Output the argument as a complex number, with both real and imaginary
618 part shown (even if one or both are zero).
620 The parameters and modifiers are the same as for fixed-point
621 @nicode{~f} described above. The real and imaginary parts are both
622 output with the same given parameters and modifiers, except that for
623 the imaginary part the @nicode{@@} modifier is always enabled, so as
624 to print a @nicode{+} sign between the real and imaginary parts.
627 (format #t "~i" 1) @print{} 1.0+0.0i
631 Plural. No parameters.
633 Output nothing if the argument is 1, or @samp{s} for any other
637 (format #t "enter name~p" 1) @print{} enter name
638 (format #t "enter name~p" 2) @print{} enter names
641 @nicode{~@@p} prints @samp{y} for 1 or @samp{ies} otherwise.
644 (format #t "pupp~@@p" 1) @print{} puppy
645 (format #t "pupp~@@p" 2) @print{} puppies
648 @nicode{~:p} re-uses the preceding argument instead of taking a new
649 one, which can be convenient when printing some sort of count.
652 (format #t "~d cat~:p" 9) @print{} 9 cats
653 (format #t "~d pupp~:@@p" 5) @print{} 5 puppies
656 @nicode{~p} is designed for English plurals and there's no attempt to
657 support other languages. @nicode{~[} conditionals (below) may be able
658 to help. When using @code{gettext} to translate messages
659 @code{ngettext} is probably best though
660 (@pxref{Internationalization}).
663 Structured printing. Parameters: @var{width}.
665 @nicode{~y} outputs an argument using @code{pretty-print}
666 (@pxref{Pretty Printing}). The result will be formatted to fit within
667 @var{width} columns (79 by default), consuming multiple lines if
670 @nicode{~@@y} outputs an argument using @code{truncated-print}
671 (@pxref{Pretty Printing}). The resulting code will be formatted to fit
672 within @var{width} columns (79 by default), on a single line. The
673 output will be truncated if necessary.
675 @nicode{~:@@y} is like @nicode{~@@y}, except the @var{width} parameter
676 is interpreted to be the maximum column to which to output. That is to
677 say, if you are at column 10, and @nicode{~60:@@y} is seen, the datum
678 will be truncated to 50 columns.
682 Sub-format. No parameters.
684 Take a format string argument and a second argument which is a list of
685 arguments for that string, and output the result.
688 (format #t "~?" "~d ~d" '(1 2)) @print{} 1 2
691 @nicode{~@@?} takes arguments for the sub-format directly rather than
695 (format #t "~@@? ~s" "~d ~d" 1 2 "foo") @print{} 1 2 "foo"
698 @nicode{~?} and @nicode{~k} are the same, @nicode{~k} is provided for
699 T-Scheme compatibility.
702 Argument jumping. Parameter: @var{N}.
704 Move forward @var{N} arguments (default 1) in the argument list.
705 @nicode{~:*} moves backwards. (@var{N} cannot be negative.)
708 (format #f "~d ~2*~d" 1 2 3 4) @result{} "1 4"
709 (format #f "~d ~:*~d" 6) @result{} "6 6"
712 @nicode{~@@*} moves to argument number @var{N}. The first argument is
713 number 0 (and that's the default for @var{N}).
716 (format #f "~d~d again ~@@*~d~d" 1 2) @result{} "12 again 12"
717 (format #f "~d~d~d ~1@@*~d~d" 1 2 3) @result{} "123 23"
720 A @nicode{#} move to the end followed by a @nicode{:} modifier move
721 back can be used for an absolute position relative to the end of the
722 argument list, a reverse of what the @nicode{@@} modifier does.
725 (format #t "~#*~2:*~a" 'a 'b 'c 'd) @print{} c
728 At the end of the format string the current argument position doesn't
729 matter, any further arguments are ignored.
732 Advance to a column position. Parameters: @var{colnum}, @var{colinc},
735 Output @var{padchar} (space by default) to move to the given
736 @var{colnum} column. The start of the line is column 0, the default
737 for @var{colnum} is 1.
740 (format #f "~tX") @result{} " X"
741 (format #f "~3tX") @result{} " X"
744 If the current column is already past @var{colnum}, then the move is
745 to there plus a multiple of @var{colinc}, ie.@: column
746 @math{@var{colnum} + @var{N} * @var{colinc}} for the smallest @var{N}
747 which makes that value greater than or equal to the current column.
748 The default @var{colinc} is 1 (which means no further move).
751 (format #f "abcd~2,5,'.tx") @result{} "abcd...x"
754 @nicode{~@@t} takes @var{colnum} as an offset from the current column.
755 @var{colnum} many pad characters are output, then further padding to
756 make the current column a multiple of @var{colinc}, if it isn't
760 (format #f "a~3,5'*@@tx") @result{} "a****x"
763 @nicode{~t} is implemented using @code{port-column} (@pxref{Reading}),
764 so it works even there has been other output before @code{format}.
767 Tilde character. Parameter: @var{n}.
769 Output a tilde character @nicode{~}, or @var{n} many if a parameter is
770 given. Normally @nicode{~} introduces an escape sequence, @nicode{~~}
771 is the way to output a literal tilde.
774 Newline. Parameter: @var{n}.
776 Output a newline character, or @var{n} many if a parameter is given.
777 A newline (or a few newlines) can of course be output just by
778 including them in the format string.
781 Start a new line. Parameter: @var{n}.
783 Output a newline if not already at the start of a line. With a
784 parameter, output that many newlines, but with the first only if not
785 already at the start of a line. So for instance 3 would be a newline
786 if not already at the start of a line, and 2 further newlines.
789 Space character. Parameter: @var{n}.
791 @c For reference, in Common Lisp ~_ is a conditional newline, but
792 @c slib fmtdoc.txi described it as a space, so we keep that.
794 Output a space character, or @var{n} many if a parameter is given.
796 With a variable parameter this is one way to insert runtime calculated
797 padding (@nicode{~t} or the various field widths can do similar
801 (format #f "~v_foo" 4) @result{} " foo"
805 Tab character. Parameter: @var{n}.
807 Output a tab character, or @var{n} many if a parameter is given.
810 Formfeed character. Parameter: @var{n}.
812 Output a formfeed character, or @var{n} many if a parameter is given.
815 Force output. No parameters.
817 At the end of output, call @code{force-output} to flush any buffers on
818 the destination (@pxref{Writing}). @nicode{~!} can occur anywhere in
819 the format string, but the force is done at the end of output.
821 When output is to a string (destination @code{#f}), @nicode{~!} does
824 @item @nicode{~newline} (ie.@: newline character)
825 Continuation line. No parameters.
827 Skip this newline and any following whitespace in the format string,
828 ie.@: don't send it to the output. This can be used to break up a
829 long format string for readability, but not print the extra
835 ~d" 1 2) @result{} "abc1 def2"
838 @nicode{~:newline} skips the newline but leaves any further whitespace
839 to be printed normally.
841 @nicode{~@@newline} prints the newline then skips following
844 @item @nicode{~(} @nicode{~)}
845 Case conversion. No parameters.
847 Between @nicode{~(} and @nicode{~)} the case of all output is changed.
848 The modifiers on @nicode{~(} control the conversion.
852 @nicode{~(} --- lower case.
854 @c FIXME: The : and @ modifiers are not yet documented because the
855 @c code applies string-capitalize and string-capitalize-first to each
856 @c separate format:out-str call, which has various subtly doubtful
857 @c effects. And worse they're applied to individual characters,
858 @c including literal characters in the format string, which has the
859 @c silly effect of being always an upcase.
861 @c The Common Lisp spec is apparently for the capitalization to be
862 @c applied in one hit to the whole of the output between ~( and ~).
863 @c (This can no doubt be implemented without accumulating all that
864 @c text, just by keeping a state or the previous char to tell whether
868 @c @nicode{:} --- first letter of each word upper case, the rest lower
869 @c case, as per the @code{string-capitalize} function (@pxref{Alphabetic
872 @c @nicode{@@} --- first letter of just the first word upper case, the
876 @nicode{~:@@(} --- upper case.
882 (format #t "~(Hello~)") @print{} hello
883 (format #t "~:@@(Hello~)") @print{} HELLO
886 In the future it's intended the modifiers @nicode{:} and @nicode{@@}
887 alone will capitalize the first letters of words, as per Common Lisp
888 @code{format}, but the current implementation of this is flawed and
889 not recommended for use.
891 Case conversions do not nest, currently. This might change in the
892 future, but if it does then it will be to Common Lisp style where the
893 outermost conversion has priority, overriding inner ones (making those
896 @item @nicode{~@{} @nicode{~@}}
897 Iteration. Parameter: @var{maxreps} (for @nicode{~@{}).
899 The format between @nicode{~@{} and @nicode{~@}} is iterated. The
900 modifiers to @nicode{~@{} determine how arguments are taken. The
901 default is a list argument with each iteration successively consuming
902 elements from it. This is a convenient way to output a whole list.
905 (format #t "~@{~d~@}" '(1 2 3)) @print{} 123
906 (format #t "~@{~s=~d ~@}" '("x" 1 "y" 2)) @print{} "x"=1 "y"=2
909 @nicode{~:@{} takes a single argument which is a list of lists, each
910 of those contained lists gives the arguments for the iterated format.
912 @c @print{} on a new line here to avoid overflowing page width in DVI
914 (format #t "~:@{~dx~d ~@}" '((1 2) (3 4) (5 6)))
918 @nicode{~@@@{} takes arguments directly, with each iteration
919 successively consuming arguments.
922 (format #t "~@@@{~d~@}" 1 2 3) @print{} 123
923 (format #t "~@@@{~s=~d ~@}" "x" 1 "y" 2) @print{} "x"=1 "y"=2
926 @nicode{~:@@@{} takes list arguments, one argument for each iteration,
927 using that list for the format.
929 @c @print{} on a new line here to avoid overflowing page width in DVI
931 (format #t "~:@@@{~dx~d ~@}" '(1 2) '(3 4) '(5 6))
935 Iterating stops when there are no more arguments or when the
936 @var{maxreps} parameter to @nicode{~@{} is reached (default no
940 (format #t "~2@{~d~@}" '(1 2 3 4)) @print{} 12
943 If the format between @nicode{~@{} and @nicode{~@}} is empty, then a
944 format string argument is taken (before iteration argument(s)) and
945 used instead. This allows a sub-format (like @nicode{~?} above) to be
949 (format #t "~@{~@}" "~d" '(1 2 3)) @print{} 123
952 @c FIXME: What is the @nicode{:} modifier to ~} meant to do? The
953 @c Common Lisp spec says it's a minimum of 1 iteration, but the
954 @c format.scm code seems to merely make it have MAXREPS default to 1.
956 Iterations can be nested, an inner iteration operates in the same way
957 as described, but of course on the arguments the outer iteration
958 provides it. This can be used to work into nested list structures.
959 For example in the following the inner @nicode{~@{~d~@}x} is applied
960 to @code{(1 2)} then @code{(3 4 5)} etc.
963 (format #t "~@{~@{~d~@}x~@}" '((1 2) (3 4 5))) @print{} 12x345x
966 See also @nicode{~^} below for escaping from iteration.
968 @item @nicode{~[} @nicode{~;} @nicode{~]}
969 Conditional. Parameter: @var{selector}.
971 A conditional block is delimited by @nicode{~[} and @nicode{~]}, and
972 @nicode{~;} separates clauses within the block. @nicode{~[} takes an
973 integer argument and that number clause is used. The first clause is
977 (format #f "~[peach~;banana~;mango~]" 1) @result{} "banana"
980 The @var{selector} parameter can be used for the clause number,
981 instead of taking an argument.
984 (format #f "~2[peach~;banana~;mango~]") @result{} "mango"
987 If the clause number is out of range then nothing is output. Or the
988 last clause can be @nicode{~:;} to use that for a number out of range.
991 (format #f "~[banana~;mango~]" 99) @result{} ""
992 (format #f "~[banana~;mango~:;fruit~]" 99) @result{} "fruit"
995 @nicode{~:[} treats the argument as a flag, and expects two clauses.
996 The first is used if the argument is @code{#f} or the second
1000 (format #f "~:[false~;not false~]" #f) @result{} "false"
1001 (format #f "~:[false~;not false~]" 'abc) @result{} "not false"
1004 (format #t "~d gnu~:[s are~; is~] here" n (= 1 n)))
1005 @print{} 3 gnus are here
1008 @nicode{~@@[} also treats the argument as a flag, and expects one
1009 clause. If the argument is @code{#f} then no output is produced and
1010 the argument is consumed, otherwise the clause is used and the
1011 argument is not consumed, it's left for the clause. This can be used
1012 for instance to suppress output if @code{#f} means something not
1016 (format #f "~@@[temperature=~d~]" 27) @result{} "temperature=27"
1017 (format #f "~@@[temperature=~d~]" #f) @result{} ""
1021 Escape. Parameters: @var{val1}, @var{val2}, @var{val3}.
1023 Stop formatting if there are no more arguments. This can be used for
1024 instance to have a format string adapt to a variable number of
1028 (format #t "~d~^ ~d" 1) @print{} 1
1029 (format #t "~d~^ ~d" 1 2) @print{} 1 2
1032 Within a @nicode{~@{} @nicode{~@}} iteration, @nicode{~^} stops the
1033 current iteration step if there are no more arguments to that step,
1034 but continuing with possible further steps and the rest of the format.
1035 This can be used for instance to avoid a separator on the last
1036 iteration, or to adapt to variable length argument lists.
1039 (format #f "~@{~d~^/~@} go" '(1 2 3)) @result{} "1/2/3 go"
1040 (format #f "~:@{ ~d~^~d~@} go" '((1) (2 3))) @result{} " 1 23 go"
1043 @c For reference, format.scm doesn't implement that Common Lisp ~:^
1044 @c modifier which stops the entire iterating of ~:{ or ~@:{.
1046 @c FIXME: Believe the Common Lisp spec is for ~^ within ~[ ~]
1047 @c conditional to terminate the whole format (or iteration step if in
1048 @c an iteration). But format.scm seems to terminate just the
1049 @c conditional form.
1051 @c (format #f "~[abc~^def~;ghi~] blah" 0)
1052 @c @result{} "abc blah" ;; looks wrong
1054 @c FIXME: Believe the Common Lisp spec is for ~^ within ~( ~) to end
1055 @c that case conversion and then also terminate the whole format (or
1056 @c iteration step if in an iteration). But format.scm doesn't seem
1057 @c to do that quite right.
1059 @c (format #f "~d ~^ ~d" 1) @result{} "1 "
1060 @c (format #f "~(~d ~^ ~d~)" 1) @result{} ERROR
1062 Within a @nicode{~?} sub-format, @nicode{~^} operates just on that
1063 sub-format. If it terminates the sub-format then the originating
1064 format will still continue.
1067 (format #t "~? items" "~d~^ ~d" '(1)) @print{} 1 items
1068 (format #t "~? items" "~d~^ ~d" '(1 2)) @print{} 1 2 items
1071 The parameters to @nicode{~^} (which are numbers) change the condition
1072 used to terminate. For a single parameter, termination is when that
1073 value is zero (notice this makes plain @nicode{~^} equivalent to
1074 @nicode{~#^}). For two parameters, termination is when those two are
1075 equal. For three parameters, termination is when @math{@var{val1}
1076 @le{} @var{val2}} and @math{@var{val2} @le{} @var{val3}}.
1078 @c FIXME: Good examples of these?
1081 Inquiry message. Insert a copyright message into the output.
1083 @nicode{~:q} inserts the format implementation version.
1087 It's an error if there are not enough arguments for the escapes in the
1088 format string, but any excess arguments are ignored.
1090 Iterations @nicode{~@{} @nicode{~@}} and conditionals @nicode{~[}
1091 @nicode{~;} @nicode{~]} can be nested, but must be properly nested,
1092 meaning the inner form must be entirely within the outer form. So
1093 it's not possible, for instance, to try to conditionalize the endpoint
1097 (format #t "~@{ ~[ ... ~] ~@}" ...) ;; good
1098 (format #t "~@{ ~[ ... ~@} ... ~]" ...) ;; bad
1101 The same applies to case conversions @nicode{~(} @nicode{~)}, they
1102 must properly nest with respect to iterations and conditionals (though
1103 currently a case conversion cannot nest within another case
1106 When a sub-format (@nicode{~?}) is used, that sub-format string must
1107 be self-contained. It cannot for instance give a @nicode{~@{} to
1108 begin an iteration form and have the @nicode{~@}} up in the
1109 originating format, or similar.
1113 Guile contains a @code{format} procedure even when the module
1114 @code{(ice-9 format)} is not loaded. The default @code{format} is
1115 @code{simple-format} (@pxref{Writing}), it doesn't support all escape
1116 sequences documented in this section, and will signal an error if you
1117 try to use one of them. The reason for two versions is that the full
1118 @code{format} is fairly large and requires some time to load.
1119 @code{simple-format} is often adequate too.
1122 @node File Tree Walk
1123 @section File Tree Walk
1124 @cindex file tree walk
1126 @cindex file system traversal
1127 @cindex directory traversal
1129 The functions in this section traverse a tree of files and
1130 directories. They come in two flavors: the first one is a high-level
1131 functional interface, and the second one is similar to the C @code{ftw}
1132 and @code{nftw} routines (@pxref{Working with Directory Trees,,, libc,
1133 GNU C Library Reference Manual}).
1136 (use-modules (ice-9 ftw))
1140 @deffn {Scheme Procedure} file-system-tree file-name [enter? [stat]]
1141 Return a tree of the form @code{(@var{file-name} @var{stat}
1142 @var{children} ...)} where @var{stat} is the result of @code{(@var{stat}
1143 @var{file-name})} and @var{children} are similar structures for each
1144 file contained in @var{file-name} when it designates a directory.
1146 The optional @var{enter?} predicate is invoked as @code{(@var{enter?}
1147 @var{name} @var{stat})} and should return true to allow recursion into
1148 directory @var{name}; the default value is a procedure that always
1149 returns @code{#t}. When a directory does not match @var{enter?}, it
1150 nonetheless appears in the resulting tree, only with zero children.
1152 The @var{stat} argument is optional and defaults to @code{lstat}, as for
1153 @code{file-system-fold} (see below.)
1155 The example below shows how to obtain a hierarchical listing of the
1156 files under the @file{module/language} directory in the Guile source
1157 tree, discarding their @code{stat} info:
1160 (use-modules (ice-9 match))
1163 ;; Remove the `stat' object the `file-system-tree' provides
1164 ;; for each file in the tree.
1166 ((name stat) ; flat file
1168 ((name stat children ...) ; directory
1169 (list name (map remove-stat children)))))
1171 (let ((dir (string-append (assq-ref %guile-build-info 'top_srcdir)
1172 "/module/language")))
1173 (remove-stat (file-system-tree dir)))
1177 (("value" ("spec.go" "spec.scm"))
1181 "compile-tree-il.scm"
1182 "decompile-tree-il.scm"
1183 "decompile-tree-il.go"
1184 "compile-tree-il.go"))
1199 @cindex file system combinator
1201 It is often desirable to process directories entries directly, rather
1202 than building up a tree of entries in memory, like
1203 @code{file-system-tree} does. The following procedure, a
1204 @dfn{combinator}, is designed to allow directory entries to be processed
1205 directly as a directory tree is traversed; in fact,
1206 @code{file-system-tree} is implemented in terms of it.
1208 @deffn {Scheme Procedure} file-system-fold enter? leaf down up skip error init file-name [stat]
1209 Traverse the directory at @var{file-name}, recursively, and return the
1210 result of the successive applications of the @var{leaf}, @var{down},
1211 @var{up}, and @var{skip} procedures as described below.
1213 Enter sub-directories only when @code{(@var{enter?} @var{path}
1214 @var{stat} @var{result})} returns true. When a sub-directory is
1215 entered, call @code{(@var{down} @var{path} @var{stat} @var{result})},
1216 where @var{path} is the path of the sub-directory and @var{stat} the
1217 result of @code{(false-if-exception (@var{stat} @var{path}))}; when it is
1218 left, call @code{(@var{up} @var{path} @var{stat} @var{result})}.
1220 For each file in a directory, call @code{(@var{leaf} @var{path}
1221 @var{stat} @var{result})}.
1223 When @var{enter?} returns @code{#f}, or when an unreadable directory is
1224 encountered, call @code{(@var{skip} @var{path} @var{stat}
1227 When @var{file-name} names a flat file, @code{(@var{leaf} @var{path}
1228 @var{stat} @var{init})} is returned.
1230 When an @code{opendir} or @var{stat} call fails, call @code{(@var{error}
1231 @var{path} @var{stat} @var{errno} @var{result})}, with @var{errno} being
1232 the operating system error number that was raised---e.g.,
1233 @code{EACCES}---and @var{stat} either @code{#f} or the result of the
1234 @var{stat} call for that entry, when available.
1236 The special @file{.} and @file{..} entries are not passed to these
1237 procedures. The @var{path} argument to the procedures is a full file
1238 name---e.g., @code{"../foo/bar/gnu"}; if @var{file-name} is an absolute
1239 file name, then @var{path} is also an absolute file name. Files and
1240 directories, as identified by their device/inode number pair, are
1241 traversed only once.
1243 The optional @var{stat} argument defaults to @code{lstat}, which means
1244 that symbolic links are not followed; the @code{stat} procedure can be
1245 used instead when symbolic links are to be followed (@pxref{File System,
1248 The example below illustrates the use of @code{file-system-fold}:
1251 (define (total-file-size file-name)
1252 "Return the size in bytes of the files under FILE-NAME (similar
1253 to `du --apparent-size' with GNU Coreutils.)"
1255 (define (enter? name stat result)
1256 ;; Skip version control directories.
1257 (not (member (basename name) '(".git" ".svn" "CVS"))))
1258 (define (leaf name stat result)
1259 ;; Return RESULT plus the size of the file at NAME.
1260 (+ result (stat:size stat)))
1262 ;; Count zero bytes for directories.
1263 (define (down name stat result) result)
1264 (define (up name stat result) result)
1266 ;; Likewise for skipped directories.
1267 (define (skip name stat result) result)
1269 ;; Ignore unreadable files/directories but warn the user.
1270 (define (error name stat errno result)
1271 (format (current-error-port) "warning: ~a: ~a~%"
1272 name (strerror errno))
1275 (file-system-fold enter? leaf down up skip error
1276 0 ; initial counter is zero bytes
1279 (total-file-size ".")
1282 (total-file-size "/dev/null")
1287 The alternative C-like functions are described below.
1289 @deffn {Scheme Procedure} scandir name [select? [entry<?]]
1290 Return the list of the names of files contained in directory @var{name}
1291 that match predicate @var{select?} (by default, all files). The
1292 returned list of file names is sorted according to @var{entry<?}, which
1293 defaults to @code{string-locale<?} such that file names are sorted in
1294 the locale's alphabetical order (@pxref{Text Collation}). Return
1295 @code{#f} when @var{name} is unreadable or is not a directory.
1297 This procedure is modeled after the C library function of the same name
1298 (@pxref{Scanning Directory Content,,, libc, GNU C Library Reference
1302 @deffn {Scheme Procedure} ftw startname proc ['hash-size n]
1303 Walk the file system tree descending from @var{startname}, calling
1304 @var{proc} for each file and directory.
1306 Hard links and symbolic links are followed. A file or directory is
1307 reported to @var{proc} only once, and skipped if seen again in another
1308 place. One consequence of this is that @code{ftw} is safe against
1309 circularly linked directory structures.
1311 Each @var{proc} call is @code{(@var{proc} filename statinfo flag)} and
1312 it should return @code{#t} to continue, or any other value to stop.
1314 @var{filename} is the item visited, being @var{startname} plus a
1315 further path and the name of the item. @var{statinfo} is the return
1316 from @code{stat} (@pxref{File System}) on @var{filename}. @var{flag}
1317 is one of the following symbols,
1321 @var{filename} is a file, this includes special files like devices,
1325 @var{filename} is a directory.
1328 An error occurred when calling @code{stat}, so nothing is known.
1329 @var{statinfo} is @code{#f} in this case.
1331 @item directory-not-readable
1332 @var{filename} is a directory, but one which cannot be read and hence
1333 won't be recursed into.
1336 @var{filename} is a dangling symbolic link. Symbolic links are
1337 normally followed and their target reported, the link itself is
1338 reported if the target does not exist.
1341 The return value from @code{ftw} is @code{#t} if it ran to completion,
1342 or otherwise the non-@code{#t} value from @var{proc} which caused the
1345 Optional argument symbol @code{hash-size} and an integer can be given
1346 to set the size of the hash table used to track items already visited.
1347 (@pxref{Hash Table Reference})
1349 @c Actually, it's probably safe to escape from ftw, just need to
1352 In the current implementation, returning non-@code{#t} from @var{proc}
1353 is the only valid way to terminate @code{ftw}. @var{proc} must not
1354 use @code{throw} or similar to escape.
1358 @deffn {Scheme Procedure} nftw startname proc ['chdir] ['depth] ['hash-size n] ['mount] ['physical]
1359 Walk the file system tree starting at @var{startname}, calling
1360 @var{proc} for each file and directory. @code{nftw} has extra
1361 features over the basic @code{ftw} described above.
1363 Like @code{ftw}, hard links and symbolic links are followed. A file
1364 or directory is reported to @var{proc} only once, and skipped if seen
1365 again in another place. One consequence of this is that @code{nftw}
1366 is safe against circular linked directory structures.
1368 Each @var{proc} call is @code{(@var{proc} filename statinfo flag
1369 base level)} and it should return @code{#t} to continue, or any
1370 other value to stop.
1372 @var{filename} is the item visited, being @var{startname} plus a
1373 further path and the name of the item. @var{statinfo} is the return
1374 from @code{stat} on @var{filename} (@pxref{File System}). @var{base}
1375 is an integer offset into @var{filename} which is where the basename
1376 for this item begins. @var{level} is an integer giving the directory
1377 nesting level, starting from 0 for the contents of @var{startname} (or
1378 that item itself if it's a file). @var{flag} is one of the following
1383 @var{filename} is a file, including special files like devices, named
1387 @var{filename} is a directory.
1389 @item directory-processed
1390 @var{filename} is a directory, and its contents have all been visited.
1391 This flag is given instead of @code{directory} when the @code{depth}
1392 option below is used.
1395 An error occurred when applying @code{stat} to @var{filename}, so
1396 nothing is known about it. @var{statinfo} is @code{#f} in this case.
1398 @item directory-not-readable
1399 @var{filename} is a directory, but one which cannot be read and hence
1400 won't be recursed into.
1403 @var{filename} is a dangling symbolic link. Links are normally
1404 followed and their target reported, the link itself is reported if its
1405 target does not exist.
1408 When the @code{physical} option described below is used, this
1409 indicates @var{filename} is a symbolic link whose target exists (and
1410 is not being followed).
1413 The following optional arguments can be given to modify the way
1414 @code{nftw} works. Each is passed as a symbol (and @code{hash-size}
1415 takes a following integer value).
1419 Change to the directory containing the item before calling @var{proc}.
1420 When @code{nftw} returns the original current directory is restored.
1422 Under this option, generally the @var{base} parameter to each
1423 @var{proc} call should be used to pick out the base part of the
1424 @var{filename}. The @var{filename} is still a path but with a changed
1425 directory it won't be valid (unless the @var{startname} directory was
1429 Visit files ``depth first'', meaning @var{proc} is called for the
1430 contents of each directory before it's called for the directory
1431 itself. Normally a directory is reported first, then its contents.
1433 Under this option, the @var{flag} to @var{proc} for a directory is
1434 @code{directory-processed} instead of @code{directory}.
1436 @item @code{hash-size @var{n}}
1437 Set the size of the hash table used to track items already visited.
1438 (@pxref{Hash Table Reference})
1441 Don't cross a mount point, meaning only visit items on the same
1442 file system as @var{startname} (ie.@: the same @code{stat:dev}).
1444 @item @code{physical}
1445 Don't follow symbolic links, instead report them to @var{proc} as
1446 @code{symlink}. Dangling links (those whose target doesn't exist) are
1447 still reported as @code{stale-symlink}.
1450 The return value from @code{nftw} is @code{#t} if it ran to
1451 completion, or otherwise the non-@code{#t} value from @var{proc} which
1454 @c For reference, one reason not to escape is that the current
1455 @c directory is not saved and restored with dynamic-wind. Maybe
1456 @c changing that would be enough to allow escaping.
1458 In the current implementation, returning non-@code{#t} from @var{proc}
1459 is the only valid way to terminate @code{ftw}. @var{proc} must not
1460 use @code{throw} or similar to escape.
1470 The functions in this section are provided by
1473 (use-modules (ice-9 q))
1476 This module implements queues holding arbitrary scheme objects and
1477 designed for efficient first-in / first-out operations.
1479 @code{make-q} creates a queue, and objects are entered and removed
1480 with @code{enq!} and @code{deq!}. @code{q-push!} and @code{q-pop!}
1481 can be used too, treating the front of the queue like a stack.
1485 @deffn {Scheme Procedure} make-q
1489 @deffn {Scheme Procedure} q? obj
1490 Return @code{#t} if @var{obj} is a queue, or @code{#f} if not.
1492 Note that queues are not a distinct class of objects but are
1493 implemented with cons cells. For that reason certain list structures
1494 can get @code{#t} from @code{q?}.
1497 @deffn {Scheme Procedure} enq! q obj
1498 Add @var{obj} to the rear of @var{q}, and return @var{q}.
1501 @deffn {Scheme Procedure} deq! q
1502 @deffnx {Scheme Procedure} q-pop! q
1503 Remove and return the front element from @var{q}. If @var{q} is
1504 empty, a @code{q-empty} exception is thrown.
1506 @code{deq!} and @code{q-pop!} are the same operation, the two names
1507 just let an application match @code{enq!} with @code{deq!}, or
1508 @code{q-push!} with @code{q-pop!}.
1511 @deffn {Scheme Procedure} q-push! q obj
1512 Add @var{obj} to the front of @var{q}, and return @var{q}.
1515 @deffn {Scheme Procedure} q-length q
1516 Return the number of elements in @var{q}.
1519 @deffn {Scheme Procedure} q-empty? q
1520 Return true if @var{q} is empty.
1523 @deffn {Scheme Procedure} q-empty-check q
1524 Throw a @code{q-empty} exception if @var{q} is empty.
1527 @deffn {Scheme Procedure} q-front q
1528 Return the first element of @var{q} (without removing it). If @var{q}
1529 is empty, a @code{q-empty} exception is thrown.
1532 @deffn {Scheme Procedure} q-rear q
1533 Return the last element of @var{q} (without removing it). If @var{q}
1534 is empty, a @code{q-empty} exception is thrown.
1537 @deffn {Scheme Procedure} q-remove! q obj
1538 Remove all occurrences of @var{obj} from @var{q}, and return @var{q}.
1539 @var{obj} is compared to queue elements using @code{eq?}.
1543 @cindex @code{q-empty}
1544 The @code{q-empty} exceptions described above are thrown just as
1545 @code{(throw 'q-empty)}, there's no message etc like an error throw.
1547 A queue is implemented as a cons cell, the @code{car} containing a
1548 list of queued elements, and the @code{cdr} being the last cell in
1549 that list (for ease of enqueuing).
1552 (@var{list} . @var{last-cell})
1556 If the queue is empty, @var{list} is the empty list and
1557 @var{last-cell} is @code{#f}.
1559 An application can directly access the queue list if desired, for
1560 instance to search the elements or to insert at a specific point.
1562 @deffn {Scheme Procedure} sync-q! q
1563 Recompute the @var{last-cell} field in @var{q}.
1565 All the operations above maintain @var{last-cell} as described, so
1566 normally there's no need for @code{sync-q!}. But if an application
1567 modifies the queue @var{list} then it must either maintain
1568 @var{last-cell} similarly, or call @code{sync-q!} to recompute it.
1576 This section documents Guile's legacy stream module. For a more
1577 complete and portable stream library, @pxref{SRFI-41}.
1579 A stream represents a sequence of values, each of which is calculated
1580 only when required. This allows large or even infinite sequences to
1581 be represented and manipulated with familiar operations like ``car'',
1582 ``cdr'', ``map'' or ``fold''. In such manipulations only as much as
1583 needed is actually held in memory at any one time. The functions in
1584 this section are available from
1587 (use-modules (ice-9 streams))
1590 Streams are implemented using promises (@pxref{Delayed Evaluation}),
1591 which is how the underlying calculation of values is made only when
1592 needed, and the values then retained so the calculation is not
1596 Here is a simple example producing a stream of all odd numbers,
1599 (define odds (make-stream (lambda (state)
1600 (cons state (+ state 2)))
1602 (stream-car odds) @result{} 1
1603 (stream-car (stream-cdr odds)) @result{} 3
1607 @code{stream-map} could be used to derive a stream of odd squares,
1610 (define (square n) (* n n))
1611 (define oddsquares (stream-map square odds))
1614 These are infinite sequences, so it's not possible to convert them to
1615 a list, but they could be printed (infinitely) with for example
1618 (stream-for-each (lambda (n sq)
1619 (format #t "~a squared is ~a\n" n sq))
1630 @deffn {Scheme Procedure} make-stream proc initial-state
1631 Return a new stream, formed by calling @var{proc} successively.
1633 Each call is @code{(@var{proc} @var{state})}, it should return a pair,
1634 the @code{car} being the value for the stream, and the @code{cdr}
1635 being the new @var{state} for the next call. For the first call
1636 @var{state} is the given @var{initial-state}. At the end of the
1637 stream, @var{proc} should return some non-pair object.
1640 @deffn {Scheme Procedure} stream-car stream
1641 Return the first element from @var{stream}. @var{stream} must not be
1645 @deffn {Scheme Procedure} stream-cdr stream
1646 Return a stream which is the second and subsequent elements of
1647 @var{stream}. @var{stream} must not be empty.
1650 @deffn {Scheme Procedure} stream-null? stream
1651 Return true if @var{stream} is empty.
1654 @deffn {Scheme Procedure} list->stream list
1655 @deffnx {Scheme Procedure} vector->stream vector
1656 Return a stream with the contents of @var{list} or @var{vector}.
1658 @var{list} or @var{vector} should not be modified subsequently, since
1659 it's unspecified whether changes there will be reflected in the stream
1663 @deffn {Scheme Procedure} port->stream port readproc
1664 Return a stream which is the values obtained by reading from
1665 @var{port} using @var{readproc}. Each read call is
1666 @code{(@var{readproc} @var{port})}, and it should return an EOF object
1667 (@pxref{Reading}) at the end of input.
1669 For example a stream of characters from a file,
1672 (port->stream (open-input-file "/foo/bar.txt") read-char)
1676 @deffn {Scheme Procedure} stream->list stream
1677 Return a list which is the entire contents of @var{stream}.
1680 @deffn {Scheme Procedure} stream->reversed-list stream
1681 Return a list which is the entire contents of @var{stream}, but in
1685 @deffn {Scheme Procedure} stream->list&length stream
1686 Return two values (@pxref{Multiple Values}), being firstly a list
1687 which is the entire contents of @var{stream}, and secondly the number
1688 of elements in that list.
1691 @deffn {Scheme Procedure} stream->reversed-list&length stream
1692 Return two values (@pxref{Multiple Values}) being firstly a list which
1693 is the entire contents of @var{stream}, but in reverse order, and
1694 secondly the number of elements in that list.
1697 @deffn {Scheme Procedure} stream->vector stream
1698 Return a vector which is the entire contents of @var{stream}.
1701 @defun stream-fold proc init stream1 stream2 @dots{}
1702 Apply @var{proc} successively over the elements of the given streams,
1703 from first to last until the end of the shortest stream is reached.
1704 Return the result from the last @var{proc} call.
1706 Each call is @code{(@var{proc} elem1 elem2 @dots{} prev)}, where each
1707 @var{elem} is from the corresponding @var{stream}. @var{prev} is the
1708 return from the previous @var{proc} call, or the given @var{init} for
1712 @defun stream-for-each proc stream1 stream2 @dots{}
1713 Call @var{proc} on the elements from the given @var{stream}s. The
1714 return value is unspecified.
1716 Each call is @code{(@var{proc} elem1 elem2 @dots{})}, where each
1717 @var{elem} is from the corresponding @var{stream}.
1718 @code{stream-for-each} stops when it reaches the end of the shortest
1722 @defun stream-map proc stream1 stream2 @dots{}
1723 Return a new stream which is the results of applying @var{proc} to the
1724 elements of the given @var{stream}s.
1726 Each call is @code{(@var{proc} elem1 elem2 @dots{})}, where each
1727 @var{elem} is from the corresponding @var{stream}. The new stream
1728 ends when the end of the shortest given @var{stream} is reached.
1732 @node Buffered Input
1733 @section Buffered Input
1734 @cindex Buffered input
1735 @cindex Line continuation
1737 The following functions are provided by
1740 (use-modules (ice-9 buffered-input))
1743 A buffered input port allows a reader function to return chunks of
1744 characters which are to be handed out on reading the port. A notion
1745 of further input for an application level logical expression is
1746 maintained too, and passed through to the reader.
1748 @deffn {Scheme Procedure} make-buffered-input-port reader
1749 Create an input port which returns characters obtained from the given
1750 @var{reader} function. @var{reader} is called (@var{reader} cont),
1751 and should return a string or an EOF object.
1753 The new port gives precisely the characters returned by @var{reader},
1754 nothing is added, so if any newline characters or other separators are
1755 desired they must come from the reader function.
1757 The @var{cont} parameter to @var{reader} is @code{#f} for initial
1758 input, or @code{#t} when continuing an expression. This is an
1759 application level notion, set with
1760 @code{set-buffered-input-continuation?!} below. If the user has
1761 entered a partial expression then it allows @var{reader} for instance
1762 to give a different prompt to show more is required.
1765 @deffn {Scheme Procedure} make-line-buffered-input-port reader
1766 @cindex Line buffered input
1767 Create an input port which returns characters obtained from the
1768 specified @var{reader} function, similar to
1769 @code{make-buffered-input-port} above, but where @var{reader} is
1770 expected to be a line-oriented.
1772 @var{reader} is called (@var{reader} cont), and should return a string
1773 or an EOF object as above. Each string is a line of input without a
1774 newline character, the port code inserts a newline after each string.
1777 @deffn {Scheme Procedure} set-buffered-input-continuation?! port cont
1778 Set the input continuation flag for a given buffered input
1781 An application uses this by calling with a @var{cont} flag of
1782 @code{#f} when beginning to read a new logical expression. For
1783 example with the Scheme @code{read} function (@pxref{Scheme Read}),
1786 (define my-port (make-buffered-input-port my-reader))
1788 (set-buffered-input-continuation?! my-port #f)
1789 (let ((obj (read my-port)))
1796 @c TeX-master: "guile.texi"