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.
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{x} will be printed using
94 @code{write}, though that behavior can be overriden 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-expressoin of @var{x} --
99 e.g., if @var{x} is a vector, each member of @var{x}. 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 [args@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).
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).
303 (format #t "~:d" 1234567) @print{} 1,234,567
304 (format #t "~10,'*,'/,2:d" 12345) @print{} ***1/23/45
307 Hexadecimal @nicode{~x} output is in lower case, but the @nicode{~(}
308 and @nicode{~)} case conversion directives described below can be used
312 (format #t "~x" 65261) @print{} feed
313 (format #t "~:@@(~x~)" 65261) @print{} FEED
317 Integer in words, roman numerals, or a specified radix. Parameters:
318 @var{radix}, @var{minwidth}, @var{padchar}, @var{commachar},
321 With no parameters output is in words as a cardinal like ``ten'', or
322 @nicode{~:r} prints an ordinal like ``tenth''.
325 (format #t "~r" 9) @print{} nine ;; cardinal
326 (format #t "~r" -9) @print{} minus nine ;; cardinal
327 (format #t "~:r" 9) @print{} ninth ;; ordinal
330 And also with no parameters, @nicode{~@@r} gives roman numerals and
331 @nicode{~:@@r} gives old roman numerals. In old roman numerals
332 there's no ``subtraction'', so 9 is @nicode{VIIII} instead of
333 @nicode{IX}. In both cases only positive numbers can be output.
336 (format #t "~@@r" 89) @print{} LXXXIX ;; roman
337 (format #t "~:@@r" 89) @print{} LXXXVIIII ;; old roman
340 When a parameter is given it means numeric output in the specified
341 @var{radix}. The modifiers and parameters following the radix are the
342 same as described for @nicode{~d} etc above.
345 (format #f "~3r" 27) @result{} "1000" ;; base 3
346 (format #f "~3,5r" 26) @result{} " 222" ;; base 3 width 5
350 Fixed-point float. Parameters: @var{width}, @var{decimals},
351 @var{scale}, @var{overflowchar}, @var{padchar}.
353 Output a number or number string in fixed-point format, ie.@: with a
357 (format #t "~f" 5) @print{} 5.0
358 (format #t "~f" "123") @print{} 123.0
359 (format #t "~f" "1e-1") @print{} 0.1
362 @nicode{~@@f} prints a @nicode{+} sign on positive numbers (including
366 (format #t "~@@f" 0) @print{} +0.0
369 If the output is less than @var{width} characters it's padded on the
370 left with @var{padchar} (space by default). If the output equals or
371 exceeds @var{width} then there's no padding. The default for
372 @var{width} is no padding.
375 (format #f "~6f" -1.5) @result{} " -1.5"
376 (format #f "~6,,,,'*f" 23) @result{} "**23.0"
377 (format #f "~6f" 1234567.0) @result{} "1234567.0"
380 @var{decimals} is how many digits to print after the decimal point,
381 with the value rounded or padded with zeros as necessary. (The
382 default is to output as many decimals as required.)
385 (format #t "~1,2f" 3.125) @print{} 3.13
386 (format #t "~1,2f" 1.5) @print{} 1.50
389 @var{scale} is a power of 10 applied to the value, moving the decimal
390 point that many places. A positive @var{scale} increases the value
391 shown, a negative decreases it.
394 (format #t "~,,2f" 1234) @print{} 123400.0
395 (format #t "~,,-2f" 1234) @print{} 12.34
398 If @var{overflowchar} and @var{width} are both given and if the output
399 would exceed @var{width}, then that many @var{overflowchar}s are
400 printed instead of the value.
403 (format #t "~5,,,'xf" 12345) @print{} 12345
404 (format #t "~4,,,'xf" 12345) @print{} xxxx
408 Exponential float. Parameters: @var{width}, @var{mantdigits},
409 @var{expdigits}, @var{intdigits}, @var{overflowchar}, @var{padchar},
412 Output a number or number string in exponential notation.
415 (format #t "~e" 5000.25) @print{} 5.00025E+3
416 (format #t "~e" "123.4") @print{} 1.234E+2
417 (format #t "~e" "1e4") @print{} 1.0E+4
420 @nicode{~@@e} prints a @nicode{+} sign on positive numbers (including
421 zero). (This is for the mantissa, a @nicode{+} or @nicode{-} sign is
422 always shown on the exponent.)
425 (format #t "~@@e" 5000.0) @print{} +5.0E+3
428 If the output is less than @var{width} characters it's padded on the
429 left with @var{padchar} (space by default). The default for
430 @var{width} is to output with no padding.
433 (format #f "~10e" 1234.0) @result{} " 1.234E+3"
434 (format #f "~10,,,,,'*e" 0.5) @result{} "****5.0E-1"
437 @c FIXME: Describe what happens when the number is bigger than WIDTH.
438 @c There seems to be a bit of dodginess about this, or some deviation
441 @var{mantdigits} is the number of digits shown in the mantissa after
442 the decimal point. The value is rounded or trailing zeros are added
443 as necessary. The default @var{mantdigits} is to show as much as
447 (format #f "~,3e" 11111.0) @result{} "1.111E+4"
448 (format #f "~,8e" 123.0) @result{} "1.23000000E+2"
451 @var{expdigits} is the minimum number of digits shown for the
452 exponent, with leading zeros added if necessary. The default for
453 @var{expdigits} is to show only as many digits as required. At least
454 1 digit is always shown.
457 (format #f "~,,1e" 1.0e99) @result{} "1.0E+99"
458 (format #f "~,,6e" 1.0e99) @result{} "1.0E+000099"
461 @var{intdigits} (default 1) is the number of digits to show before the
462 decimal point in the mantissa. @var{intdigits} can be zero, in which
463 case the integer part is a single @nicode{0}, or it can be negative,
464 in which case leading zeros are shown after the decimal point.
466 @c FIXME: When INTDIGITS is 0, Common Lisp format apparently only
467 @c shows the single 0 digit if it fits in WIDTH. format.scm seems to
468 @c show it always. Is it meant to?
471 (format #t "~,,,3e" 12345.0) @print{} 123.45E+2
472 (format #t "~,,,0e" 12345.0) @print{} 0.12345E+5
473 (format #t "~,,,-3e" 12345.0) @print{} 0.00012345E+8
476 @c FIXME: MANTDIGITS with negative INTDIGITS doesn't match CL spec,
477 @c believe the spec says it ought to still show mantdigits+1 sig
478 @c figures, ie. leading zeros don't count towards MANTDIGITS, but it
479 @c seems to just treat MANTDIGITS as how many digits after the
482 If @var{overflowchar} is given then @var{width} is a hard limit. If
483 the output would exceed @var{width} then instead that many
484 @var{overflowchar}s are printed.
487 (format #f "~6,,,,'xe" 100.0) @result{} "1.0E+2"
488 (format #f "~3,,,,'xe" 100.0) @result{} "xxx"
491 @var{expchar} is the exponent marker character (default @nicode{E}).
494 (format #t "~,,,,,,'ee" 100.0) @print{} 1.0e+2
498 General float. Parameters: @var{width}, @var{mantdigits},
499 @var{expdigits}, @var{intdigits}, @var{overflowchar}, @var{padchar},
502 Output a number or number string in either exponential format the same
503 as @nicode{~e}, or fixed-point format like @nicode{~f} but aligned
504 where the mantissa would have been and followed by padding where the
505 exponent would have been.
507 @c FIXME: The default MANTDIGITS is apparently max(needed,min(n,7))
508 @c where 10^(n-1)<=abs(x)<=10^n. But the Common Lisp spec seems to
509 @c ask for "needed" to be without leading or trailing zeros, whereas
510 @c format.scm seems to include trailing zeros, ending up with it
511 @c using fixed format for bigger values than it should.
513 Fixed-point is used when the absolute value is 0.1 or more and it
514 takes no more space than the mantissa in exponential format, ie.@:
515 basically up to @var{mantdigits} digits.
518 (format #f "~12,4,2g" 999.0) @result{} " 999.0 "
519 (format #f "~12,4,2g" "100000") @result{} " 1.0000E+05"
522 The parameters are interpreted as per @nicode{~e} above. When
523 fixed-point is used, the @var{decimals} parameter to @nicode{~f} is
524 established from @var{mantdigits}, so as to give a total
525 @math{@var{mantdigits}+1} figures.
528 Monetary style fixed-point float. Parameters: @var{decimals},
529 @var{intdigits}, @var{width}, @var{padchar}.
531 @c For reference, fmtdoc.txi from past versions of slib showed the
532 @c INTDIGITS parameter as SCALE. That looks like a typo, in the code
533 @c and in the Common Lisp spec it's a minimum digits for the integer
534 @c part, it isn't a power of 10 like in ~f.
536 Output a number or number string in fixed-point format, ie.@: with a
537 decimal point. @var{decimals} is the number of decimal places to
541 (format #t "~$" 5) @print{} 5.00
542 (format #t "~4$" "2.25") @print{} 2.2500
543 (format #t "~4$" "1e-2") @print{} 0.0100
546 @nicode{~@@$} prints a @nicode{+} sign on positive numbers (including
550 (format #t "~@@$" 0) @print{} +0.00
553 @var{intdigits} is a minimum number of digits to show in the integer
554 part of the value (default 1).
557 (format #t "~,3$" 9.5) @print{} 009.50
558 (format #t "~,0$" 0.125) @print{} .13
561 If the output is less than @var{width} characters (default 0), it's
562 padded on the left with @var{padchar} (default space). @nicode{~:$}
563 puts the padding after the sign.
566 (format #f "~,,8$" -1.5) @result{} " -1.50"
567 (format #f "~,,8:$" -1.5) @result{} "- 1.50"
568 (format #f "~,,8,'.:@@$" 3) @result{} "+...3.00"
571 Note that floating point for dollar amounts is generally not a good
572 idea, because a cent @math{0.01} cannot be represented exactly in the
573 binary floating point Guile uses, which leads to slowly accumulating
574 rounding errors. Keeping values as cents (or fractions of a cent) in
575 integers then printing with the scale option in @nicode{~f} may be a
578 @c For reference, fractions don't work with ~$ (or any of the float
579 @c conversions) currently. If they did work then we could perhaps
580 @c suggest keeping dollar amounts as rationals, which would of course
581 @c give exact cents. An integer as cents is probably still a better
582 @c recommendation though, since it forces one to think about where
583 @c and when rounding can or should occur.
586 Complex fixed-point float. Parameters: @var{width}, @var{decimals},
587 @var{scale}, @var{overflowchar}, @var{padchar}.
589 @c For reference, in Common Lisp ~i is an indent, but slib fmtdoc.txi
590 @c described it as complex number output, so we keep that.
592 Output the argument as a complex number, with both real and imaginary
593 part shown (even if one or both are zero).
595 The parameters and modifiers are the same as for fixed-point
596 @nicode{~f} described above. The real and imaginary parts are both
597 output with the same given parameters and modifiers, except that for
598 the imaginary part the @nicode{@@} modifier is always enabled, so as
599 to print a @nicode{+} sign between the real and imaginary parts.
602 (format #t "~i" 1) @print{} 1.0+0.0i
606 Plural. No parameters.
608 Output nothing if the argument is 1, or @samp{s} for any other
612 (format #t "enter name~p" 1) @print{} enter name
613 (format #t "enter name~p" 2) @print{} enter names
616 @nicode{~@@p} prints @samp{y} for 1 or @samp{ies} otherwise.
619 (format #t "pupp~@@p" 1) @print{} puppy
620 (format #t "pupp~@@p" 2) @print{} puppies
623 @nicode{~:p} re-uses the preceding argument instead of taking a new
624 one, which can be convenient when printing some sort of count.
627 (format #t "~d cat~:p" 9) @print{} 9 cats
628 (format #t "~d pupp~:@@p" 5) @print{} 5 puppies
631 @nicode{~p} is designed for English plurals and there's no attempt to
632 support other languages. @nicode{~[} conditionals (below) may be able
633 to help. When using @code{gettext} to translate messages
634 @code{ngettext} is probably best though
635 (@pxref{Internationalization}).
638 Structured printing. Parameters: @var{width}.
640 @nicode{~y} outputs an argument using @code{pretty-print}
641 (@pxref{Pretty Printing}). The result will be formatted to fit within
642 @var{width} columns (79 by default), consuming multiple lines if
645 @nicode{~@@y} outputs an argument using @code{truncated-print}
646 (@pxref{Pretty Printing}). The resulting code will be formatted to fit
647 within @var{width} columns (79 by default), on a single line. The
648 output will be truncated if necessary.
650 @nicode{~:@@y} is like @nicode{~@@y}, except the @var{width} parameter
651 is interpreted to be the maximum column to which to output. That is to
652 say, if you are at column 10, and @nicode{~60:@@y} is seen, the datum
653 will be truncated to 50 columns.
657 Sub-format. No parameters.
659 Take a format string argument and a second argument which is a list of
660 arguments for that string, and output the result.
663 (format #t "~?" "~d ~d" '(1 2)) @print{} 1 2
666 @nicode{~@@?} takes arguments for the sub-format directly rather than
670 (format #t "~@@? ~s" "~d ~d" 1 2 "foo") @print{} 1 2 "foo"
673 @nicode{~?} and @nicode{~k} are the same, @nicode{~k} is provided for
674 T-Scheme compatibility.
677 Argument jumping. Parameter: @var{N}.
679 Move forward @var{N} arguments (default 1) in the argument list.
680 @nicode{~:*} moves backwards. (@var{N} cannot be negative.)
683 (format #f "~d ~2*~d" 1 2 3 4) @result{} "1 4"
684 (format #f "~d ~:*~d" 6) @result{} "6 6"
687 @nicode{~@@*} moves to argument number @var{N}. The first argument is
688 number 0 (and that's the default for @var{N}).
691 (format #f "~d~d again ~@@*~d~d" 1 2) @result{} "12 again 12"
692 (format #f "~d~d~d ~1@@*~d~d" 1 2 3) @result{} "123 23"
695 A @nicode{#} move to the end followed by a @nicode{:} modifier move
696 back can be used for an absolute position relative to the end of the
697 argument list, a reverse of what the @nicode{@@} modifier does.
700 (format #t "~#*~2:*~a" 'a 'b 'c 'd) @print{} c
703 At the end of the format string the current argument position doesn't
704 matter, any further arguments are ignored.
707 Advance to a column position. Parameters: @var{colnum}, @var{colinc},
710 Output @var{padchar} (space by default) to move to the given
711 @var{colnum} column. The start of the line is column 0, the default
712 for @var{colnum} is 1.
715 (format #f "~tX") @result{} " X"
716 (format #f "~3tX") @result{} " X"
719 If the current column is already past @var{colnum}, then the move is
720 to there plus a multiple of @var{colinc}, ie.@: column
721 @math{@var{colnum} + @var{N} * @var{colinc}} for the smallest @var{N}
722 which makes that value greater than or equal to the current column.
723 The default @var{colinc} is 1 (which means no further move).
726 (format #f "abcd~2,5,'.tx") @result{} "abcd...x"
729 @nicode{~@@t} takes @var{colnum} as an offset from the current column.
730 @var{colnum} many pad characters are output, then further padding to
731 make the current column a multiple of @var{colinc}, if it isn't
735 (format #f "a~3,5'*@@tx") @result{} "a****x"
738 @nicode{~t} is implemented using @code{port-column} (@pxref{Reading}),
739 so it works even there has been other output before @code{format}.
742 Tilde character. Parameter: @var{n}.
744 Output a tilde character @nicode{~}, or @var{n} many if a parameter is
745 given. Normally @nicode{~} introduces an escape sequence, @nicode{~~}
746 is the way to output a literal tilde.
749 Newline. Parameter: @var{n}.
751 Output a newline character, or @var{n} many if a parameter is given.
752 A newline (or a few newlines) can of course be output just by
753 including them in the format string.
756 Start a new line. Parameter: @var{n}.
758 Output a newline if not already at the start of a line. With a
759 parameter, output that many newlines, but with the first only if not
760 already at the start of a line. So for instance 3 would be a newline
761 if not already at the start of a line, and 2 further newlines.
764 Space character. Parameter: @var{n}.
766 @c For reference, in Common Lisp ~_ is a conditional newline, but
767 @c slib fmtdoc.txi described it as a space, so we keep that.
769 Output a space character, or @var{n} many if a parameter is given.
771 With a variable parameter this is one way to insert runtime calculated
772 padding (@nicode{~t} or the various field widths can do similar
776 (format #f "~v_foo" 4) @result{} " foo"
780 Tab character. Parameter: @var{n}.
782 Output a tab character, or @var{n} many if a parameter is given.
785 Formfeed character. Parameter: @var{n}.
787 Output a formfeed character, or @var{n} many if a parameter is given.
790 Force output. No parameters.
792 At the end of output, call @code{force-output} to flush any buffers on
793 the destination (@pxref{Writing}). @nicode{~!} can occur anywhere in
794 the format string, but the force is done at the end of output.
796 When output is to a string (destination @code{#f}), @nicode{~!} does
799 @item @nicode{~newline} (ie.@: newline character)
800 Continuation line. No parameters.
802 Skip this newline and any following whitespace in the format string,
803 ie.@: don't send it to the output. This can be used to break up a
804 long format string for readability, but not print the extra
810 ~d" 1 2) @result{} "abc1 def2"
813 @nicode{~:newline} skips the newline but leaves any further whitespace
814 to be printed normally.
816 @nicode{~@@newline} prints the newline then skips following
819 @item @nicode{~(} @nicode{~)}
820 Case conversion. No parameters.
822 Between @nicode{~(} and @nicode{~)} the case of all output is changed.
823 The modifiers on @nicode{~(} control the conversion.
827 @nicode{~(} --- lower case.
829 @c FIXME: The : and @ modifiers are not yet documented because the
830 @c code applies string-capitalize and string-capitalize-first to each
831 @c separate format:out-str call, which has various subtly doubtful
832 @c effects. And worse they're applied to individual characters,
833 @c including literal characters in the format string, which has the
834 @c silly effect of being always an upcase.
836 @c The Common Lisp spec is apparently for the capitalization to be
837 @c applied in one hit to the whole of the output between ~( and ~).
838 @c (This can no doubt be implemented without accumulating all that
839 @c text, just by keeping a state or the previous char to tell whether
843 @c @nicode{:} --- first letter of each word upper case, the rest lower
844 @c case, as per the @code{string-capitalize} function (@pxref{Alphabetic
847 @c @nicode{@@} --- first letter of just the first word upper case, the
851 @nicode{~:@@(} --- upper case.
857 (format #t "~(Hello~)") @print{} hello
858 (format #t "~:@@(Hello~)") @print{} HELLO
861 In the future it's intended the modifiers @nicode{:} and @nicode{@@}
862 alone will capitalize the first letters of words, as per Common Lisp
863 @code{format}, but the current implementation of this is flawed and
864 not recommended for use.
866 Case conversions do not nest, currently. This might change in the
867 future, but if it does then it will be to Common Lisp style where the
868 outermost conversion has priority, overriding inner ones (making those
871 @item @nicode{~@{} @nicode{~@}}
872 Iteration. Parameter: @var{maxreps} (for @nicode{~@{}).
874 The format between @nicode{~@{} and @nicode{~@}} is iterated. The
875 modifiers to @nicode{~@{} determine how arguments are taken. The
876 default is a list argument with each iteration successively consuming
877 elements from it. This is a convenient way to output a whole list.
880 (format #t "~@{~d~@}" '(1 2 3)) @print{} 123
881 (format #t "~@{~s=~d ~@}" '("x" 1 "y" 2)) @print{} "x"=1 "y"=2
884 @nicode{~:@{} takes a single argument which is a list of lists, each
885 of those contained lists gives the arguments for the iterated format.
887 @c @print{} on a new line here to avoid overflowing page width in DVI
889 (format #t "~:@{~dx~d ~@}" '((1 2) (3 4) (5 6)))
893 @nicode{~@@@{} takes arguments directly, with each iteration
894 successively consuming arguments.
897 (format #t "~@@@{~d~@}" 1 2 3) @print{} 123
898 (format #t "~@@@{~s=~d ~@}" "x" 1 "y" 2) @print{} "x"=1 "y"=2
901 @nicode{~:@@@{} takes list arguments, one argument for each iteration,
902 using that list for the format.
904 @c @print{} on a new line here to avoid overflowing page width in DVI
906 (format #t "~:@@@{~dx~d ~@}" '(1 2) '(3 4) '(5 6))
910 Iterating stops when there are no more arguments or when the
911 @var{maxreps} parameter to @nicode{~@{} is reached (default no
915 (format #t "~2@{~d~@}" '(1 2 3 4)) @print{} 12
918 If the format between @nicode{~@{} and @nicode{~@}} is empty, then a
919 format string argument is taken (before iteration argument(s)) and
920 used instead. This allows a sub-format (like @nicode{~?} above) to be
924 (format #t "~@{~@}" "~d" '(1 2 3)) @print{} 123
927 @c FIXME: What is the @nicode{:} modifier to ~} meant to do? The
928 @c Common Lisp spec says it's a minimum of 1 iteration, but the
929 @c format.scm code seems to merely make it have MAXREPS default to 1.
931 Iterations can be nested, an inner iteration operates in the same way
932 as described, but of course on the arguments the outer iteration
933 provides it. This can be used to work into nested list structures.
934 For example in the following the inner @nicode{~@{~d~@}x} is applied
935 to @code{(1 2)} then @code{(3 4 5)} etc.
938 (format #t "~@{~@{~d~@}x~@}" '((1 2) (3 4 5))) @print{} 12x345x
941 See also @nicode{~^} below for escaping from iteration.
943 @item @nicode{~[} @nicode{~;} @nicode{~]}
944 Conditional. Parameter: @var{selector}.
946 A conditional block is delimited by @nicode{~[} and @nicode{~]}, and
947 @nicode{~;} separates clauses within the block. @nicode{~[} takes an
948 integer argument and that number clause is used. The first clause is
952 (format #f "~[peach~;banana~;mango~]" 1) @result{} "banana"
955 The @var{selector} parameter can be used for the clause number,
956 instead of taking an argument.
959 (format #f "~2[peach~;banana~;mango~]") @result{} "mango"
962 If the clause number is out of range then nothing is output. Or the
963 last clause can be @nicode{~:;} to use that for a number out of range.
966 (format #f "~[banana~;mango~]" 99) @result{} ""
967 (format #f "~[banana~;mango~:;fruit~]" 99) @result{} "fruit"
970 @nicode{~:[} treats the argument as a flag, and expects two clauses.
971 The first is used if the argument is @code{#f} or the second
975 (format #f "~:[false~;not false~]" #f) @result{} "false"
976 (format #f "~:[false~;not false~]" 'abc) @result{} "not false"
979 (format #t "~d gnu~:[s are~; is~] here" n (= 1 n)))
980 @print{} 3 gnus are here
983 @nicode{~@@[} also treats the argument as a flag, and expects one
984 clause. If the argument is @code{#f} then no output is produced and
985 the argument is consumed, otherwise the clause is used and the
986 argument is not consumed, it's left for the clause. This can be used
987 for instance to suppress output if @code{#f} means something not
991 (format #f "~@@[temperature=~d~]" 27) @result{} "temperature=27"
992 (format #f "~@@[temperature=~d~]" #f) @result{} ""
996 Escape. Parameters: @var{val1}, @var{val2}, @var{val3}.
998 Stop formatting if there are no more arguments. This can be used for
999 instance to have a format string adapt to a variable number of
1003 (format #t "~d~^ ~d" 1) @print{} 1
1004 (format #t "~d~^ ~d" 1 2) @print{} 1 2
1007 Within a @nicode{~@{} @nicode{~@}} iteration, @nicode{~^} stops the
1008 current iteration step if there are no more arguments to that step,
1009 but continuing with possible further steps and the rest of the format.
1010 This can be used for instance to avoid a separator on the last
1011 iteration, or to adapt to variable length argument lists.
1014 (format #f "~@{~d~^/~@} go" '(1 2 3)) @result{} "1/2/3 go"
1015 (format #f "~:@{ ~d~^~d~@} go" '((1) (2 3))) @result{} " 1 23 go"
1018 @c For reference, format.scm doesn't implement that Common Lisp ~:^
1019 @c modifier which stops the entire iterating of ~:{ or ~@:{.
1021 @c FIXME: Believe the Common Lisp spec is for ~^ within ~[ ~]
1022 @c conditional to terminate the whole format (or iteration step if in
1023 @c an iteration). But format.scm seems to terminate just the
1024 @c conditional form.
1026 @c (format #f "~[abc~^def~;ghi~] blah" 0)
1027 @c @result{} "abc blah" ;; looks wrong
1029 @c FIXME: Believe the Common Lisp spec is for ~^ within ~( ~) to end
1030 @c that case conversion and then also terminate the whole format (or
1031 @c iteration step if in an iteration). But format.scm doesn't seem
1032 @c to do that quite right.
1034 @c (format #f "~d ~^ ~d" 1) @result{} "1 "
1035 @c (format #f "~(~d ~^ ~d~)" 1) @result{} ERROR
1037 Within a @nicode{~?} sub-format, @nicode{~^} operates just on that
1038 sub-format. If it terminates the sub-format then the originating
1039 format will still continue.
1042 (format #t "~? items" "~d~^ ~d" '(1)) @print{} 1 items
1043 (format #t "~? items" "~d~^ ~d" '(1 2)) @print{} 1 2 items
1046 The parameters to @nicode{~^} (which are numbers) change the condition
1047 used to terminate. For a single parameter, termination is when that
1048 value is zero (notice this makes plain @nicode{~^} equivalent to
1049 @nicode{~#^}). For two parameters, termination is when those two are
1050 equal. For three parameters, termination is when @math{@var{val1}
1051 @le{} @var{val2}} and @math{@var{val2} @le{} @var{val3}}.
1053 @c FIXME: Good examples of these?
1056 Inquiry message. Insert a copyright message into the output.
1058 @nicode{~:q} inserts the format implementation version.
1062 It's an error if there are not enough arguments for the escapes in the
1063 format string, but any excess arguments are ignored.
1065 Iterations @nicode{~@{} @nicode{~@}} and conditionals @nicode{~[}
1066 @nicode{~;} @nicode{~]} can be nested, but must be properly nested,
1067 meaning the inner form must be entirely within the outer form. So
1068 it's not possible, for instance, to try to conditionalize the endpoint
1072 (format #t "~@{ ~[ ... ~] ~@}" ...) ;; good
1073 (format #t "~@{ ~[ ... ~@} ... ~]" ...) ;; bad
1076 The same applies to case conversions @nicode{~(} @nicode{~)}, they
1077 must properly nest with respect to iterations and conditionals (though
1078 currently a case conversion cannot nest within another case
1081 When a sub-format (@nicode{~?}) is used, that sub-format string must
1082 be self-contained. It cannot for instance give a @nicode{~@{} to
1083 begin an iteration form and have the @nicode{~@}} up in the
1084 originating format, or similar.
1088 Guile contains a @code{format} procedure even when the module
1089 @code{(ice-9 format)} is not loaded. The default @code{format} is
1090 @code{simple-format} (@pxref{Writing}), it doesn't support all escape
1091 sequences documented in this section, and will signal an error if you
1092 try to use one of them. The reason for two versions is that the full
1093 @code{format} is fairly large and requires some time to load.
1094 @code{simple-format} is often adequate too.
1097 @node File Tree Walk
1098 @section File Tree Walk
1099 @cindex file tree walk
1101 The functions in this section traverse a tree of files and
1102 directories, in a fashion similar to the C @code{ftw} and @code{nftw}
1103 routines (@pxref{Working with Directory Trees,,, libc, GNU C Library
1107 (use-modules (ice-9 ftw))
1111 @defun ftw startname proc ['hash-size n]
1112 Walk the file system tree descending from @var{startname}, calling
1113 @var{proc} for each file and directory.
1115 Hard links and symbolic links are followed. A file or directory is
1116 reported to @var{proc} only once, and skipped if seen again in another
1117 place. One consequence of this is that @code{ftw} is safe against
1118 circularly linked directory structures.
1120 Each @var{proc} call is @code{(@var{proc} filename statinfo flag)} and
1121 it should return @code{#t} to continue, or any other value to stop.
1123 @var{filename} is the item visited, being @var{startname} plus a
1124 further path and the name of the item. @var{statinfo} is the return
1125 from @code{stat} (@pxref{File System}) on @var{filename}. @var{flag}
1126 is one of the following symbols,
1130 @var{filename} is a file, this includes special files like devices,
1134 @var{filename} is a directory.
1137 An error occurred when calling @code{stat}, so nothing is known.
1138 @var{statinfo} is @code{#f} in this case.
1140 @item directory-not-readable
1141 @var{filename} is a directory, but one which cannot be read and hence
1142 won't be recursed into.
1145 @var{filename} is a dangling symbolic link. Symbolic links are
1146 normally followed and their target reported, the link itself is
1147 reported if the target does not exist.
1150 The return value from @code{ftw} is @code{#t} if it ran to completion,
1151 or otherwise the non-@code{#t} value from @var{proc} which caused the
1154 Optional argument symbol @code{hash-size} and an integer can be given
1155 to set the size of the hash table used to track items already visited.
1156 (@pxref{Hash Table Reference})
1158 @c Actually, it's probably safe to escape from ftw, just need to
1161 In the current implementation, returning non-@code{#t} from @var{proc}
1162 is the only valid way to terminate @code{ftw}. @var{proc} must not
1163 use @code{throw} or similar to escape.
1167 @defun nftw startname proc ['chdir] ['depth] ['hash-size n] ['mount] ['physical]
1168 Walk the file system tree starting at @var{startname}, calling
1169 @var{proc} for each file and directory. @code{nftw} has extra
1170 features over the basic @code{ftw} described above.
1172 Like @code{ftw}, hard links and symbolic links are followed. A file
1173 or directory is reported to @var{proc} only once, and skipped if seen
1174 again in another place. One consequence of this is that @code{nftw}
1175 is safe against circular linked directory structures.
1177 Each @var{proc} call is @code{(@var{proc} filename statinfo flag
1178 base level)} and it should return @code{#t} to continue, or any
1179 other value to stop.
1181 @var{filename} is the item visited, being @var{startname} plus a
1182 further path and the name of the item. @var{statinfo} is the return
1183 from @code{stat} on @var{filename} (@pxref{File System}). @var{base}
1184 is an integer offset into @var{filename} which is where the basename
1185 for this item begins. @var{level} is an integer giving the directory
1186 nesting level, starting from 0 for the contents of @var{startname} (or
1187 that item itself if it's a file). @var{flag} is one of the following
1192 @var{filename} is a file, including special files like devices, named
1196 @var{filename} is a directory.
1198 @item directory-processed
1199 @var{filename} is a directory, and its contents have all been visited.
1200 This flag is given instead of @code{directory} when the @code{depth}
1201 option below is used.
1204 An error occurred when applying @code{stat} to @var{filename}, so
1205 nothing is known about it. @var{statinfo} is @code{#f} in this case.
1207 @item directory-not-readable
1208 @var{filename} is a directory, but one which cannot be read and hence
1209 won't be recursed into.
1212 @var{filename} is a dangling symbolic link. Links are normally
1213 followed and their target reported, the link itself is reported if its
1214 target does not exist.
1217 When the @code{physical} option described below is used, this
1218 indicates @var{filename} is a symbolic link whose target exists (and
1219 is not being followed).
1222 The following optional arguments can be given to modify the way
1223 @code{nftw} works. Each is passed as a symbol (and @code{hash-size}
1224 takes a following integer value).
1228 Change to the directory containing the item before calling @var{proc}.
1229 When @code{nftw} returns the original current directory is restored.
1231 Under this option, generally the @var{base} parameter to each
1232 @var{proc} call should be used to pick out the base part of the
1233 @var{filename}. The @var{filename} is still a path but with a changed
1234 directory it won't be valid (unless the @var{startname} directory was
1238 Visit files ``depth first'', meaning @var{proc} is called for the
1239 contents of each directory before it's called for the directory
1240 itself. Normally a directory is reported first, then its contents.
1242 Under this option, the @var{flag} to @var{proc} for a directory is
1243 @code{directory-processed} instead of @code{directory}.
1245 @item @code{hash-size @var{n}}
1246 Set the size of the hash table used to track items already visited.
1247 (@pxref{Hash Table Reference})
1250 Don't cross a mount point, meaning only visit items on the same
1251 file system as @var{startname} (ie.@: the same @code{stat:dev}).
1253 @item @code{physical}
1254 Don't follow symbolic links, instead report them to @var{proc} as
1255 @code{symlink}. Dangling links (those whose target doesn't exist) are
1256 still reported as @code{stale-symlink}.
1259 The return value from @code{nftw} is @code{#t} if it ran to
1260 completion, or otherwise the non-@code{#t} value from @var{proc} which
1263 @c For reference, one reason not to esacpe is that the current
1264 @c directory is not saved and restored with dynamic-wind. Maybe
1265 @c changing that would be enough to allow escaping.
1267 In the current implementation, returning non-@code{#t} from @var{proc}
1268 is the only valid way to terminate @code{ftw}. @var{proc} must not
1269 use @code{throw} or similar to escape.
1279 The functions in this section are provided by
1282 (use-modules (ice-9 q))
1285 This module implements queues holding arbitrary scheme objects and
1286 designed for efficient first-in / first-out operations.
1288 @code{make-q} creates a queue, and objects are entered and removed
1289 with @code{enq!} and @code{deq!}. @code{q-push!} and @code{q-pop!}
1290 can be used too, treating the front of the queue like a stack.
1294 @deffn {Scheme Procedure} make-q
1298 @deffn {Scheme Procedure} q? obj
1299 Return @code{#t} if @var{obj} is a queue, or @code{#f} if not.
1301 Note that queues are not a distinct class of objects but are
1302 implemented with cons cells. For that reason certain list structures
1303 can get @code{#t} from @code{q?}.
1306 @deffn {Scheme Procedure} enq! q obj
1307 Add @var{obj} to the rear of @var{q}, and return @var{q}.
1310 @deffn {Scheme Procedure} deq! q
1311 @deffnx {Scheme Procedure} q-pop! q
1312 Remove and return the front element from @var{q}. If @var{q} is
1313 empty, a @code{q-empty} exception is thrown.
1315 @code{deq!} and @code{q-pop!} are the same operation, the two names
1316 just let an application match @code{enq!} with @code{deq!}, or
1317 @code{q-push!} with @code{q-pop!}.
1320 @deffn {Scheme Procedure} q-push! q obj
1321 Add @var{obj} to the front of @var{q}, and return @var{q}.
1324 @deffn {Scheme Procedure} q-length q
1325 Return the number of elements in @var{q}.
1328 @deffn {Scheme Procedure} q-empty? q
1329 Return true if @var{q} is empty.
1332 @deffn {Scheme Procedure} q-empty-check q
1333 Throw a @code{q-empty} exception if @var{q} is empty.
1336 @deffn {Scheme Procedure} q-front q
1337 Return the first element of @var{q} (without removing it). If @var{q}
1338 is empty, a @code{q-empty} exception is thrown.
1341 @deffn {Scheme Procedure} q-rear q
1342 Return the last element of @var{q} (without removing it). If @var{q}
1343 is empty, a @code{q-empty} exception is thrown.
1346 @deffn {Scheme Procedure} q-remove! q obj
1347 Remove all occurrences of @var{obj} from @var{q}, and return @var{q}.
1348 @var{obj} is compared to queue elements using @code{eq?}.
1352 @cindex @code{q-empty}
1353 The @code{q-empty} exceptions described above are thrown just as
1354 @code{(throw 'q-empty)}, there's no message etc like an error throw.
1356 A queue is implemented as a cons cell, the @code{car} containing a
1357 list of queued elements, and the @code{cdr} being the last cell in
1358 that list (for ease of enqueuing).
1361 (@var{list} . @var{last-cell})
1365 If the queue is empty, @var{list} is the empty list and
1366 @var{last-cell} is @code{#f}.
1368 An application can directly access the queue list if desired, for
1369 instance to search the elements or to insert at a specific point.
1371 @deffn {Scheme Procedure} sync-q! q
1372 Recompute the @var{last-cell} field in @var{q}.
1374 All the operations above maintain @var{last-cell} as described, so
1375 normally there's no need for @code{sync-q!}. But if an application
1376 modifies the queue @var{list} then it must either maintain
1377 @var{last-cell} similarly, or call @code{sync-q!} to recompute it.
1385 A stream represents a sequence of values, each of which is calculated
1386 only when required. This allows large or even infinite sequences to
1387 be represented and manipulated with familiar operations like ``car'',
1388 ``cdr'', ``map'' or ``fold''. In such manipulations only as much as
1389 needed is actually held in memory at any one time. The functions in
1390 this section are available from
1393 (use-modules (ice-9 streams))
1396 Streams are implemented using promises (@pxref{Delayed Evaluation}),
1397 which is how the underlying calculation of values is made only when
1398 needed, and the values then retained so the calculation is not
1402 Here is a simple example producing a stream of all odd numbers,
1405 (define odds (make-stream (lambda (state)
1406 (cons state (+ state 2)))
1408 (stream-car odds) @result{} 1
1409 (stream-car (stream-cdr odds)) @result{} 3
1413 @code{stream-map} could be used to derive a stream of odd squares,
1416 (define (square n) (* n n))
1417 (define oddsquares (stream-map square odds))
1420 These are infinite sequences, so it's not possible to convert them to
1421 a list, but they could be printed (infinitely) with for example
1424 (stream-for-each (lambda (n sq)
1425 (format #t "~a squared is ~a\n" n sq))
1436 @defun make-stream proc initial-state
1437 Return a new stream, formed by calling @var{proc} successively.
1439 Each call is @code{(@var{proc} @var{state})}, it should return a pair,
1440 the @code{car} being the value for the stream, and the @code{cdr}
1441 being the new @var{state} for the next call. For the first call
1442 @var{state} is the given @var{initial-state}. At the end of the
1443 stream, @var{proc} should return some non-pair object.
1446 @defun stream-car stream
1447 Return the first element from @var{stream}. @var{stream} must not be
1451 @defun stream-cdr stream
1452 Return a stream which is the second and subsequent elements of
1453 @var{stream}. @var{stream} must not be empty.
1456 @defun stream-null? stream
1457 Return true if @var{stream} is empty.
1460 @defun list->stream list
1461 @defunx vector->stream vector
1462 Return a stream with the contents of @var{list} or @var{vector}.
1464 @var{list} or @var{vector} should not be modified subsequently, since
1465 it's unspecified whether changes there will be reflected in the stream
1469 @defun port->stream port readproc
1470 Return a stream which is the values obtained by reading from
1471 @var{port} using @var{readproc}. Each read call is
1472 @code{(@var{readproc} @var{port})}, and it should return an EOF object
1473 (@pxref{Reading}) at the end of input.
1475 For example a stream of characters from a file,
1478 (port->stream (open-input-file "/foo/bar.txt") read-char)
1482 @defun stream->list stream
1483 Return a list which is the entire contents of @var{stream}.
1486 @defun stream->reversed-list stream
1487 Return a list which is the entire contents of @var{stream}, but in
1491 @defun stream->list&length stream
1492 Return two values (@pxref{Multiple Values}), being firstly a list
1493 which is the entire contents of @var{stream}, and secondly the number
1494 of elements in that list.
1497 @defun stream->reversed-list&length stream
1498 Return two values (@pxref{Multiple Values}) being firstly a list which
1499 is the entire contents of @var{stream}, but in reverse order, and
1500 secondly the number of elements in that list.
1503 @defun stream->vector stream
1504 Return a vector which is the entire contents of @var{stream}.
1507 @defun stream-fold proc init stream0 @dots{} streamN
1508 Apply @var{proc} successively over the elements of the given streams,
1509 from first to last until the end of the shortest stream is reached.
1510 Return the result from the last @var{proc} call.
1512 Each call is @code{(@var{proc} elem0 @dots{} elemN prev)}, where each
1513 @var{elem} is from the corresponding @var{stream}. @var{prev} is the
1514 return from the previous @var{proc} call, or the given @var{init} for
1518 @defun stream-for-each proc stream0 @dots{} streamN
1519 Call @var{proc} on the elements from the given @var{stream}s. The
1520 return value is unspecified.
1522 Each call is @code{(@var{proc} elem0 @dots{} elemN)}, where each
1523 @var{elem} is from the corresponding @var{stream}.
1524 @code{stream-for-each} stops when it reaches the end of the shortest
1528 @defun stream-map proc stream0 @dots{} streamN
1529 Return a new stream which is the results of applying @var{proc} to the
1530 elements of the given @var{stream}s.
1532 Each call is @code{(@var{proc} elem0 @dots{} elemN)}, where each
1533 @var{elem} is from the corresponding @var{stream}. The new stream
1534 ends when the end of the shortest given @var{stream} is reached.
1538 @node Buffered Input
1539 @section Buffered Input
1540 @cindex Buffered input
1541 @cindex Line continuation
1543 The following functions are provided by
1546 (use-modules (ice-9 buffered-input))
1549 A buffered input port allows a reader function to return chunks of
1550 characters which are to be handed out on reading the port. A notion
1551 of further input for an application level logical expression is
1552 maintained too, and passed through to the reader.
1554 @defun make-buffered-input-port reader
1555 Create an input port which returns characters obtained from the given
1556 @var{reader} function. @var{reader} is called (@var{reader} cont),
1557 and should return a string or an EOF object.
1559 The new port gives precisely the characters returned by @var{reader},
1560 nothing is added, so if any newline characters or other separators are
1561 desired they must come from the reader function.
1563 The @var{cont} parameter to @var{reader} is @code{#f} for initial
1564 input, or @code{#t} when continuing an expression. This is an
1565 application level notion, set with
1566 @code{set-buffered-input-continuation?!} below. If the user has
1567 entered a partial expression then it allows @var{reader} for instance
1568 to give a different prompt to show more is required.
1571 @defun make-line-buffered-input-port reader
1572 @cindex Line buffered input
1573 Create an input port which returns characters obtained from the
1574 specified @var{reader} function, similar to
1575 @code{make-buffered-input-port} above, but where @var{reader} is
1576 expected to be a line-oriented.
1578 @var{reader} is called (@var{reader} cont), and should return a string
1579 or an EOF object as above. Each string is a line of input without a
1580 newline character, the port code inserts a newline after each string.
1583 @defun set-buffered-input-continuation?! port cont
1584 Set the input continuation flag for a given buffered input
1587 An application uses this by calling with a @var{cont} flag of
1588 @code{#f} when beginning to read a new logical expression. For
1589 example with the Scheme @code{read} function (@pxref{Scheme Read}),
1592 (define my-port (make-buffered-input-port my-reader))
1594 (set-buffered-input-continuation?! my-port #f)
1595 (let ((obj (read my-port)))
1602 @c TeX-master: "guile.texi"