2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2009, 2010
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 entering the following:
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.
63 @cindex truncated printing
64 Also exported by the @code{(ice-9 pretty-print)} module is
65 @code{truncated-print}, a procedure to print Scheme datums, truncating
66 the output to a certain number of characters. This is useful when you
67 need to present an arbitrary datum to the user, but you only have one
68 line in which to do so.
71 (define exp '(a b #(c d e) f . g))
72 (truncated-print exp #:width 10) (newline)
74 (truncated-print exp #:width 15) (newline)
75 @print{} (a b # f . g)
76 (truncated-print exp #:width 18) (newline)
77 @print{} (a b #(c ...) . #)
78 (truncated-print exp #:width 20) (newline)
79 @print{} (a b #(c d e) f . g)
80 (truncated-print "The quick brown fox" #:width 20) (newline)
81 @print{} "The quick brown..."
82 (truncated-print (current-module) #:width 20) (newline)
83 @print{} #<directory (gui...>
86 @code{truncated-print} will not output a trailing newline. If an expression does
87 not fit in the given width, it will be truncated -- possibly
88 ellipsized@footnote{On Unicode-capable ports, the ellipsis is represented by
89 character `HORIZONTAL ELLIPSIS' (U+2026), otherwise it is represented by three
90 dots.}, or in the worst case, displayed as @nicode{#}.
92 @deffn {Scheme Procedure} truncated-print obj [port] [keyword-options]
93 Print @var{obj}, truncating the output, if necessary, to make it fit
94 into @var{width} characters. By default, @var{x} will be printed using
95 @code{write}, though that behavior can be overriden via the
96 @var{display?} keyword argument.
98 The default behaviour is to print depth-first, meaning that the entire
99 remaining width will be available to each sub-expressoin of @var{x} --
100 e.g., if @var{x} is a vector, each member of @var{x}. One can attempt to
101 ``ration'' the available width, trying to allocate it equally to each
102 sub-expression, via the @var{breadth-first?} keyword argument.
104 The further @var{keyword-options} are keywords and parameters as
108 @item @nicode{#:display?} @var{flag}
109 If @var{flag} is true then print using @code{display}. The default is
110 @code{#f} which means use @code{write} style. (@pxref{Writing})
112 @item @nicode{#:width} @var{columns}
113 Print within the given @var{columns}. The default is 79.
115 @item @nicode{#:breadth-first?} @var{flag}
116 If @var{flag} is true, then allocate the available width breadth-first
117 among elements of a compound data structure (list, vector, pair,
118 etc.). The default is @code{#f} which means that any element is
119 allowed to consume all of the available width.
125 @node Formatted Output
126 @section Formatted Output
127 @cindex formatted output
129 @c For reference, in this section escapes like ~a are given in
130 @c @nicode, to give code font in TeX etc, but leave them unadorned in
133 @c The idea is to reduce clutter around what's shown, and avoid any
134 @c possible confusion over whether the ` ' quotes are part of what
135 @c should be entered. (In particular for instance of course ' is
136 @c meaningful in a format string, introducing a char parameter).
138 The @code{format} function is a powerful way to print numbers, strings
139 and other objects together with literal text under the control of a
140 format string. This function is available from
143 (use-modules (ice-9 format))
146 A format string is generally more compact and easier than using just
147 the standard procedures like @code{display}, @code{write} and
148 @code{newline}. Parameters in the output string allow various output
149 styles, and parameters can be taken from the arguments for runtime
152 @code{format} is similar to the Common Lisp procedure of the same
153 name, but it's not identical and doesn't have quite all the features
154 found in Common Lisp.
156 C programmers will note the similarity between @code{format} and
157 @code{printf}, though escape sequences are marked with @nicode{~}
158 instead of @nicode{%}, and are more powerful.
161 @deffn {Scheme Procedure} format dest fmt [args@dots{}]
162 Write output specified by the @var{fmt} string to @var{dest}.
163 @var{dest} can be an output port, @code{#t} for
164 @code{current-output-port} (@pxref{Default Ports}), a number for
165 @code{current-error-port}, or @code{#f} to return the output as a
168 @var{fmt} can contain literal text to be output, and @nicode{~}
169 escapes. Each escape has the form
172 ~ [param [, param@dots{}] [:] [@@] code
175 @nicode{code} is a character determining the escape sequence. The
176 @nicode{:} and @nicode{@@} characters are optional modifiers, one or
177 both of which change the way various codes operate. Optional
178 parameters are accepted by some codes too. Parameters have the
182 @item @nicode{[+/-]number}
183 An integer, with optional @nicode{+} or @nicode{-}.
184 @item @nicode{'} (apostrophe)
185 The following character in the format string, for instance @nicode{'z}
188 The next function argument as the parameter. @nicode{v} stands for
189 ``variable'', a parameter can be calculated at runtime and included in
190 the arguments. Upper case @nicode{V} can be used too.
192 The number of arguments remaining. (See @nicode{~*} below for some
196 Parameters are separated by commas (@nicode{,}). A parameter can be
197 left empty to keep its default value when supplying later parameters.
200 The following escapes are available. The code letters are not
201 case-sensitive, upper and lower case are the same.
206 Object output. Parameters: @var{minwidth}, @var{padinc},
207 @var{minpad}, @var{padchar}.
209 @nicode{~a} outputs an argument like @code{display}, @nicode{~s}
210 outputs an argument like @code{write} (@pxref{Writing}).
213 (format #t "~a" "foo") @print{} foo
214 (format #t "~s" "foo") @print{} "foo"
217 @nicode{~:a} and @nicode{~:s} put objects that don't have an external
218 representation in quotes like a string.
221 (format #t "~:a" car) @print{} "#<primitive-procedure car>"
224 If the output is less than @var{minwidth} characters (default 0), it's
225 padded on the right with @var{padchar} (default space). @nicode{~@@a}
226 and @nicode{~@@s} put the padding on the left instead.
229 (format #f "~5a" 'abc) @result{} "abc "
230 (format #f "~5,,,'-@@a" 'abc) @result{} "--abc"
233 @var{minpad} is a minimum for the padding then plus a multiple of
234 @var{padinc}. Ie.@: the padding is @math{@var{minpad} + @var{N} *
235 @var{padinc}}, where @var{n} is the smallest integer making the total
236 object plus padding greater than or equal to @var{minwidth}. The
237 default @var{minpad} is 0 and the default @var{padinc} is 1 (imposing
238 no minimum or multiple).
241 (format #f "~5,1,4a" 'abc) @result{} "abc "
245 Character. Parameter: @var{charnum}.
247 Output a character. The default is to simply output, as per
248 @code{write-char} (@pxref{Writing}). @nicode{~@@c} prints in
249 @code{write} style. @nicode{~:c} prints control characters (ASCII 0
250 to 31) in @nicode{^X} form.
253 (format #t "~c" #\z) @print{} z
254 (format #t "~@@c" #\z) @print{} #\z
255 (format #t "~:c" #\newline) @print{} ^J
258 If the @var{charnum} parameter is given then an argument is not taken
259 but instead the character is @code{(integer->char @var{charnum})}
260 (@pxref{Characters}). This can be used for instance to output
261 characters given by their ASCII code.
264 (format #t "~65c") @print{} A
271 Integer. Parameters: @var{minwidth}, @var{padchar}, @var{commachar},
274 Output an integer argument as a decimal, hexadecimal, octal or binary
275 integer (respectively).
278 (format #t "~d" 123) @print{} 123
281 @nicode{~@@d} etc shows a @nicode{+} sign is shown on positive
284 @c FIXME: "+" is not shown on zero, unlike in Common Lisp. Should
285 @c that be changed in the code, or is it too late and should just be
286 @c documented that way?
289 (format #t "~@@b" 12) @print{} +1100
292 If the output is less than the @var{minwidth} parameter (default no
293 minimum), it's padded on the left with the @var{padchar} parameter
297 (format #t "~5,'*d" 12) @print{} ***12
298 (format #t "~5,'0d" 12) @print{} 00012
299 (format #t "~3d" 1234) @print{} 1234
302 @nicode{~:d} adds commas (or the @var{commachar} parameter) every
303 three digits (or the @var{commawidth} parameter many).
306 (format #t "~:d" 1234567) @print{} 1,234,567
307 (format #t "~10,'*,'/,2:d" 12345) @print{} ***1/23/45
310 Hexadecimal @nicode{~x} output is in lower case, but the @nicode{~(}
311 and @nicode{~)} case conversion directives described below can be used
315 (format #t "~x" 65261) @print{} feed
316 (format #t "~:@@(~x~)" 65261) @print{} FEED
320 Integer in words, roman numerals, or a specified radix. Parameters:
321 @var{radix}, @var{minwidth}, @var{padchar}, @var{commachar},
324 With no parameters output is in words as a cardinal like ``ten'', or
325 @nicode{~:r} prints an ordinal like ``tenth''.
328 (format #t "~r" 9) @print{} nine ;; cardinal
329 (format #t "~r" -9) @print{} minus nine ;; cardinal
330 (format #t "~:r" 9) @print{} ninth ;; ordinal
333 And also with no parameters, @nicode{~@@r} gives roman numerals and
334 @nicode{~:@@r} gives old roman numerals. In old roman numerals
335 there's no ``subtraction'', so 9 is @nicode{VIIII} instead of
336 @nicode{IX}. In both cases only positive numbers can be output.
339 (format #t "~@@r" 89) @print{} LXXXIX ;; roman
340 (format #t "~:@@r" 89) @print{} LXXXVIIII ;; old roman
343 When a parameter is given it means numeric output in the specified
344 @var{radix}. The modifiers and parameters following the radix are the
345 same as described for @nicode{~d} etc above.
348 (format #f "~3r" 27) @result{} "1000" ;; base 3
349 (format #f "~3,5r" 26) @result{} " 222" ;; base 3 width 5
353 Fixed-point float. Parameters: @var{width}, @var{decimals},
354 @var{scale}, @var{overflowchar}, @var{padchar}.
356 Output a number or number string in fixed-point format, ie.@: with a
360 (format #t "~f" 5) @print{} 5.0
361 (format #t "~f" "123") @print{} 123.0
362 (format #t "~f" "1e-1") @print{} 0.1
365 @nicode{~@@f} prints a @nicode{+} sign on positive numbers (including
369 (format #t "~@@f" 0) @print{} +0.0
372 If the output is less than @var{width} characters it's padded on the
373 left with @var{padchar} (space by default). If the output equals or
374 exceeds @var{width} then there's no padding. The default for
375 @var{width} is no padding.
378 (format #f "~6f" -1.5) @result{} " -1.5"
379 (format #f "~6,,,,'*f" 23) @result{} "**23.0"
380 (format #f "~6f" 1234567.0) @result{} "1234567.0"
383 @var{decimals} is how many digits to print after the decimal point,
384 with the value rounded or padded with zeros as necessary. (The
385 default is to output as many decimals as required.)
388 (format #t "~1,2f" 3.125) @print{} 3.13
389 (format #t "~1,2f" 1.5) @print{} 1.50
392 @var{scale} is a power of 10 applied to the value, moving the decimal
393 point that many places. A positive @var{scale} increases the value
394 shown, a negative decreases it.
397 (format #t "~,,2f" 1234) @print{} 123400.0
398 (format #t "~,,-2f" 1234) @print{} 12.34
401 If @var{overflowchar} and @var{width} are both given and if the output
402 would exceed @var{width}, then that many @var{overflowchar}s are
403 printed instead of the value.
406 (format #t "~5,,,'xf" 12345) @print{} 12345
407 (format #t "~4,,,'xf" 12345) @print{} xxxx
411 Exponential float. Parameters: @var{width}, @var{mantdigits},
412 @var{expdigits}, @var{intdigits}, @var{overflowchar}, @var{padchar},
415 Output a number or number string in exponential notation.
418 (format #t "~e" 5000.25) @print{} 5.00025E+3
419 (format #t "~e" "123.4") @print{} 1.234E+2
420 (format #t "~e" "1e4") @print{} 1.0E+4
423 @nicode{~@@e} prints a @nicode{+} sign on positive numbers (including
424 zero). (This is for the mantissa, a @nicode{+} or @nicode{-} sign is
425 always shown on the exponent.)
428 (format #t "~@@e" 5000.0) @print{} +5.0E+3
431 If the output is less than @var{width} characters it's padded on the
432 left with @var{padchar} (space by default). The default for
433 @var{width} is to output with no padding.
436 (format #f "~10e" 1234.0) @result{} " 1.234E+3"
437 (format #f "~10,,,,,'*e" 0.5) @result{} "****5.0E-1"
440 @c FIXME: Describe what happens when the number is bigger than WIDTH.
441 @c There seems to be a bit of dodginess about this, or some deviation
444 @var{mantdigits} is the number of digits shown in the mantissa after
445 the decimal point. The value is rounded or trailing zeros are added
446 as necessary. The default @var{mantdigits} is to show as much as
450 (format #f "~,3e" 11111.0) @result{} "1.111E+4"
451 (format #f "~,8e" 123.0) @result{} "1.23000000E+2"
454 @var{expdigits} is the minimum number of digits shown for the
455 exponent, with leading zeros added if necessary. The default for
456 @var{expdigits} is to show only as many digits as required. At least
457 1 digit is always shown.
460 (format #f "~,,1e" 1.0e99) @result{} "1.0E+99"
461 (format #f "~,,6e" 1.0e99) @result{} "1.0E+000099"
464 @var{intdigits} (default 1) is the number of digits to show before the
465 decimal point in the mantissa. @var{intdigits} can be zero, in which
466 case the integer part is a single @nicode{0}, or it can be negative,
467 in which case leading zeros are shown after the decimal point.
469 @c FIXME: When INTDIGITS is 0, Common Lisp format apparently only
470 @c shows the single 0 digit if it fits in WIDTH. format.scm seems to
471 @c show it always. Is it meant to?
474 (format #t "~,,,3e" 12345.0) @print{} 123.45E+2
475 (format #t "~,,,0e" 12345.0) @print{} 0.12345E+5
476 (format #t "~,,,-3e" 12345.0) @print{} 0.00012345E+8
479 @c FIXME: MANTDIGITS with negative INTDIGITS doesn't match CL spec,
480 @c believe the spec says it ought to still show mantdigits+1 sig
481 @c figures, ie. leading zeros don't count towards MANTDIGITS, but it
482 @c seems to just treat MANTDIGITS as how many digits after the
485 If @var{overflowchar} is given then @var{width} is a hard limit. If
486 the output would exceed @var{width} then instead that many
487 @var{overflowchar}s are printed.
490 (format #f "~6,,,,'xe" 100.0) @result{} "1.0E+2"
491 (format #f "~3,,,,'xe" 100.0) @result{} "xxx"
494 @var{expchar} is the exponent marker character (default @nicode{E}).
497 (format #t "~,,,,,,'ee" 100.0) @print{} 1.0e+2
501 General float. Parameters: @var{width}, @var{mantdigits},
502 @var{expdigits}, @var{intdigits}, @var{overflowchar}, @var{padchar},
505 Output a number or number string in either exponential format the same
506 as @nicode{~e}, or fixed-point format like @nicode{~f} but aligned
507 where the mantissa would have been and followed by padding where the
508 exponent would have been.
510 @c FIXME: The default MANTDIGITS is apparently max(needed,min(n,7))
511 @c where 10^(n-1)<=abs(x)<=10^n. But the Common Lisp spec seems to
512 @c ask for "needed" to be without leading or trailing zeros, whereas
513 @c format.scm seems to include trailing zeros, ending up with it
514 @c using fixed format for bigger values than it should.
516 Fixed-point is used when the absolute value is 0.1 or more and it
517 takes no more space than the mantissa in exponential format, ie.@:
518 basically up to @var{mantdigits} digits.
521 (format #f "~12,4,2g" 999.0) @result{} " 999.0 "
522 (format #f "~12,4,2g" "100000") @result{} " 1.0000E+05"
525 The parameters are interpreted as per @nicode{~e} above. When
526 fixed-point is used, the @var{decimals} parameter to @nicode{~f} is
527 established from @var{mantdigits}, so as to give a total
528 @math{@var{mantdigits}+1} figures.
531 Monetary style fixed-point float. Parameters: @var{decimals},
532 @var{intdigits}, @var{width}, @var{padchar}.
534 @c For reference, fmtdoc.txi from past versions of slib showed the
535 @c INTDIGITS parameter as SCALE. That looks like a typo, in the code
536 @c and in the Common Lisp spec it's a minimum digits for the integer
537 @c part, it isn't a power of 10 like in ~f.
539 Output a number or number string in fixed-point format, ie.@: with a
540 decimal point. @var{decimals} is the number of decimal places to
544 (format #t "~$" 5) @print{} 5.00
545 (format #t "~4$" "2.25") @print{} 2.2500
546 (format #t "~4$" "1e-2") @print{} 0.0100
549 @nicode{~@@$} prints a @nicode{+} sign on positive numbers (including
553 (format #t "~@@$" 0) @print{} +0.00
556 @var{intdigits} is a minimum number of digits to show in the integer
557 part of the value (default 1).
560 (format #t "~,3$" 9.5) @print{} 009.50
561 (format #t "~,0$" 0.125) @print{} .13
564 If the output is less than @var{width} characters (default 0), it's
565 padded on the left with @var{padchar} (default space). @nicode{~:$}
566 puts the padding after the sign.
569 (format #f "~,,8$" -1.5) @result{} " -1.50"
570 (format #f "~,,8:$" -1.5) @result{} "- 1.50"
571 (format #f "~,,8,'.:@@$" 3) @result{} "+...3.00"
574 Note that floating point for dollar amounts is generally not a good
575 idea, because a cent @math{0.01} cannot be represented exactly in the
576 binary floating point Guile uses, which leads to slowly accumulating
577 rounding errors. Keeping values as cents (or fractions of a cent) in
578 integers then printing with the scale option in @nicode{~f} may be a
581 @c For reference, fractions don't work with ~$ (or any of the float
582 @c conversions) currently. If they did work then we could perhaps
583 @c suggest keeping dollar amounts as rationals, which would of course
584 @c give exact cents. An integer as cents is probably still a better
585 @c recommendation though, since it forces one to think about where
586 @c and when rounding can or should occur.
589 Complex fixed-point float. Parameters: @var{width}, @var{decimals},
590 @var{scale}, @var{overflowchar}, @var{padchar}.
592 @c For reference, in Common Lisp ~i is an indent, but slib fmtdoc.txi
593 @c described it as complex number output, so we keep that.
595 Output the argument as a complex number, with both real and imaginary
596 part shown (even if one or both are zero).
598 The parameters and modifiers are the same as for fixed-point
599 @nicode{~f} described above. The real and imaginary parts are both
600 output with the same given parameters and modifiers, except that for
601 the imaginary part the @nicode{@@} modifier is always enabled, so as
602 to print a @nicode{+} sign between the real and imaginary parts.
605 (format #t "~i" 1) @print{} 1.0+0.0i
609 Plural. No parameters.
611 Output nothing if the argument is 1, or @samp{s} for any other
615 (format #t "enter name~p" 1) @print{} enter name
616 (format #t "enter name~p" 2) @print{} enter names
619 @nicode{~@@p} prints @samp{y} for 1 or @samp{ies} otherwise.
622 (format #t "pupp~@@p" 1) @print{} puppy
623 (format #t "pupp~@@p" 2) @print{} puppies
626 @nicode{~:p} re-uses the preceding argument instead of taking a new
627 one, which can be convenient when printing some sort of count.
630 (format #t "~d cat~:p" 9) @print{} 9 cats
631 (format #t "~d pupp~:@@p" 5) @print{} 5 puppies
634 @nicode{~p} is designed for English plurals and there's no attempt to
635 support other languages. @nicode{~[} conditionals (below) may be able
636 to help. When using @code{gettext} to translate messages
637 @code{ngettext} is probably best though
638 (@pxref{Internationalization}).
641 Structured printing. Parameters: @var{width}.
643 @nicode{~y} outputs an argument using @code{pretty-print}
644 (@pxref{Pretty Printing}). The result will be formatted to fit within
645 @var{width} columns (79 by default), consuming multiple lines if
648 @nicode{~@@y} outputs an argument using @code{truncated-print}
649 (@pxref{Pretty Printing}). The resulting code will be formatted to fit
650 within @var{width} columns (79 by default), on a single line. The
651 output will be truncated if necessary.
653 @nicode{~:@@y} is like @nicode{~@@y}, except the @var{width} parameter
654 is interpreted to be the maximum column to which to output. That is to
655 say, if you are at column 10, and @nicode{~60:@@y} is seen, the datum
656 will be truncated to 50 columns.
660 Sub-format. No parameters.
662 Take a format string argument and a second argument which is a list of
663 arguments for that string, and output the result.
666 (format #t "~?" "~d ~d" '(1 2)) @print{} 1 2
669 @nicode{~@@?} takes arguments for the sub-format directly rather than
673 (format #t "~@@? ~s" "~d ~d" 1 2 "foo") @print{} 1 2 "foo"
676 @nicode{~?} and @nicode{~k} are the same, @nicode{~k} is provided for
677 T-Scheme compatibility.
680 Argument jumping. Parameter: @var{N}.
682 Move forward @var{N} arguments (default 1) in the argument list.
683 @nicode{~:*} moves backwards. (@var{N} cannot be negative.)
686 (format #f "~d ~2*~d" 1 2 3 4) @result{} "1 4"
687 (format #f "~d ~:*~d" 6) @result{} "6 6"
690 @nicode{~@@*} moves to argument number @var{N}. The first argument is
691 number 0 (and that's the default for @var{N}).
694 (format #f "~d~d again ~@@*~d~d" 1 2) @result{} "12 again 12"
695 (format #f "~d~d~d ~1@@*~d~d" 1 2 3) @result{} "123 23"
698 A @nicode{#} move to the end followed by a @nicode{:} modifier move
699 back can be used for an absolute position relative to the end of the
700 argument list, a reverse of what the @nicode{@@} modifier does.
703 (format #t "~#*~2:*~a" 'a 'b 'c 'd) @print{} c
706 At the end of the format string the current argument position doesn't
707 matter, any further arguments are ignored.
710 Advance to a column position. Parameters: @var{colnum}, @var{colinc},
713 Output @var{padchar} (space by default) to move to the given
714 @var{colnum} column. The start of the line is column 0, the default
715 for @var{colnum} is 1.
718 (format #f "~tX") @result{} " X"
719 (format #f "~3tX") @result{} " X"
722 If the current column is already past @var{colnum}, then the move is
723 to there plus a multiple of @var{colinc}, ie.@: column
724 @math{@var{colnum} + @var{N} * @var{colinc}} for the smallest @var{N}
725 which makes that value greater than or equal to the current column.
726 The default @var{colinc} is 1 (which means no further move).
729 (format #f "abcd~2,5,'.tx") @result{} "abcd...x"
732 @nicode{~@@t} takes @var{colnum} as an offset from the current column.
733 @var{colnum} many pad characters are output, then further padding to
734 make the current column a multiple of @var{colinc}, if it isn't
738 (format #f "a~3,5'*@@tx") @result{} "a****x"
741 @nicode{~t} is implemented using @code{port-column} (@pxref{Reading}),
742 so it works even there has been other output before @code{format}.
745 Tilde character. Parameter: @var{n}.
747 Output a tilde character @nicode{~}, or @var{n} many if a parameter is
748 given. Normally @nicode{~} introduces an escape sequence, @nicode{~~}
749 is the way to output a literal tilde.
752 Newline. Parameter: @var{n}.
754 Output a newline character, or @var{n} many if a parameter is given.
755 A newline (or a few newlines) can of course be output just by
756 including them in the format string.
759 Start a new line. Parameter: @var{n}.
761 Output a newline if not already at the start of a line. With a
762 parameter, output that many newlines, but with the first only if not
763 already at the start of a line. So for instance 3 would be a newline
764 if not already at the start of a line, and 2 further newlines.
767 Space character. Parameter: @var{n}.
769 @c For reference, in Common Lisp ~_ is a conditional newline, but
770 @c slib fmtdoc.txi described it as a space, so we keep that.
772 Output a space character, or @var{n} many if a parameter is given.
774 With a variable parameter this is one way to insert runtime calculated
775 padding (@nicode{~t} or the various field widths can do similar
779 (format #f "~v_foo" 4) @result{} " foo"
783 Tab character. Parameter: @var{n}.
785 Output a tab character, or @var{n} many if a parameter is given.
788 Formfeed character. Parameter: @var{n}.
790 Output a formfeed character, or @var{n} many if a parameter is given.
793 Force output. No parameters.
795 At the end of output, call @code{force-output} to flush any buffers on
796 the destination (@pxref{Writing}). @nicode{~!} can occur anywhere in
797 the format string, but the force is done at the end of output.
799 When output is to a string (destination @code{#f}), @nicode{~!} does
802 @item @nicode{~newline} (ie.@: newline character)
803 Continuation line. No parameters.
805 Skip this newline and any following whitespace in the format string,
806 ie.@: don't send it to the output. This can be used to break up a
807 long format string for readability, but not print the extra
813 ~d" 1 2) @result{} "abc1 def2"
816 @nicode{~:newline} skips the newline but leaves any further whitespace
817 to be printed normally.
819 @nicode{~@@newline} prints the newline then skips following
822 @item @nicode{~(} @nicode{~)}
823 Case conversion. No parameters.
825 Between @nicode{~(} and @nicode{~)} the case of all output is changed.
826 The modifiers on @nicode{~(} control the conversion.
830 @nicode{~(} --- lower case.
832 @c FIXME: The : and @ modifiers are not yet documented because the
833 @c code applies string-capitalize and string-capitalize-first to each
834 @c separate format:out-str call, which has various subtly doubtful
835 @c effects. And worse they're applied to individual characters,
836 @c including literal characters in the format string, which has the
837 @c silly effect of being always an upcase.
839 @c The Common Lisp spec is apparently for the capitalization to be
840 @c applied in one hit to the whole of the output between ~( and ~).
841 @c (This can no doubt be implemented without accumulating all that
842 @c text, just by keeping a state or the previous char to tell whether
846 @c @nicode{:} --- first letter of each word upper case, the rest lower
847 @c case, as per the @code{string-capitalize} function (@pxref{Alphabetic
850 @c @nicode{@@} --- first letter of just the first word upper case, the
854 @nicode{~:@@(} --- upper case.
860 (format #t "~(Hello~)") @print{} hello
861 (format #t "~:@@(Hello~)") @print{} HELLO
864 In the future it's intended the modifiers @nicode{:} and @nicode{@@}
865 alone will capitalize the first letters of words, as per Common Lisp
866 @code{format}, but the current implementation of this is flawed and
867 not recommended for use.
869 Case conversions do not nest, currently. This might change in the
870 future, but if it does then it will be to Common Lisp style where the
871 outermost conversion has priority, overriding inner ones (making those
874 @item @nicode{~@{} @nicode{~@}}
875 Iteration. Parameter: @var{maxreps} (for @nicode{~@{}).
877 The format between @nicode{~@{} and @nicode{~@}} is iterated. The
878 modifiers to @nicode{~@{} determine how arguments are taken. The
879 default is a list argument with each iteration successively consuming
880 elements from it. This is a convenient way to output a whole list.
883 (format #t "~@{~d~@}" '(1 2 3)) @print{} 123
884 (format #t "~@{~s=~d ~@}" '("x" 1 "y" 2)) @print{} "x"=1 "y"=2
887 @nicode{~:@{} takes a single argument which is a list of lists, each
888 of those contained lists gives the arguments for the iterated format.
890 @c @print{} on a new line here to avoid overflowing page width in DVI
892 (format #t "~:@{~dx~d ~@}" '((1 2) (3 4) (5 6)))
896 @nicode{~@@@{} takes arguments directly, with each iteration
897 successively consuming arguments.
900 (format #t "~@@@{~d~@}" 1 2 3) @print{} 123
901 (format #t "~@@@{~s=~d ~@}" "x" 1 "y" 2) @print{} "x"=1 "y"=2
904 @nicode{~:@@@{} takes list arguments, one argument for each iteration,
905 using that list for the format.
907 @c @print{} on a new line here to avoid overflowing page width in DVI
909 (format #t "~:@@@{~dx~d ~@}" '(1 2) '(3 4) '(5 6))
913 Iterating stops when there are no more arguments or when the
914 @var{maxreps} parameter to @nicode{~@{} is reached (default no
918 (format #t "~2@{~d~@}" '(1 2 3 4)) @print{} 12
921 If the format between @nicode{~@{} and @nicode{~@}} is empty, then a
922 format string argument is taken (before iteration argument(s)) and
923 used instead. This allows a sub-format (like @nicode{~?} above) to be
927 (format #t "~@{~@}" "~d" '(1 2 3)) @print{} 123
930 @c FIXME: What is the @nicode{:} modifier to ~} meant to do? The
931 @c Common Lisp spec says it's a minimum of 1 iteration, but the
932 @c format.scm code seems to merely make it have MAXREPS default to 1.
934 Iterations can be nested, an inner iteration operates in the same way
935 as described, but of course on the arguments the outer iteration
936 provides it. This can be used to work into nested list structures.
937 For example in the following the inner @nicode{~@{~d~@}x} is applied
938 to @code{(1 2)} then @code{(3 4 5)} etc.
941 (format #t "~@{~@{~d~@}x~@}" '((1 2) (3 4 5))) @print{} 12x345x
944 See also @nicode{~^} below for escaping from iteration.
946 @item @nicode{~[} @nicode{~;} @nicode{~]}
947 Conditional. Parameter: @var{selector}.
949 A conditional block is delimited by @nicode{~[} and @nicode{~]}, and
950 @nicode{~;} separates clauses within the block. @nicode{~[} takes an
951 integer argument and that number clause is used. The first clause is
955 (format #f "~[peach~;banana~;mango~]" 1) @result{} "banana"
958 The @var{selector} parameter can be used for the clause number,
959 instead of taking an argument.
962 (format #f "~2[peach~;banana~;mango~]") @result{} "mango"
965 If the clause number is out of range then nothing is output. Or the
966 last clause can be @nicode{~:;} to use that for a number out of range.
969 (format #f "~[banana~;mango~]" 99) @result{} ""
970 (format #f "~[banana~;mango~:;fruit~]" 99) @result{} "fruit"
973 @nicode{~:[} treats the argument as a flag, and expects two clauses.
974 The first is used if the argument is @code{#f} or the second
978 (format #f "~:[false~;not false~]" #f) @result{} "false"
979 (format #f "~:[false~;not false~]" 'abc) @result{} "not false"
982 (format #t "~d gnu~:[s are~; is~] here" n (= 1 n)))
983 @print{} 3 gnus are here
986 @nicode{~@@[} also treats the argument as a flag, and expects one
987 clause. If the argument is @code{#f} then no output is produced and
988 the argument is consumed, otherwise the clause is used and the
989 argument is not consumed, it's left for the clause. This can be used
990 for instance to suppress output if @code{#f} means something not
994 (format #f "~@@[temperature=~d~]" 27) @result{} "temperature=27"
995 (format #f "~@@[temperature=~d~]" #f) @result{} ""
999 Escape. Parameters: @var{val1}, @var{val2}, @var{val3}.
1001 Stop formatting if there are no more arguments. This can be used for
1002 instance to have a format string adapt to a variable number of
1006 (format #t "~d~^ ~d" 1) @print{} 1
1007 (format #t "~d~^ ~d" 1 2) @print{} 1 2
1010 Within a @nicode{~@{} @nicode{~@}} iteration, @nicode{~^} stops the
1011 current iteration step if there are no more arguments to that step,
1012 but continuing with possible further steps and the rest of the format.
1013 This can be used for instance to avoid a separator on the last
1014 iteration, or to adapt to variable length argument lists.
1017 (format #f "~@{~d~^/~@} go" '(1 2 3)) @result{} "1/2/3 go"
1018 (format #f "~:@{ ~d~^~d~@} go" '((1) (2 3))) @result{} " 1 23 go"
1021 @c For reference, format.scm doesn't implement that Common Lisp ~:^
1022 @c modifier which stops the entire iterating of ~:{ or ~@:{.
1024 @c FIXME: Believe the Common Lisp spec is for ~^ within ~[ ~]
1025 @c conditional to terminate the whole format (or iteration step if in
1026 @c an iteration). But format.scm seems to terminate just the
1027 @c conditional form.
1029 @c (format #f "~[abc~^def~;ghi~] blah" 0)
1030 @c @result{} "abc blah" ;; looks wrong
1032 @c FIXME: Believe the Common Lisp spec is for ~^ within ~( ~) to end
1033 @c that case conversion and then also terminate the whole format (or
1034 @c iteration step if in an iteration). But format.scm doesn't seem
1035 @c to do that quite right.
1037 @c (format #f "~d ~^ ~d" 1) @result{} "1 "
1038 @c (format #f "~(~d ~^ ~d~)" 1) @result{} ERROR
1040 Within a @nicode{~?} sub-format, @nicode{~^} operates just on that
1041 sub-format. If it terminates the sub-format then the originating
1042 format will still continue.
1045 (format #t "~? items" "~d~^ ~d" '(1)) @print{} 1 items
1046 (format #t "~? items" "~d~^ ~d" '(1 2)) @print{} 1 2 items
1049 The parameters to @nicode{~^} (which are numbers) change the condition
1050 used to terminate. For a single parameter, termination is when that
1051 value is zero (notice this makes plain @nicode{~^} equivalent to
1052 @nicode{~#^}). For two parameters, termination is when those two are
1053 equal. For three parameters, termination is when @math{@var{val1}
1054 @le{} @var{val2}} and @math{@var{val2} @le{} @var{val3}}.
1056 @c FIXME: Good examples of these?
1059 Inquiry message. Insert a copyright message into the output.
1061 @nicode{~:q} inserts the format implementation version.
1065 It's an error if there are not enough arguments for the escapes in the
1066 format string, but any excess arguments are ignored.
1068 Iterations @nicode{~@{} @nicode{~@}} and conditionals @nicode{~[}
1069 @nicode{~;} @nicode{~]} can be nested, but must be properly nested,
1070 meaning the inner form must be entirely within the outer form. So
1071 it's not possible, for instance, to try to conditionalize the endpoint
1075 (format #t "~@{ ~[ ... ~] ~@}" ...) ;; good
1076 (format #t "~@{ ~[ ... ~@} ... ~]" ...) ;; bad
1079 The same applies to case conversions @nicode{~(} @nicode{~)}, they
1080 must properly nest with respect to iterations and conditionals (though
1081 currently a case conversion cannot nest within another case
1084 When a sub-format (@nicode{~?}) is used, that sub-format string must
1085 be self-contained. It cannot for instance give a @nicode{~@{} to
1086 begin an iteration form and have the @nicode{~@}} up in the
1087 originating format, or similar.
1091 Guile contains a @code{format} procedure even when the module
1092 @code{(ice-9 format)} is not loaded. The default @code{format} is
1093 @code{simple-format} (@pxref{Writing}), it doesn't support all escape
1094 sequences documented in this section, and will signal an error if you
1095 try to use one of them. The reason for two versions is that the full
1096 @code{format} is fairly large and requires some time to load.
1097 @code{simple-format} is often adequate too.
1100 @node File Tree Walk
1101 @section File Tree Walk
1102 @cindex file tree walk
1104 The functions in this section traverse a tree of files and
1105 directories, in a fashion similar to the C @code{ftw} and @code{nftw}
1106 routines (@pxref{Working with Directory Trees,,, libc, GNU C Library
1110 (use-modules (ice-9 ftw))
1114 @defun ftw startname proc ['hash-size n]
1115 Walk the file system tree descending from @var{startname}, calling
1116 @var{proc} for each file and directory.
1118 Hard links and symbolic links are followed. A file or directory is
1119 reported to @var{proc} only once, and skipped if seen again in another
1120 place. One consequence of this is that @code{ftw} is safe against
1121 circularly linked directory structures.
1123 Each @var{proc} call is @code{(@var{proc} filename statinfo flag)} and
1124 it should return @code{#t} to continue, or any other value to stop.
1126 @var{filename} is the item visited, being @var{startname} plus a
1127 further path and the name of the item. @var{statinfo} is the return
1128 from @code{stat} (@pxref{File System}) on @var{filename}. @var{flag}
1129 is one of the following symbols,
1133 @var{filename} is a file, this includes special files like devices,
1137 @var{filename} is a directory.
1140 An error occurred when calling @code{stat}, so nothing is known.
1141 @var{statinfo} is @code{#f} in this case.
1143 @item directory-not-readable
1144 @var{filename} is a directory, but one which cannot be read and hence
1145 won't be recursed into.
1148 @var{filename} is a dangling symbolic link. Symbolic links are
1149 normally followed and their target reported, the link itself is
1150 reported if the target does not exist.
1153 The return value from @code{ftw} is @code{#t} if it ran to completion,
1154 or otherwise the non-@code{#t} value from @var{proc} which caused the
1157 Optional argument symbol @code{hash-size} and an integer can be given
1158 to set the size of the hash table used to track items already visited.
1159 (@pxref{Hash Table Reference})
1161 @c Actually, it's probably safe to escape from ftw, just need to
1164 In the current implementation, returning non-@code{#t} from @var{proc}
1165 is the only valid way to terminate @code{ftw}. @var{proc} must not
1166 use @code{throw} or similar to escape.
1170 @defun nftw startname proc ['chdir] ['depth] ['hash-size n] ['mount] ['physical]
1171 Walk the file system tree starting at @var{startname}, calling
1172 @var{proc} for each file and directory. @code{nftw} has extra
1173 features over the basic @code{ftw} described above.
1175 Like @code{ftw}, hard links and symbolic links are followed. A file
1176 or directory is reported to @var{proc} only once, and skipped if seen
1177 again in another place. One consequence of this is that @code{nftw}
1178 is safe against circular linked directory structures.
1180 Each @var{proc} call is @code{(@var{proc} filename statinfo flag
1181 base level)} and it should return @code{#t} to continue, or any
1182 other value to stop.
1184 @var{filename} is the item visited, being @var{startname} plus a
1185 further path and the name of the item. @var{statinfo} is the return
1186 from @code{stat} on @var{filename} (@pxref{File System}). @var{base}
1187 is an integer offset into @var{filename} which is where the basename
1188 for this item begins. @var{level} is an integer giving the directory
1189 nesting level, starting from 0 for the contents of @var{startname} (or
1190 that item itself if it's a file). @var{flag} is one of the following
1195 @var{filename} is a file, including special files like devices, named
1199 @var{filename} is a directory.
1201 @item directory-processed
1202 @var{filename} is a directory, and its contents have all been visited.
1203 This flag is given instead of @code{directory} when the @code{depth}
1204 option below is used.
1207 An error occurred when applying @code{stat} to @var{filename}, so
1208 nothing is known about it. @var{statinfo} is @code{#f} in this case.
1210 @item directory-not-readable
1211 @var{filename} is a directory, but one which cannot be read and hence
1212 won't be recursed into.
1215 @var{filename} is a dangling symbolic link. Links are normally
1216 followed and their target reported, the link itself is reported if its
1217 target does not exist.
1220 When the @code{physical} option described below is used, this
1221 indicates @var{filename} is a symbolic link whose target exists (and
1222 is not being followed).
1225 The following optional arguments can be given to modify the way
1226 @code{nftw} works. Each is passed as a symbol (and @code{hash-size}
1227 takes a following integer value).
1231 Change to the directory containing the item before calling @var{proc}.
1232 When @code{nftw} returns the original current directory is restored.
1234 Under this option, generally the @var{base} parameter to each
1235 @var{proc} call should be used to pick out the base part of the
1236 @var{filename}. The @var{filename} is still a path but with a changed
1237 directory it won't be valid (unless the @var{startname} directory was
1241 Visit files ``depth first'', meaning @var{proc} is called for the
1242 contents of each directory before it's called for the directory
1243 itself. Normally a directory is reported first, then its contents.
1245 Under this option, the @var{flag} to @var{proc} for a directory is
1246 @code{directory-processed} instead of @code{directory}.
1248 @item @code{hash-size @var{n}}
1249 Set the size of the hash table used to track items already visited.
1250 (@pxref{Hash Table Reference})
1253 Don't cross a mount point, meaning only visit items on the same
1254 file system as @var{startname} (ie.@: the same @code{stat:dev}).
1256 @item @code{physical}
1257 Don't follow symbolic links, instead report them to @var{proc} as
1258 @code{symlink}. Dangling links (those whose target doesn't exist) are
1259 still reported as @code{stale-symlink}.
1262 The return value from @code{nftw} is @code{#t} if it ran to
1263 completion, or otherwise the non-@code{#t} value from @var{proc} which
1266 @c For reference, one reason not to esacpe is that the current
1267 @c directory is not saved and restored with dynamic-wind. Maybe
1268 @c changing that would be enough to allow escaping.
1270 In the current implementation, returning non-@code{#t} from @var{proc}
1271 is the only valid way to terminate @code{ftw}. @var{proc} must not
1272 use @code{throw} or similar to escape.
1282 The functions in this section are provided by
1285 (use-modules (ice-9 q))
1288 This module implements queues holding arbitrary scheme objects and
1289 designed for efficient first-in / first-out operations.
1291 @code{make-q} creates a queue, and objects are entered and removed
1292 with @code{enq!} and @code{deq!}. @code{q-push!} and @code{q-pop!}
1293 can be used too, treating the front of the queue like a stack.
1297 @deffn {Scheme Procedure} make-q
1301 @deffn {Scheme Procedure} q? obj
1302 Return @code{#t} if @var{obj} is a queue, or @code{#f} if not.
1304 Note that queues are not a distinct class of objects but are
1305 implemented with cons cells. For that reason certain list structures
1306 can get @code{#t} from @code{q?}.
1309 @deffn {Scheme Procedure} enq! q obj
1310 Add @var{obj} to the rear of @var{q}, and return @var{q}.
1313 @deffn {Scheme Procedure} deq! q
1314 @deffnx {Scheme Procedure} q-pop! q
1315 Remove and return the front element from @var{q}. If @var{q} is
1316 empty, a @code{q-empty} exception is thrown.
1318 @code{deq!} and @code{q-pop!} are the same operation, the two names
1319 just let an application match @code{enq!} with @code{deq!}, or
1320 @code{q-push!} with @code{q-pop!}.
1323 @deffn {Scheme Procedure} q-push! q obj
1324 Add @var{obj} to the front of @var{q}, and return @var{q}.
1327 @deffn {Scheme Procedure} q-length q
1328 Return the number of elements in @var{q}.
1331 @deffn {Scheme Procedure} q-empty? q
1332 Return true if @var{q} is empty.
1335 @deffn {Scheme Procedure} q-empty-check q
1336 Throw a @code{q-empty} exception if @var{q} is empty.
1339 @deffn {Scheme Procedure} q-front q
1340 Return the first element of @var{q} (without removing it). If @var{q}
1341 is empty, a @code{q-empty} exception is thrown.
1344 @deffn {Scheme Procedure} q-rear q
1345 Return the last element of @var{q} (without removing it). If @var{q}
1346 is empty, a @code{q-empty} exception is thrown.
1349 @deffn {Scheme Procedure} q-remove! q obj
1350 Remove all occurrences of @var{obj} from @var{q}, and return @var{q}.
1351 @var{obj} is compared to queue elements using @code{eq?}.
1355 @cindex @code{q-empty}
1356 The @code{q-empty} exceptions described above are thrown just as
1357 @code{(throw 'q-empty)}, there's no message etc like an error throw.
1359 A queue is implemented as a cons cell, the @code{car} containing a
1360 list of queued elements, and the @code{cdr} being the last cell in
1361 that list (for ease of enqueuing).
1364 (@var{list} . @var{last-cell})
1368 If the queue is empty, @var{list} is the empty list and
1369 @var{last-cell} is @code{#f}.
1371 An application can directly access the queue list if desired, for
1372 instance to search the elements or to insert at a specific point.
1374 @deffn {Scheme Procedure} sync-q! q
1375 Recompute the @var{last-cell} field in @var{q}.
1377 All the operations above maintain @var{last-cell} as described, so
1378 normally there's no need for @code{sync-q!}. But if an application
1379 modifies the queue @var{list} then it must either maintain
1380 @var{last-cell} similarly, or call @code{sync-q!} to recompute it.
1388 A stream represents a sequence of values, each of which is calculated
1389 only when required. This allows large or even infinite sequences to
1390 be represented and manipulated with familiar operations like ``car'',
1391 ``cdr'', ``map'' or ``fold''. In such manipulations only as much as
1392 needed is actually held in memory at any one time. The functions in
1393 this section are available from
1396 (use-modules (ice-9 streams))
1399 Streams are implemented using promises (@pxref{Delayed Evaluation}),
1400 which is how the underlying calculation of values is made only when
1401 needed, and the values then retained so the calculation is not
1405 Here is a simple example producing a stream of all odd numbers,
1408 (define odds (make-stream (lambda (state)
1409 (cons state (+ state 2)))
1411 (stream-car odds) @result{} 1
1412 (stream-car (stream-cdr odds)) @result{} 3
1416 @code{stream-map} could be used to derive a stream of odd squares,
1419 (define (square n) (* n n))
1420 (define oddsquares (stream-map square odds))
1423 These are infinite sequences, so it's not possible to convert them to
1424 a list, but they could be printed (infinitely) with for example
1427 (stream-for-each (lambda (n sq)
1428 (format #t "~a squared is ~a\n" n sq))
1439 @defun make-stream proc initial-state
1440 Return a new stream, formed by calling @var{proc} successively.
1442 Each call is @code{(@var{proc} @var{state})}, it should return a pair,
1443 the @code{car} being the value for the stream, and the @code{cdr}
1444 being the new @var{state} for the next call. For the first call
1445 @var{state} is the given @var{initial-state}. At the end of the
1446 stream, @var{proc} should return some non-pair object.
1449 @defun stream-car stream
1450 Return the first element from @var{stream}. @var{stream} must not be
1454 @defun stream-cdr stream
1455 Return a stream which is the second and subsequent elements of
1456 @var{stream}. @var{stream} must not be empty.
1459 @defun stream-null? stream
1460 Return true if @var{stream} is empty.
1463 @defun list->stream list
1464 @defunx vector->stream vector
1465 Return a stream with the contents of @var{list} or @var{vector}.
1467 @var{list} or @var{vector} should not be modified subsequently, since
1468 it's unspecified whether changes there will be reflected in the stream
1472 @defun port->stream port readproc
1473 Return a stream which is the values obtained by reading from
1474 @var{port} using @var{readproc}. Each read call is
1475 @code{(@var{readproc} @var{port})}, and it should return an EOF object
1476 (@pxref{Reading}) at the end of input.
1478 For example a stream of characters from a file,
1481 (port->stream (open-input-file "/foo/bar.txt") read-char)
1485 @defun stream->list stream
1486 Return a list which is the entire contents of @var{stream}.
1489 @defun stream->reversed-list stream
1490 Return a list which is the entire contents of @var{stream}, but in
1494 @defun stream->list&length stream
1495 Return two values (@pxref{Multiple Values}), being firstly a list
1496 which is the entire contents of @var{stream}, and secondly the number
1497 of elements in that list.
1500 @defun stream->reversed-list&length stream
1501 Return two values (@pxref{Multiple Values}) being firstly a list which
1502 is the entire contents of @var{stream}, but in reverse order, and
1503 secondly the number of elements in that list.
1506 @defun stream->vector stream
1507 Return a vector which is the entire contents of @var{stream}.
1510 @defun stream-fold proc init stream0 @dots{} streamN
1511 Apply @var{proc} successively over the elements of the given streams,
1512 from first to last until the end of the shortest stream is reached.
1513 Return the result from the last @var{proc} call.
1515 Each call is @code{(@var{proc} elem0 @dots{} elemN prev)}, where each
1516 @var{elem} is from the corresponding @var{stream}. @var{prev} is the
1517 return from the previous @var{proc} call, or the given @var{init} for
1521 @defun stream-for-each proc stream0 @dots{} streamN
1522 Call @var{proc} on the elements from the given @var{stream}s. The
1523 return value is unspecified.
1525 Each call is @code{(@var{proc} elem0 @dots{} elemN)}, where each
1526 @var{elem} is from the corresponding @var{stream}.
1527 @code{stream-for-each} stops when it reaches the end of the shortest
1531 @defun stream-map proc stream0 @dots{} streamN
1532 Return a new stream which is the results of applying @var{proc} to the
1533 elements of the given @var{stream}s.
1535 Each call is @code{(@var{proc} elem0 @dots{} elemN)}, where each
1536 @var{elem} is from the corresponding @var{stream}. The new stream
1537 ends when the end of the shortest given @var{stream} is reached.
1541 @node Buffered Input
1542 @section Buffered Input
1543 @cindex Buffered input
1544 @cindex Line continuation
1546 The following functions are provided by
1549 (use-modules (ice-9 buffered-input))
1552 A buffered input port allows a reader function to return chunks of
1553 characters which are to be handed out on reading the port. A notion
1554 of further input for an application level logical expression is
1555 maintained too, and passed through to the reader.
1557 @defun make-buffered-input-port reader
1558 Create an input port which returns characters obtained from the given
1559 @var{reader} function. @var{reader} is called (@var{reader} cont),
1560 and should return a string or an EOF object.
1562 The new port gives precisely the characters returned by @var{reader},
1563 nothing is added, so if any newline characters or other separators are
1564 desired they must come from the reader function.
1566 The @var{cont} parameter to @var{reader} is @code{#f} for initial
1567 input, or @code{#t} when continuing an expression. This is an
1568 application level notion, set with
1569 @code{set-buffered-input-continuation?!} below. If the user has
1570 entered a partial expression then it allows @var{reader} for instance
1571 to give a different prompt to show more is required.
1574 @defun make-line-buffered-input-port reader
1575 @cindex Line buffered input
1576 Create an input port which returns characters obtained from the
1577 specified @var{reader} function, similar to
1578 @code{make-buffered-input-port} above, but where @var{reader} is
1579 expected to be a line-oriented.
1581 @var{reader} is called (@var{reader} cont), and should return a string
1582 or an EOF object as above. Each string is a line of input without a
1583 newline character, the port code inserts a newline after each string.
1586 @defun set-buffered-input-continuation?! port cont
1587 Set the input continuation flag for a given buffered input
1590 An application uses this by calling with a @var{cont} flag of
1591 @code{#f} when beginning to read a new logical expression. For
1592 example with the Scheme @code{read} function (@pxref{Scheme Read}),
1595 (define my-port (make-buffered-input-port my-reader))
1597 (set-buffered-input-continuation?! my-port #f)
1598 (let ((obj (read my-port)))
1605 @c TeX-master: "guile.texi"