-@page
-@node Pretty Printing
-@chapter Pretty Printing
-
-@c FIXME::martin: Review me!
-
-@cindex pretty printing
-The module @code{(ice-9 pretty-print)} provides the procedure
-@code{pretty-print}, which provides nicely formatted output of Scheme
-objects. This is especially useful for deeply nested or complex data
-structures, such as lists and vectors.
-
-The module is loaded by simply saying.
-
-@lisp
-(use-modules (ice-9 pretty-print))
-@end lisp
-
-This makes the procedure @code{pretty-print} available. As an example
-how @code{pretty-print} will format the output, see the following:
-
-@lisp
-(pretty-print '(define (foo) (lambda (x)
-(cond ((zero? x) #t) ((negative? x) -x) (else (if (= x 1) 2 (* x x x)))))))
-@print{}
-(define (foo)
- (lambda (x)
- (cond ((zero? x) #t)
- ((negative? x) -x)
- (else (if (= x 1) 2 (* x x x))))))
-@end lisp
-
-@deffn {Scheme Procedure} pretty-print obj [port]
-Print the textual representation of the Scheme object @var{obj} to
-@var{port}. @var{port} defaults to the current output port, if not
-given.
-@end deffn
-
-Beware: Since @code{pretty-print} uses it's own write procedure, it's
-output will not be the same as for example the output of @code{write}.
-Consider the following example.
-
-@lisp
-(write (lambda (x) x))
-@print{}
-#<procedure #f (x)>
-
-(pretty-print (lambda (x) x))
-@print{}
-#[procedure]
-@end lisp
-
-The reason is that @code{pretty-print} does not know as much about
-Guile's object types as the builtin procedures. This is particularly
-important for smobs, for which a write procedure can be defined and be
-used by @code{write}, but not by @code{pretty-print}.
-
-
-@page
-@node Formatted Output
-@chapter Formatted Output
-
-@c FIXME::martin: Review me!
-
-@cindex format
-@cindex formatted output
-Outputting messages or other texts which are composed of literal
-strings, variable contents, newlines and other formatting can be
-cumbersome, when only the standard procedures like @code{display},
-@code{write} and @code{newline} are available. Additionally, one
-often wants to collect the output in strings. With the standard
-routines, the user is required to set up a string port, add this port
-as a parameter to the output procedure calls and then retrieve the
-resulting string from the string port.
-
-The @code{format} procedure, to be found in module @code{(ice-9
-format)}, can do all this, and even more. If you are a C programmer,
-you can think of this procedure as Guile's @code{fprintf}.
-
-@deffn {Scheme Procedure} format destination format-string args @dots{}
-The first parameter is the @var{destination}, it determines where the
-output of @code{format} will go.
-
-@table @asis
-@item @code{#t}
-Send the formatted output to the current output port and return
-@code{#t}.
-
-@item @code{#f}
-Return the formatted output as a string.
-
-@item Any number value
-Send the formatted output to the current error port and return
-@code{#t}.
-
-@item A valid output port
-Send the formatted output to the port @var{destination} and return
-@code{#t}.
-@end table
-
-The second parameter is the format string. It has a similar function
-to the format string in calls to @code{printf} or @code{fprintf} in C.
-It is output to the specified destination, but all escape sequences
-are replaced by the results of formatting the corresponding sequence.
-
-Note that escape sequences are marked with the character @code{~}
-(tilde), and not with a @code{%} (percent sign), as in C.
-
-The escape sequences in the following table are supported. When there
-appears ``corresponding @var{arg}', that means any of the additional
-arguments, after dropping all arguments which have been used up by
-escape sequences which have been processed earlier. Some of the
-format characters (the characters following the tilde) can be prefixed
-by @code{:}, @code{@@}, or @code{:@@}, to modify the behaviour of the
-format character. How the modified behaviour differs from the default
-behaviour is described for every character in the table where
-appropriate.
-
-@table @code
-@item ~~
-Output a single @code{~} (tilde) character.
-
-@item ~%
-Output a newline character, thus advancing to the next output line.
-
-@item ~&
-Start a new line, that is, output a newline character if not already
-at the start of a line.
-
-@item ~_
-Output a single space character.
-
-@item ~/
-Output a single tabulator character.
-
-@item ~|
-Output a page separator (formfeed) character.
-
-@item ~t
-Advance to the next tabulator position.
-
-@item ~y
-Pretty-print the corresponding @var{arg}.
-
-@item ~a
-Output the corresponding @var{arg} like @code{display}.
-
-@item ~s
-Output the corresponding @var{arg} like @code{write}.
-
-@item ~d
-Output the corresponding @var{arg} as a decimal number.
-
-@item ~x
-Output the corresponding @var{arg} as a hexadecimal number.
-
-@item ~o
-Output the corresponding @var{arg} as an octal number.
-
-@item ~b
-Output the corresponding @var{arg} as a binary number.
-
-@item ~r
-Output the corresponding @var{arg} as a number word, e.g. 10 prints as
-@code{ten}. If prefixed with @code{:}, @code{tenth} is printed, if
-prefixed with @code{:@@}, Roman numbers are printed.
-
-@item ~f
-Output the corresponding @var{arg} as a fixed format floating point
-number, such as @code{1.34}.
-
-@item ~e
-Output the corresponding @var{arg} in exponential notation, such as
-@code{1.34E+0}.
-
-@item ~g
-This works either like @code{~f} or like @code{~e}, whichever produces
-less characters to be written.
-
-@item ~$
-Like @code{~f}, but only with two digits after the decimal point.
-
-@item ~i
-Output the corresponding @var{arg} as a complex number.
-
-@item ~c
-Output the corresponding @var{arg} as a character. If prefixed with
-@code{@@}, it is printed like with @code{write}. If prefixed with
-@code{:}, control characters are treated specially, for example
-@code{#\newline} will be printed as @code{^J}.
-
-@item ~p
-``Plural''. If the corresponding @var{arg} is 1, nothing is printed
-(or @code{y} if prefixed with @code{@@} or @code{:@@}), otherwise
-@code{s} is printed (or @code{ies} if prefixed with @code{@@} or
-@code{:@@}).
-
-@item ~?, ~k
-Take the corresponding argument as a format string, and the following
-argument as a list of values. Then format the values with respect to
-the format string.
-
-@item ~!
-Flush the output to the output port.
-
-@item ~#\newline (tilde-newline)
-@c FIXME::martin: I don't understand this from the source.
-Continuation lines.
-
-@item ~*
-Argument jumping. Navigate in the argument list as specified by the
-corresponding argument. If prefixed with @code{:}, jump backwards in
-the argument list, if prefixed by @code{:@@}, jump to the parameter
-with the absolute index, otherwise jump forward in the argument list.
-
-@item ~(
-Case conversion begin. If prefixed by @code{:}, the following output
-string will be capitalized, if prefixed by @code{@@}, the first
-character will be capitalized, if prefixed by @code{:@@} it will be
-upcased and otherwise it will be downcased. Conversion stops when the
-``Case conversion end'' @code{~)}sequence is encountered.
-
-@item ~)
-Case conversion end. Stop any case conversion currently in effect.
-
-@item ~[
-@c FIXME::martin: I don't understand this from the source.
-Conditional begin.
-
-@item ~;
-@c FIXME::martin: I don't understand this from the source.
-Conditional separator.
-
-@item ~]
-@c FIXME::martin: I don't understand this from the source.
-Conditional end.
-
-@item ~@{
-@c FIXME::martin: I don't understand this from the source.
-Iteration begin.
-
-@item ~@}
-@c FIXME::martin: I don't understand this from the source.
-Iteration end.
-
-@item ~^
-@c FIXME::martin: I don't understand this from the source.
-Up and out.
-
-@item ~'
-@c FIXME::martin: I don't understand this from the source.
-Character parameter.
-
-@item ~0 @dots{} ~9, ~-, ~+
-@c FIXME::martin: I don't understand this from the source.
-Numeric parameter.
-
-@item ~v
-@c FIXME::martin: I don't understand this from the source.
-Variable parameter from next argument.
-
-@item ~#
-Parameter is number of remaining args. The number of the remaining
-arguments is prepended to the list of unprocessed arguments.
-
-@item ~,
-@c FIXME::martin: I don't understand this from the source.
-Parameter separators.
-
-@item ~q
-Inquiry message. Insert a copyright message into the output.
-@end table
-
-If any type conversions should fail (for example when using an escape
-sequence for number output, but the argument is a string), an error
-will be signalled.
-@end deffn
-
-You may have noticed that Guile contains a @code{format} procedure
-even when the module @code{(ice-9 format)} is not loaded. The default
-@code{format} procedure does not support all escape sequences
-documented in this chapter, and will signal an error if you try to use
-one of them. The reason for providing two versions of @code{format}
-is that the full-featured module is fairly large and requires some
-time to get loaded. So the Guile maintainers decided not to load the
-large version of @code{format} by default, so that the start-up time
-of the interpreter is not unnecessarily increased.
-
-
-@page
-@node Rx Regexps
-@chapter The Rx Regular Expression Library
-
-[FIXME: this is taken from Gary and Mark's quick summaries and should be
-reviewed and expanded. Rx is pretty stable, so could already be done!]
-
-@cindex rx
-@cindex finite automaton
-
-The @file{guile-lang-allover} package provides an interface to Tom
-Lord's Rx library (currently only to POSIX regular expressions). Use of
-the library requires a two step process: compile a regular expression
-into an efficient structure, then use the structure in any number of
-string comparisons.
-
-For example, given the regular expression @samp{abc.} (which matches any
-string containing @samp{abc} followed by any single character):
-
-@smalllisp
-guile> @kbd{(define r (regcomp "abc."))}
-guile> @kbd{r}
-#<rgx abc.>
-guile> @kbd{(regexec r "abc")}
-#f
-guile> @kbd{(regexec r "abcd")}
-#((0 . 4))
-guile>
-@end smalllisp
-
-The definitions of @code{regcomp} and @code{regexec} are as follows:
-
-@deffn {Scheme Procedure} regcomp pattern [flags]
-Compile the regular expression pattern using POSIX rules. Flags is
-optional and should be specified using symbolic names:
-@defvar REG_EXTENDED
-use extended POSIX syntax
-@end defvar
-@defvar REG_ICASE
-use case-insensitive matching
-@end defvar
-@defvar REG_NEWLINE
-allow anchors to match after newline characters in the
-string and prevents @code{.} or @code{[^...]} from matching newlines.
-@end defvar
-
-The @code{logior} procedure can be used to combine multiple flags.
-The default is to use
-POSIX basic syntax, which makes @code{+} and @code{?} literals and @code{\+}
-and @code{\?}
-operators. Backslashes in @var{pattern} must be escaped if specified in a
-literal string e.g., @code{"\\(a\\)\\?"}.
-@end deffn
-
-@deffn {Scheme Procedure} regexec regex string [match-pick] [flags]
-Match @var{string} against the compiled POSIX regular expression
-@var{regex}.
-@var{match-pick} and @var{flags} are optional. Possible flags (which can be
-combined using the logior procedure) are:
-
-@defvar REG_NOTBOL
-The beginning of line operator won't match the beginning of
-@var{string} (presumably because it's not the beginning of a line)
-@end defvar
-
-@defvar REG_NOTEOL
-Similar to REG_NOTBOL, but prevents the end of line operator
-from matching the end of @var{string}.
-@end defvar
-
-If no match is possible, regexec returns #f. Otherwise @var{match-pick}
-determines the return value:
-
-@code{#t} or unspecified: a newly-allocated vector is returned,
-containing pairs with the indices of the matched part of @var{string} and any
-substrings.
-
-@code{""}: a list is returned: the first element contains a nested list
-with the matched part of @var{string} surrounded by the the unmatched parts.
-Remaining elements are matched substrings (if any). All returned
-substrings share memory with @var{string}.
-
-@code{#f}: regexec returns #t if a match is made, otherwise #f.
-
-vector: the supplied vector is returned, with the first element replaced
-by a pair containing the indices of the matched portion of @var{string} and
-further elements replaced by pairs containing the indices of matched
-substrings (if any).
-
-list: a list will be returned, with each member of the list
-specified by a code in the corresponding position of the supplied list:
-
-a number: the numbered matching substring (0 for the entire match).
-
-@code{#\<}: the beginning of @var{string} to the beginning of the part matched
-by regex.
-
-@code{#\>}: the end of the matched part of @var{string} to the end of
-@var{string}.
-
-@code{#\c}: the "final tag", which seems to be associated with the "cut
-operator", which doesn't seem to be available through the posix
-interface.
-
-e.g., @code{(list #\< 0 1 #\>)}. The returned substrings share memory with
-@var{string}.
-@end deffn
-
-Here are some other procedures that might be used when using regular
-expressions:
-
-@deffn {Scheme Procedure} compiled-regexp? obj
-Test whether obj is a compiled regular expression.
-@end deffn
-
-@deffn {Scheme Procedure} regexp->dfa regex [flags]
-@end deffn
-
-@deffn {Scheme Procedure} dfa-fork dfa
-@end deffn
-
-@deffn {Scheme Procedure} reset-dfa! dfa
-@end deffn
-
-@deffn {Scheme Procedure} dfa-final-tag dfa
-@end deffn
-
-@deffn {Scheme Procedure} dfa-continuable? dfa
-@end deffn
-
-@deffn {Scheme Procedure} advance-dfa! dfa string
-@end deffn
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
+@c -*-texinfo-*-
+@c This is part of the GNU Guile Reference Manual.
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2009, 2010
+@c Free Software Foundation, Inc.
+@c See the file guile.texi for copying conditions.
+
+@node Pretty Printing
+@section Pretty Printing
+
+@c FIXME::martin: Review me!
+
+@cindex pretty printing
+The module @code{(ice-9 pretty-print)} provides the procedure
+@code{pretty-print}, which provides nicely formatted output of Scheme
+objects. This is especially useful for deeply nested or complex data
+structures, such as lists and vectors.
+
+The module is loaded by entering the following:
+
+@lisp
+(use-modules (ice-9 pretty-print))
+@end lisp
+
+This makes the procedure @code{pretty-print} available. As an example
+how @code{pretty-print} will format the output, see the following:
+
+@lisp
+(pretty-print '(define (foo) (lambda (x)
+(cond ((zero? x) #t) ((negative? x) -x) (else
+(if (= x 1) 2 (* x x x)))))))
+@print{}
+(define (foo)
+ (lambda (x)
+ (cond ((zero? x) #t)
+ ((negative? x) -x)
+ (else (if (= x 1) 2 (* x x x))))))
+@end lisp
+
+@deffn {Scheme Procedure} pretty-print obj [port] [keyword-options]
+Print the textual representation of the Scheme object @var{obj} to
+@var{port}. @var{port} defaults to the current output port, if not
+given.
+
+The further @var{keyword-options} are keywords and parameters as
+follows,
+
+@table @asis
+@item @nicode{#:display?} @var{flag}
+If @var{flag} is true then print using @code{display}. The default is
+@code{#f} which means use @code{write} style. (@pxref{Writing})
+
+@item @nicode{#:per-line-prefix} @var{string}
+Print the given @var{string} as a prefix on each line. The default is
+no prefix.
+
+@item @nicode{#:width} @var{columns}
+Print within the given @var{columns}. The default is 79.
+@end table
+@end deffn
+
+
+@cindex truncated printing
+Also exported by the @code{(ice-9 pretty-print)} module is
+@code{truncated-print}, a procedure to print Scheme datums, truncating
+the output to a certain number of characters. This is useful when you
+need to present an arbitrary datum to the user, but you only have one
+line in which to do so.
+
+@lisp
+(define exp '(a b #(c d e) f . g))
+(truncated-print exp #:width 10) (newline)
+@print{} (a b . #)
+(truncated-print exp #:width 15) (newline)
+@print{} (a b # f . g)
+(truncated-print exp #:width 18) (newline)
+@print{} (a b #(c ...) . #)
+(truncated-print exp #:width 20) (newline)
+@print{} (a b #(c d e) f . g)
+(truncated-print "The quick brown fox" #:width 20) (newline)
+@print{} "The quick brown..."
+(truncated-print (current-module) #:width 20) (newline)
+@print{} #<directory (gui...>
+@end lisp
+
+@code{truncated-print} will not output a trailing newline. If an expression does
+not fit in the given width, it will be truncated -- possibly
+ellipsized@footnote{On Unicode-capable ports, the ellipsis is represented by
+character `HORIZONTAL ELLIPSIS' (U+2026), otherwise it is represented by three
+dots.}, or in the worst case, displayed as @nicode{#}.
+
+@deffn {Scheme Procedure} truncated-print obj [port] [keyword-options]
+Print @var{obj}, truncating the output, if necessary, to make it fit
+into @var{width} characters. By default, @var{x} will be printed using
+@code{write}, though that behavior can be overriden via the
+@var{display?} keyword argument.
+
+The default behaviour is to print depth-first, meaning that the entire
+remaining width will be available to each sub-expressoin of @var{x} --
+e.g., if @var{x} is a vector, each member of @var{x}. One can attempt to
+``ration'' the available width, trying to allocate it equally to each
+sub-expression, via the @var{breadth-first?} keyword argument.
+
+The further @var{keyword-options} are keywords and parameters as
+follows,
+
+@table @asis
+@item @nicode{#:display?} @var{flag}
+If @var{flag} is true then print using @code{display}. The default is
+@code{#f} which means use @code{write} style. (@pxref{Writing})
+
+@item @nicode{#:width} @var{columns}
+Print within the given @var{columns}. The default is 79.
+
+@item @nicode{#:breadth-first?} @var{flag}
+If @var{flag} is true, then allocate the available width breadth-first
+among elements of a compound data structure (list, vector, pair,
+etc.). The default is @code{#f} which means that any element is
+allowed to consume all of the available width.
+@end table
+@end deffn
+
+
+@node Formatted Output
+@section Formatted Output
+@cindex formatted output
+
+@c For reference, in this section escapes like ~a are given in
+@c @nicode, to give code font in TeX etc, but leave them unadorned in
+@c Info.
+@c
+@c The idea is to reduce clutter around what's shown, and avoid any
+@c possible confusion over whether the ` ' quotes are part of what
+@c should be entered. (In particular for instance of course ' is
+@c meaningful in a format string, introducing a char parameter).
+
+The @code{format} function is a powerful way to print numbers, strings
+and other objects together with literal text under the control of a
+format string. This function is available from
+
+@example
+(use-modules (ice-9 format))
+@end example
+
+A format string is generally more compact and easier than using just
+the standard procedures like @code{display}, @code{write} and
+@code{newline}. Parameters in the output string allow various output
+styles, and parameters can be taken from the arguments for runtime
+flexibility.
+
+@code{format} is similar to the Common Lisp procedure of the same
+name, but it's not identical and doesn't have quite all the features
+found in Common Lisp.
+
+C programmers will note the similarity between @code{format} and
+@code{printf}, though escape sequences are marked with @nicode{~}
+instead of @nicode{%}, and are more powerful.
+
+@sp 1
+@deffn {Scheme Procedure} format dest fmt [args@dots{}]
+Write output specified by the @var{fmt} string to @var{dest}.
+@var{dest} can be an output port, @code{#t} for
+@code{current-output-port} (@pxref{Default Ports}), a number for
+@code{current-error-port}, or @code{#f} to return the output as a
+string.
+
+@var{fmt} can contain literal text to be output, and @nicode{~}
+escapes. Each escape has the form
+
+@example
+~ [param [, param@dots{}] [:] [@@] code
+@end example
+
+@nicode{code} is a character determining the escape sequence. The
+@nicode{:} and @nicode{@@} characters are optional modifiers, one or
+both of which change the way various codes operate. Optional
+parameters are accepted by some codes too. Parameters have the
+following forms,
+
+@table @asis
+@item @nicode{[+/-]number}
+An integer, with optional @nicode{+} or @nicode{-}.
+@item @nicode{'} (apostrophe)
+The following character in the format string, for instance @nicode{'z}
+for @nicode{z}.
+@item @nicode{v}
+The next function argument as the parameter. @nicode{v} stands for
+``variable'', a parameter can be calculated at runtime and included in
+the arguments. Upper case @nicode{V} can be used too.
+@item @nicode{#}
+The number of arguments remaining. (See @nicode{~*} below for some
+usages.)
+@end table
+
+Parameters are separated by commas (@nicode{,}). A parameter can be
+left empty to keep its default value when supplying later parameters.
+
+@sp 1
+The following escapes are available. The code letters are not
+case-sensitive, upper and lower case are the same.
+
+@table @asis
+@item @nicode{~a}
+@itemx @nicode{~s}
+Object output. Parameters: @var{minwidth}, @var{padinc},
+@var{minpad}, @var{padchar}.
+
+@nicode{~a} outputs an argument like @code{display}, @nicode{~s}
+outputs an argument like @code{write} (@pxref{Writing}).
+
+@example
+(format #t "~a" "foo") @print{} foo
+(format #t "~s" "foo") @print{} "foo"
+@end example
+
+@nicode{~:a} and @nicode{~:s} put objects that don't have an external
+representation in quotes like a string.
+
+@example
+(format #t "~:a" car) @print{} "#<primitive-procedure car>"
+@end example
+
+If the output is less than @var{minwidth} characters (default 0), it's
+padded on the right with @var{padchar} (default space). @nicode{~@@a}
+and @nicode{~@@s} put the padding on the left instead.
+
+@example
+(format #f "~5a" 'abc) @result{} "abc "
+(format #f "~5,,,'-@@a" 'abc) @result{} "--abc"
+@end example
+
+@var{minpad} is a minimum for the padding then plus a multiple of
+@var{padinc}. Ie.@: the padding is @math{@var{minpad} + @var{N} *
+@var{padinc}}, where @var{n} is the smallest integer making the total
+object plus padding greater than or equal to @var{minwidth}. The
+default @var{minpad} is 0 and the default @var{padinc} is 1 (imposing
+no minimum or multiple).
+
+@example
+(format #f "~5,1,4a" 'abc) @result{} "abc "
+@end example
+
+@item @nicode{~c}
+Character. Parameter: @var{charnum}.
+
+Output a character. The default is to simply output, as per
+@code{write-char} (@pxref{Writing}). @nicode{~@@c} prints in
+@code{write} style. @nicode{~:c} prints control characters (ASCII 0
+to 31) in @nicode{^X} form.
+
+@example
+(format #t "~c" #\z) @print{} z
+(format #t "~@@c" #\z) @print{} #\z
+(format #t "~:c" #\newline) @print{} ^J
+@end example
+
+If the @var{charnum} parameter is given then an argument is not taken
+but instead the character is @code{(integer->char @var{charnum})}
+(@pxref{Characters}). This can be used for instance to output
+characters given by their ASCII code.
+
+@example
+(format #t "~65c") @print{} A
+@end example
+
+@item @nicode{~d}
+@itemx @nicode{~x}
+@itemx @nicode{~o}
+@itemx @nicode{~b}
+Integer. Parameters: @var{minwidth}, @var{padchar}, @var{commachar},
+@var{commawidth}.
+
+Output an integer argument as a decimal, hexadecimal, octal or binary
+integer (respectively).
+
+@example
+(format #t "~d" 123) @print{} 123
+@end example
+
+@nicode{~@@d} etc shows a @nicode{+} sign is shown on positive
+numbers.
+
+@c FIXME: "+" is not shown on zero, unlike in Common Lisp. Should
+@c that be changed in the code, or is it too late and should just be
+@c documented that way?
+
+@example
+(format #t "~@@b" 12) @print{} +1100
+@end example
+
+If the output is less than the @var{minwidth} parameter (default no
+minimum), it's padded on the left with the @var{padchar} parameter
+(default space).
+
+@example
+(format #t "~5,'*d" 12) @print{} ***12
+(format #t "~5,'0d" 12) @print{} 00012
+(format #t "~3d" 1234) @print{} 1234
+@end example
+
+@nicode{~:d} adds commas (or the @var{commachar} parameter) every
+three digits (or the @var{commawidth} parameter many).
+
+@example
+(format #t "~:d" 1234567) @print{} 1,234,567
+(format #t "~10,'*,'/,2:d" 12345) @print{} ***1/23/45
+@end example
+
+Hexadecimal @nicode{~x} output is in lower case, but the @nicode{~(}
+and @nicode{~)} case conversion directives described below can be used
+to get upper case.
+
+@example
+(format #t "~x" 65261) @print{} feed
+(format #t "~:@@(~x~)" 65261) @print{} FEED
+@end example
+
+@item @nicode{~r}
+Integer in words, roman numerals, or a specified radix. Parameters:
+@var{radix}, @var{minwidth}, @var{padchar}, @var{commachar},
+@var{commawidth}.
+
+With no parameters output is in words as a cardinal like ``ten'', or
+@nicode{~:r} prints an ordinal like ``tenth''.
+
+@example
+(format #t "~r" 9) @print{} nine ;; cardinal
+(format #t "~r" -9) @print{} minus nine ;; cardinal
+(format #t "~:r" 9) @print{} ninth ;; ordinal
+@end example
+
+And also with no parameters, @nicode{~@@r} gives roman numerals and
+@nicode{~:@@r} gives old roman numerals. In old roman numerals
+there's no ``subtraction'', so 9 is @nicode{VIIII} instead of
+@nicode{IX}. In both cases only positive numbers can be output.
+
+@example
+(format #t "~@@r" 89) @print{} LXXXIX ;; roman
+(format #t "~:@@r" 89) @print{} LXXXVIIII ;; old roman
+@end example
+
+When a parameter is given it means numeric output in the specified
+@var{radix}. The modifiers and parameters following the radix are the
+same as described for @nicode{~d} etc above.
+
+@example
+(format #f "~3r" 27) @result{} "1000" ;; base 3
+(format #f "~3,5r" 26) @result{} " 222" ;; base 3 width 5
+@end example
+
+@item @nicode{~f}
+Fixed-point float. Parameters: @var{width}, @var{decimals},
+@var{scale}, @var{overflowchar}, @var{padchar}.
+
+Output a number or number string in fixed-point format, ie.@: with a
+decimal point.
+
+@example
+(format #t "~f" 5) @print{} 5.0
+(format #t "~f" "123") @print{} 123.0
+(format #t "~f" "1e-1") @print{} 0.1
+@end example
+
+@nicode{~@@f} prints a @nicode{+} sign on positive numbers (including
+zero).
+
+@example
+(format #t "~@@f" 0) @print{} +0.0
+@end example
+
+If the output is less than @var{width} characters it's padded on the
+left with @var{padchar} (space by default). If the output equals or
+exceeds @var{width} then there's no padding. The default for
+@var{width} is no padding.
+
+@example
+(format #f "~6f" -1.5) @result{} " -1.5"
+(format #f "~6,,,,'*f" 23) @result{} "**23.0"
+(format #f "~6f" 1234567.0) @result{} "1234567.0"
+@end example
+
+@var{decimals} is how many digits to print after the decimal point,
+with the value rounded or padded with zeros as necessary. (The
+default is to output as many decimals as required.)
+
+@example
+(format #t "~1,2f" 3.125) @print{} 3.13
+(format #t "~1,2f" 1.5) @print{} 1.50
+@end example
+
+@var{scale} is a power of 10 applied to the value, moving the decimal
+point that many places. A positive @var{scale} increases the value
+shown, a negative decreases it.
+
+@example
+(format #t "~,,2f" 1234) @print{} 123400.0
+(format #t "~,,-2f" 1234) @print{} 12.34
+@end example
+
+If @var{overflowchar} and @var{width} are both given and if the output
+would exceed @var{width}, then that many @var{overflowchar}s are
+printed instead of the value.
+
+@example
+(format #t "~5,,,'xf" 12345) @print{} 12345
+(format #t "~4,,,'xf" 12345) @print{} xxxx
+@end example
+
+@item @nicode{~e}
+Exponential float. Parameters: @var{width}, @var{mantdigits},
+@var{expdigits}, @var{intdigits}, @var{overflowchar}, @var{padchar},
+@var{expchar}.
+
+Output a number or number string in exponential notation.
+
+@example
+(format #t "~e" 5000.25) @print{} 5.00025E+3
+(format #t "~e" "123.4") @print{} 1.234E+2
+(format #t "~e" "1e4") @print{} 1.0E+4
+@end example
+
+@nicode{~@@e} prints a @nicode{+} sign on positive numbers (including
+zero). (This is for the mantissa, a @nicode{+} or @nicode{-} sign is
+always shown on the exponent.)
+
+@example
+(format #t "~@@e" 5000.0) @print{} +5.0E+3
+@end example
+
+If the output is less than @var{width} characters it's padded on the
+left with @var{padchar} (space by default). The default for
+@var{width} is to output with no padding.
+
+@example
+(format #f "~10e" 1234.0) @result{} " 1.234E+3"
+(format #f "~10,,,,,'*e" 0.5) @result{} "****5.0E-1"
+@end example
+
+@c FIXME: Describe what happens when the number is bigger than WIDTH.
+@c There seems to be a bit of dodginess about this, or some deviation
+@c from Common Lisp.
+
+@var{mantdigits} is the number of digits shown in the mantissa after
+the decimal point. The value is rounded or trailing zeros are added
+as necessary. The default @var{mantdigits} is to show as much as
+needed by the value.
+
+@example
+(format #f "~,3e" 11111.0) @result{} "1.111E+4"
+(format #f "~,8e" 123.0) @result{} "1.23000000E+2"
+@end example
+
+@var{expdigits} is the minimum number of digits shown for the
+exponent, with leading zeros added if necessary. The default for
+@var{expdigits} is to show only as many digits as required. At least
+1 digit is always shown.
+
+@example
+(format #f "~,,1e" 1.0e99) @result{} "1.0E+99"
+(format #f "~,,6e" 1.0e99) @result{} "1.0E+000099"
+@end example
+
+@var{intdigits} (default 1) is the number of digits to show before the
+decimal point in the mantissa. @var{intdigits} can be zero, in which
+case the integer part is a single @nicode{0}, or it can be negative,
+in which case leading zeros are shown after the decimal point.
+
+@c FIXME: When INTDIGITS is 0, Common Lisp format apparently only
+@c shows the single 0 digit if it fits in WIDTH. format.scm seems to
+@c show it always. Is it meant to?
+
+@example
+(format #t "~,,,3e" 12345.0) @print{} 123.45E+2
+(format #t "~,,,0e" 12345.0) @print{} 0.12345E+5
+(format #t "~,,,-3e" 12345.0) @print{} 0.00012345E+8
+@end example
+
+@c FIXME: MANTDIGITS with negative INTDIGITS doesn't match CL spec,
+@c believe the spec says it ought to still show mantdigits+1 sig
+@c figures, ie. leading zeros don't count towards MANTDIGITS, but it
+@c seems to just treat MANTDIGITS as how many digits after the
+@c decimal point.
+
+If @var{overflowchar} is given then @var{width} is a hard limit. If
+the output would exceed @var{width} then instead that many
+@var{overflowchar}s are printed.
+
+@example
+(format #f "~6,,,,'xe" 100.0) @result{} "1.0E+2"
+(format #f "~3,,,,'xe" 100.0) @result{} "xxx"
+@end example
+
+@var{expchar} is the exponent marker character (default @nicode{E}).
+
+@example
+(format #t "~,,,,,,'ee" 100.0) @print{} 1.0e+2
+@end example
+
+@item @nicode{~g}
+General float. Parameters: @var{width}, @var{mantdigits},
+@var{expdigits}, @var{intdigits}, @var{overflowchar}, @var{padchar},
+@var{expchar}.
+
+Output a number or number string in either exponential format the same
+as @nicode{~e}, or fixed-point format like @nicode{~f} but aligned
+where the mantissa would have been and followed by padding where the
+exponent would have been.
+
+@c FIXME: The default MANTDIGITS is apparently max(needed,min(n,7))
+@c where 10^(n-1)<=abs(x)<=10^n. But the Common Lisp spec seems to
+@c ask for "needed" to be without leading or trailing zeros, whereas
+@c format.scm seems to include trailing zeros, ending up with it
+@c using fixed format for bigger values than it should.
+
+Fixed-point is used when the absolute value is 0.1 or more and it
+takes no more space than the mantissa in exponential format, ie.@:
+basically up to @var{mantdigits} digits.
+
+@example
+(format #f "~12,4,2g" 999.0) @result{} " 999.0 "
+(format #f "~12,4,2g" "100000") @result{} " 1.0000E+05"
+@end example
+
+The parameters are interpreted as per @nicode{~e} above. When
+fixed-point is used, the @var{decimals} parameter to @nicode{~f} is
+established from @var{mantdigits}, so as to give a total
+@math{@var{mantdigits}+1} figures.
+
+@item @nicode{~$}
+Monetary style fixed-point float. Parameters: @var{decimals},
+@var{intdigits}, @var{width}, @var{padchar}.
+
+@c For reference, fmtdoc.txi from past versions of slib showed the
+@c INTDIGITS parameter as SCALE. That looks like a typo, in the code
+@c and in the Common Lisp spec it's a minimum digits for the integer
+@c part, it isn't a power of 10 like in ~f.
+
+Output a number or number string in fixed-point format, ie.@: with a
+decimal point. @var{decimals} is the number of decimal places to
+show, default 2.
+
+@example
+(format #t "~$" 5) @print{} 5.00
+(format #t "~4$" "2.25") @print{} 2.2500
+(format #t "~4$" "1e-2") @print{} 0.0100
+@end example
+
+@nicode{~@@$} prints a @nicode{+} sign on positive numbers (including
+zero).
+
+@example
+(format #t "~@@$" 0) @print{} +0.00
+@end example
+
+@var{intdigits} is a minimum number of digits to show in the integer
+part of the value (default 1).
+
+@example
+(format #t "~,3$" 9.5) @print{} 009.50
+(format #t "~,0$" 0.125) @print{} .13
+@end example
+
+If the output is less than @var{width} characters (default 0), it's
+padded on the left with @var{padchar} (default space). @nicode{~:$}
+puts the padding after the sign.
+
+@example
+(format #f "~,,8$" -1.5) @result{} " -1.50"
+(format #f "~,,8:$" -1.5) @result{} "- 1.50"
+(format #f "~,,8,'.:@@$" 3) @result{} "+...3.00"
+@end example
+
+Note that floating point for dollar amounts is generally not a good
+idea, because a cent @math{0.01} cannot be represented exactly in the
+binary floating point Guile uses, which leads to slowly accumulating
+rounding errors. Keeping values as cents (or fractions of a cent) in
+integers then printing with the scale option in @nicode{~f} may be a
+better approach.
+
+@c For reference, fractions don't work with ~$ (or any of the float
+@c conversions) currently. If they did work then we could perhaps
+@c suggest keeping dollar amounts as rationals, which would of course
+@c give exact cents. An integer as cents is probably still a better
+@c recommendation though, since it forces one to think about where
+@c and when rounding can or should occur.
+
+@item @nicode{~i}
+Complex fixed-point float. Parameters: @var{width}, @var{decimals},
+@var{scale}, @var{overflowchar}, @var{padchar}.
+
+@c For reference, in Common Lisp ~i is an indent, but slib fmtdoc.txi
+@c described it as complex number output, so we keep that.
+
+Output the argument as a complex number, with both real and imaginary
+part shown (even if one or both are zero).
+
+The parameters and modifiers are the same as for fixed-point
+@nicode{~f} described above. The real and imaginary parts are both
+output with the same given parameters and modifiers, except that for
+the imaginary part the @nicode{@@} modifier is always enabled, so as
+to print a @nicode{+} sign between the real and imaginary parts.
+
+@example
+(format #t "~i" 1) @print{} 1.0+0.0i
+@end example
+
+@item @nicode{~p}
+Plural. No parameters.
+
+Output nothing if the argument is 1, or @samp{s} for any other
+value.
+
+@example
+(format #t "enter name~p" 1) @print{} enter name
+(format #t "enter name~p" 2) @print{} enter names
+@end example
+
+@nicode{~@@p} prints @samp{y} for 1 or @samp{ies} otherwise.
+
+@example
+(format #t "pupp~@@p" 1) @print{} puppy
+(format #t "pupp~@@p" 2) @print{} puppies
+@end example
+
+@nicode{~:p} re-uses the preceding argument instead of taking a new
+one, which can be convenient when printing some sort of count.
+
+@example
+(format #t "~d cat~:p" 9) @print{} 9 cats
+(format #t "~d pupp~:@@p" 5) @print{} 5 puppies
+@end example
+
+@nicode{~p} is designed for English plurals and there's no attempt to
+support other languages. @nicode{~[} conditionals (below) may be able
+to help. When using @code{gettext} to translate messages
+@code{ngettext} is probably best though
+(@pxref{Internationalization}).
+
+@item @nicode{~y}
+Structured printing. Parameters: @var{width}.
+
+@nicode{~y} outputs an argument using @code{pretty-print}
+(@pxref{Pretty Printing}). The result will be formatted to fit within
+@var{width} columns (79 by default), consuming multiple lines if
+necessary.
+
+@nicode{~@@y} outputs an argument using @code{truncated-print}
+(@pxref{Pretty Printing}). The resulting code will be formatted to fit
+within @var{width} columns (79 by default), on a single line. The
+output will be truncated if necessary.
+
+@nicode{~:@@y} is like @nicode{~@@y}, except the @var{width} parameter
+is interpreted to be the maximum column to which to output. That is to
+say, if you are at column 10, and @nicode{~60:@@y} is seen, the datum
+will be truncated to 50 columns.
+
+@item @nicode{~?}
+@itemx @nicode{~k}
+Sub-format. No parameters.
+
+Take a format string argument and a second argument which is a list of
+arguments for that string, and output the result.
+
+@example
+(format #t "~?" "~d ~d" '(1 2)) @print{} 1 2
+@end example
+
+@nicode{~@@?} takes arguments for the sub-format directly rather than
+in a list.
+
+@example
+(format #t "~@@? ~s" "~d ~d" 1 2 "foo") @print{} 1 2 "foo"
+@end example
+
+@nicode{~?} and @nicode{~k} are the same, @nicode{~k} is provided for
+T-Scheme compatibility.
+
+@item @nicode{~*}
+Argument jumping. Parameter: @var{N}.
+
+Move forward @var{N} arguments (default 1) in the argument list.
+@nicode{~:*} moves backwards. (@var{N} cannot be negative.)
+
+@example
+(format #f "~d ~2*~d" 1 2 3 4) @result{} "1 4"
+(format #f "~d ~:*~d" 6) @result{} "6 6"
+@end example
+
+@nicode{~@@*} moves to argument number @var{N}. The first argument is
+number 0 (and that's the default for @var{N}).
+
+@example
+(format #f "~d~d again ~@@*~d~d" 1 2) @result{} "12 again 12"
+(format #f "~d~d~d ~1@@*~d~d" 1 2 3) @result{} "123 23"
+@end example
+
+A @nicode{#} move to the end followed by a @nicode{:} modifier move
+back can be used for an absolute position relative to the end of the
+argument list, a reverse of what the @nicode{@@} modifier does.
+
+@example
+(format #t "~#*~2:*~a" 'a 'b 'c 'd) @print{} c
+@end example
+
+At the end of the format string the current argument position doesn't
+matter, any further arguments are ignored.
+
+@item @nicode{~t}
+Advance to a column position. Parameters: @var{colnum}, @var{colinc},
+@var{padchar}.
+
+Output @var{padchar} (space by default) to move to the given
+@var{colnum} column. The start of the line is column 0, the default
+for @var{colnum} is 1.
+
+@example
+(format #f "~tX") @result{} " X"
+(format #f "~3tX") @result{} " X"
+@end example
+
+If the current column is already past @var{colnum}, then the move is
+to there plus a multiple of @var{colinc}, ie.@: column
+@math{@var{colnum} + @var{N} * @var{colinc}} for the smallest @var{N}
+which makes that value greater than or equal to the current column.
+The default @var{colinc} is 1 (which means no further move).
+
+@example
+(format #f "abcd~2,5,'.tx") @result{} "abcd...x"
+@end example
+
+@nicode{~@@t} takes @var{colnum} as an offset from the current column.
+@var{colnum} many pad characters are output, then further padding to
+make the current column a multiple of @var{colinc}, if it isn't
+already so.
+
+@example
+(format #f "a~3,5'*@@tx") @result{} "a****x"
+@end example
+
+@nicode{~t} is implemented using @code{port-column} (@pxref{Reading}),
+so it works even there has been other output before @code{format}.
+
+@item @nicode{~~}
+Tilde character. Parameter: @var{n}.
+
+Output a tilde character @nicode{~}, or @var{n} many if a parameter is
+given. Normally @nicode{~} introduces an escape sequence, @nicode{~~}
+is the way to output a literal tilde.
+
+@item @nicode{~%}
+Newline. Parameter: @var{n}.
+
+Output a newline character, or @var{n} many if a parameter is given.
+A newline (or a few newlines) can of course be output just by
+including them in the format string.
+
+@item @nicode{~&}
+Start a new line. Parameter: @var{n}.
+
+Output a newline if not already at the start of a line. With a
+parameter, output that many newlines, but with the first only if not
+already at the start of a line. So for instance 3 would be a newline
+if not already at the start of a line, and 2 further newlines.
+
+@item @nicode{~_}
+Space character. Parameter: @var{n}.
+
+@c For reference, in Common Lisp ~_ is a conditional newline, but
+@c slib fmtdoc.txi described it as a space, so we keep that.
+
+Output a space character, or @var{n} many if a parameter is given.
+
+With a variable parameter this is one way to insert runtime calculated
+padding (@nicode{~t} or the various field widths can do similar
+things).
+
+@example
+(format #f "~v_foo" 4) @result{} " foo"
+@end example
+
+@item @nicode{~/}
+Tab character. Parameter: @var{n}.
+
+Output a tab character, or @var{n} many if a parameter is given.
+
+@item @nicode{~|}
+Formfeed character. Parameter: @var{n}.
+
+Output a formfeed character, or @var{n} many if a parameter is given.
+
+@item @nicode{~!}
+Force output. No parameters.
+
+At the end of output, call @code{force-output} to flush any buffers on
+the destination (@pxref{Writing}). @nicode{~!} can occur anywhere in
+the format string, but the force is done at the end of output.
+
+When output is to a string (destination @code{#f}), @nicode{~!} does
+nothing.
+
+@item @nicode{~newline} (ie.@: newline character)
+Continuation line. No parameters.
+
+Skip this newline and any following whitespace in the format string,
+ie.@: don't send it to the output. This can be used to break up a
+long format string for readability, but not print the extra
+whitespace.
+
+@example
+(format #f "abc~
+ ~d def~
+ ~d" 1 2) @result{} "abc1 def2"
+@end example
+
+@nicode{~:newline} skips the newline but leaves any further whitespace
+to be printed normally.
+
+@nicode{~@@newline} prints the newline then skips following
+whitespace.
+
+@item @nicode{~(} @nicode{~)}
+Case conversion. No parameters.
+
+Between @nicode{~(} and @nicode{~)} the case of all output is changed.
+The modifiers on @nicode{~(} control the conversion.
+
+@itemize @w{}
+@item
+@nicode{~(} --- lower case.
+@c
+@c FIXME: The : and @ modifiers are not yet documented because the
+@c code applies string-capitalize and string-capitalize-first to each
+@c separate format:out-str call, which has various subtly doubtful
+@c effects. And worse they're applied to individual characters,
+@c including literal characters in the format string, which has the
+@c silly effect of being always an upcase.
+@c
+@c The Common Lisp spec is apparently for the capitalization to be
+@c applied in one hit to the whole of the output between ~( and ~).
+@c (This can no doubt be implemented without accumulating all that
+@c text, just by keeping a state or the previous char to tell whether
+@c within a word.)
+@c
+@c @item
+@c @nicode{:} --- first letter of each word upper case, the rest lower
+@c case, as per the @code{string-capitalize} function (@pxref{Alphabetic
+@c Case Mapping}).
+@c @item
+@c @nicode{@@} --- first letter of just the first word upper case, the
+@c rest lower case.
+@c
+@item
+@nicode{~:@@(} --- upper case.
+@end itemize
+
+For example,
+
+@example
+(format #t "~(Hello~)") @print{} hello
+(format #t "~:@@(Hello~)") @print{} HELLO
+@end example
+
+In the future it's intended the modifiers @nicode{:} and @nicode{@@}
+alone will capitalize the first letters of words, as per Common Lisp
+@code{format}, but the current implementation of this is flawed and
+not recommended for use.
+
+Case conversions do not nest, currently. This might change in the
+future, but if it does then it will be to Common Lisp style where the
+outermost conversion has priority, overriding inner ones (making those
+fairly pointless).
+
+@item @nicode{~@{} @nicode{~@}}
+Iteration. Parameter: @var{maxreps} (for @nicode{~@{}).
+
+The format between @nicode{~@{} and @nicode{~@}} is iterated. The
+modifiers to @nicode{~@{} determine how arguments are taken. The
+default is a list argument with each iteration successively consuming
+elements from it. This is a convenient way to output a whole list.
+
+@example
+(format #t "~@{~d~@}" '(1 2 3)) @print{} 123
+(format #t "~@{~s=~d ~@}" '("x" 1 "y" 2)) @print{} "x"=1 "y"=2
+@end example
+
+@nicode{~:@{} takes a single argument which is a list of lists, each
+of those contained lists gives the arguments for the iterated format.
+
+@c @print{} on a new line here to avoid overflowing page width in DVI
+@example
+(format #t "~:@{~dx~d ~@}" '((1 2) (3 4) (5 6)))
+@print{} 1x2 3x4 5x6
+@end example
+
+@nicode{~@@@{} takes arguments directly, with each iteration
+successively consuming arguments.
+
+@example
+(format #t "~@@@{~d~@}" 1 2 3) @print{} 123
+(format #t "~@@@{~s=~d ~@}" "x" 1 "y" 2) @print{} "x"=1 "y"=2
+@end example
+
+@nicode{~:@@@{} takes list arguments, one argument for each iteration,
+using that list for the format.
+
+@c @print{} on a new line here to avoid overflowing page width in DVI
+@example
+(format #t "~:@@@{~dx~d ~@}" '(1 2) '(3 4) '(5 6))
+@print{} 1x2 3x4 5x6
+@end example
+
+Iterating stops when there are no more arguments or when the
+@var{maxreps} parameter to @nicode{~@{} is reached (default no
+maximum).
+
+@example
+(format #t "~2@{~d~@}" '(1 2 3 4)) @print{} 12
+@end example
+
+If the format between @nicode{~@{} and @nicode{~@}} is empty, then a
+format string argument is taken (before iteration argument(s)) and
+used instead. This allows a sub-format (like @nicode{~?} above) to be
+iterated.
+
+@example
+(format #t "~@{~@}" "~d" '(1 2 3)) @print{} 123
+@end example
+
+@c FIXME: What is the @nicode{:} modifier to ~} meant to do? The
+@c Common Lisp spec says it's a minimum of 1 iteration, but the
+@c format.scm code seems to merely make it have MAXREPS default to 1.
+
+Iterations can be nested, an inner iteration operates in the same way
+as described, but of course on the arguments the outer iteration
+provides it. This can be used to work into nested list structures.
+For example in the following the inner @nicode{~@{~d~@}x} is applied
+to @code{(1 2)} then @code{(3 4 5)} etc.
+
+@example
+(format #t "~@{~@{~d~@}x~@}" '((1 2) (3 4 5))) @print{} 12x345x
+@end example
+
+See also @nicode{~^} below for escaping from iteration.
+
+@item @nicode{~[} @nicode{~;} @nicode{~]}
+Conditional. Parameter: @var{selector}.
+
+A conditional block is delimited by @nicode{~[} and @nicode{~]}, and
+@nicode{~;} separates clauses within the block. @nicode{~[} takes an
+integer argument and that number clause is used. The first clause is
+number 0.
+
+@example
+(format #f "~[peach~;banana~;mango~]" 1) @result{} "banana"
+@end example
+
+The @var{selector} parameter can be used for the clause number,
+instead of taking an argument.
+
+@example
+(format #f "~2[peach~;banana~;mango~]") @result{} "mango"
+@end example
+
+If the clause number is out of range then nothing is output. Or the
+last clause can be @nicode{~:;} to use that for a number out of range.
+
+@example
+(format #f "~[banana~;mango~]" 99) @result{} ""
+(format #f "~[banana~;mango~:;fruit~]" 99) @result{} "fruit"
+@end example
+
+@nicode{~:[} treats the argument as a flag, and expects two clauses.
+The first is used if the argument is @code{#f} or the second
+otherwise.
+
+@example
+(format #f "~:[false~;not false~]" #f) @result{} "false"
+(format #f "~:[false~;not false~]" 'abc) @result{} "not false"
+
+(let ((n 3))
+ (format #t "~d gnu~:[s are~; is~] here" n (= 1 n)))
+@print{} 3 gnus are here
+@end example
+
+@nicode{~@@[} also treats the argument as a flag, and expects one
+clause. If the argument is @code{#f} then no output is produced and
+the argument is consumed, otherwise the clause is used and the
+argument is not consumed, it's left for the clause. This can be used
+for instance to suppress output if @code{#f} means something not
+available.
+
+@example
+(format #f "~@@[temperature=~d~]" 27) @result{} "temperature=27"
+(format #f "~@@[temperature=~d~]" #f) @result{} ""
+@end example
+
+@item @nicode{~^}
+Escape. Parameters: @var{val1}, @var{val2}, @var{val3}.
+
+Stop formatting if there are no more arguments. This can be used for
+instance to have a format string adapt to a variable number of
+arguments.
+
+@example
+(format #t "~d~^ ~d" 1) @print{} 1
+(format #t "~d~^ ~d" 1 2) @print{} 1 2
+@end example
+
+Within a @nicode{~@{} @nicode{~@}} iteration, @nicode{~^} stops the
+current iteration step if there are no more arguments to that step,
+but continuing with possible further steps and the rest of the format.
+This can be used for instance to avoid a separator on the last
+iteration, or to adapt to variable length argument lists.
+
+@example
+(format #f "~@{~d~^/~@} go" '(1 2 3)) @result{} "1/2/3 go"
+(format #f "~:@{ ~d~^~d~@} go" '((1) (2 3))) @result{} " 1 23 go"
+@end example
+
+@c For reference, format.scm doesn't implement that Common Lisp ~:^
+@c modifier which stops the entire iterating of ~:{ or ~@:{.
+
+@c FIXME: Believe the Common Lisp spec is for ~^ within ~[ ~]
+@c conditional to terminate the whole format (or iteration step if in
+@c an iteration). But format.scm seems to terminate just the
+@c conditional form.
+@c
+@c (format #f "~[abc~^def~;ghi~] blah" 0)
+@c @result{} "abc blah" ;; looks wrong
+
+@c FIXME: Believe the Common Lisp spec is for ~^ within ~( ~) to end
+@c that case conversion and then also terminate the whole format (or
+@c iteration step if in an iteration). But format.scm doesn't seem
+@c to do that quite right.
+@c
+@c (format #f "~d ~^ ~d" 1) @result{} "1 "
+@c (format #f "~(~d ~^ ~d~)" 1) @result{} ERROR
+
+Within a @nicode{~?} sub-format, @nicode{~^} operates just on that
+sub-format. If it terminates the sub-format then the originating
+format will still continue.
+
+@example
+(format #t "~? items" "~d~^ ~d" '(1)) @print{} 1 items
+(format #t "~? items" "~d~^ ~d" '(1 2)) @print{} 1 2 items
+@end example
+
+The parameters to @nicode{~^} (which are numbers) change the condition
+used to terminate. For a single parameter, termination is when that
+value is zero (notice this makes plain @nicode{~^} equivalent to
+@nicode{~#^}). For two parameters, termination is when those two are
+equal. For three parameters, termination is when @math{@var{val1}
+@le{} @var{val2}} and @math{@var{val2} @le{} @var{val3}}.
+
+@c FIXME: Good examples of these?
+
+@item @nicode{~q}
+Inquiry message. Insert a copyright message into the output.
+
+@nicode{~:q} inserts the format implementation version.
+@end table
+
+@sp 1
+It's an error if there are not enough arguments for the escapes in the
+format string, but any excess arguments are ignored.
+
+Iterations @nicode{~@{} @nicode{~@}} and conditionals @nicode{~[}
+@nicode{~;} @nicode{~]} can be nested, but must be properly nested,
+meaning the inner form must be entirely within the outer form. So
+it's not possible, for instance, to try to conditionalize the endpoint
+of an iteration.
+
+@example
+(format #t "~@{ ~[ ... ~] ~@}" ...) ;; good
+(format #t "~@{ ~[ ... ~@} ... ~]" ...) ;; bad
+@end example
+
+The same applies to case conversions @nicode{~(} @nicode{~)}, they
+must properly nest with respect to iterations and conditionals (though
+currently a case conversion cannot nest within another case
+conversion).
+
+When a sub-format (@nicode{~?}) is used, that sub-format string must
+be self-contained. It cannot for instance give a @nicode{~@{} to
+begin an iteration form and have the @nicode{~@}} up in the
+originating format, or similar.
+@end deffn
+
+@sp 1
+Guile contains a @code{format} procedure even when the module
+@code{(ice-9 format)} is not loaded. The default @code{format} is
+@code{simple-format} (@pxref{Writing}), it doesn't support all escape
+sequences documented in this section, and will signal an error if you
+try to use one of them. The reason for two versions is that the full
+@code{format} is fairly large and requires some time to load.
+@code{simple-format} is often adequate too.
+
+
+@node File Tree Walk
+@section File Tree Walk
+@cindex file tree walk
+
+The functions in this section traverse a tree of files and
+directories, in a fashion similar to the C @code{ftw} and @code{nftw}
+routines (@pxref{Working with Directory Trees,,, libc, GNU C Library
+Reference Manual}).
+
+@example
+(use-modules (ice-9 ftw))
+@end example
+@sp 1
+
+@defun ftw startname proc ['hash-size n]
+Walk the file system tree descending from @var{startname}, calling
+@var{proc} for each file and directory.
+
+Hard links and symbolic links are followed. A file or directory is
+reported to @var{proc} only once, and skipped if seen again in another
+place. One consequence of this is that @code{ftw} is safe against
+circularly linked directory structures.
+
+Each @var{proc} call is @code{(@var{proc} filename statinfo flag)} and
+it should return @code{#t} to continue, or any other value to stop.
+
+@var{filename} is the item visited, being @var{startname} plus a
+further path and the name of the item. @var{statinfo} is the return
+from @code{stat} (@pxref{File System}) on @var{filename}. @var{flag}
+is one of the following symbols,
+
+@table @code
+@item regular
+@var{filename} is a file, this includes special files like devices,
+named pipes, etc.
+
+@item directory
+@var{filename} is a directory.
+
+@item invalid-stat
+An error occurred when calling @code{stat}, so nothing is known.
+@var{statinfo} is @code{#f} in this case.
+
+@item directory-not-readable
+@var{filename} is a directory, but one which cannot be read and hence
+won't be recursed into.
+
+@item symlink
+@var{filename} is a dangling symbolic link. Symbolic links are
+normally followed and their target reported, the link itself is
+reported if the target does not exist.
+@end table
+
+The return value from @code{ftw} is @code{#t} if it ran to completion,
+or otherwise the non-@code{#t} value from @var{proc} which caused the
+stop.
+
+Optional argument symbol @code{hash-size} and an integer can be given
+to set the size of the hash table used to track items already visited.
+(@pxref{Hash Table Reference})
+
+@c Actually, it's probably safe to escape from ftw, just need to
+@c check it.
+@c
+In the current implementation, returning non-@code{#t} from @var{proc}
+is the only valid way to terminate @code{ftw}. @var{proc} must not
+use @code{throw} or similar to escape.
+@end defun
+
+
+@defun nftw startname proc ['chdir] ['depth] ['hash-size n] ['mount] ['physical]
+Walk the file system tree starting at @var{startname}, calling
+@var{proc} for each file and directory. @code{nftw} has extra
+features over the basic @code{ftw} described above.
+
+Like @code{ftw}, hard links and symbolic links are followed. A file
+or directory is reported to @var{proc} only once, and skipped if seen
+again in another place. One consequence of this is that @code{nftw}
+is safe against circular linked directory structures.
+
+Each @var{proc} call is @code{(@var{proc} filename statinfo flag
+base level)} and it should return @code{#t} to continue, or any
+other value to stop.
+
+@var{filename} is the item visited, being @var{startname} plus a
+further path and the name of the item. @var{statinfo} is the return
+from @code{stat} on @var{filename} (@pxref{File System}). @var{base}
+is an integer offset into @var{filename} which is where the basename
+for this item begins. @var{level} is an integer giving the directory
+nesting level, starting from 0 for the contents of @var{startname} (or
+that item itself if it's a file). @var{flag} is one of the following
+symbols,
+
+@table @code
+@item regular
+@var{filename} is a file, including special files like devices, named
+pipes, etc.
+
+@item directory
+@var{filename} is a directory.
+
+@item directory-processed
+@var{filename} is a directory, and its contents have all been visited.
+This flag is given instead of @code{directory} when the @code{depth}
+option below is used.
+
+@item invalid-stat
+An error occurred when applying @code{stat} to @var{filename}, so
+nothing is known about it. @var{statinfo} is @code{#f} in this case.
+
+@item directory-not-readable
+@var{filename} is a directory, but one which cannot be read and hence
+won't be recursed into.
+
+@item stale-symlink
+@var{filename} is a dangling symbolic link. Links are normally
+followed and their target reported, the link itself is reported if its
+target does not exist.
+
+@item symlink
+When the @code{physical} option described below is used, this
+indicates @var{filename} is a symbolic link whose target exists (and
+is not being followed).
+@end table
+
+The following optional arguments can be given to modify the way
+@code{nftw} works. Each is passed as a symbol (and @code{hash-size}
+takes a following integer value).
+
+@table @asis
+@item @code{chdir}
+Change to the directory containing the item before calling @var{proc}.
+When @code{nftw} returns the original current directory is restored.
+
+Under this option, generally the @var{base} parameter to each
+@var{proc} call should be used to pick out the base part of the
+@var{filename}. The @var{filename} is still a path but with a changed
+directory it won't be valid (unless the @var{startname} directory was
+absolute).
+
+@item @code{depth}
+Visit files ``depth first'', meaning @var{proc} is called for the
+contents of each directory before it's called for the directory
+itself. Normally a directory is reported first, then its contents.
+
+Under this option, the @var{flag} to @var{proc} for a directory is
+@code{directory-processed} instead of @code{directory}.
+
+@item @code{hash-size @var{n}}
+Set the size of the hash table used to track items already visited.
+(@pxref{Hash Table Reference})
+
+@item @code{mount}
+Don't cross a mount point, meaning only visit items on the same
+file system as @var{startname} (ie.@: the same @code{stat:dev}).
+
+@item @code{physical}
+Don't follow symbolic links, instead report them to @var{proc} as
+@code{symlink}. Dangling links (those whose target doesn't exist) are
+still reported as @code{stale-symlink}.
+@end table
+
+The return value from @code{nftw} is @code{#t} if it ran to
+completion, or otherwise the non-@code{#t} value from @var{proc} which
+caused the stop.
+
+@c For reference, one reason not to esacpe is that the current
+@c directory is not saved and restored with dynamic-wind. Maybe
+@c changing that would be enough to allow escaping.
+@c
+In the current implementation, returning non-@code{#t} from @var{proc}
+is the only valid way to terminate @code{ftw}. @var{proc} must not
+use @code{throw} or similar to escape.
+@end defun
+
+
+@node Queues
+@section Queues
+@cindex queues
+@tindex Queues
+
+@noindent
+The functions in this section are provided by
+
+@example
+(use-modules (ice-9 q))
+@end example
+
+This module implements queues holding arbitrary scheme objects and
+designed for efficient first-in / first-out operations.
+
+@code{make-q} creates a queue, and objects are entered and removed
+with @code{enq!} and @code{deq!}. @code{q-push!} and @code{q-pop!}
+can be used too, treating the front of the queue like a stack.
+
+@sp 1
+
+@deffn {Scheme Procedure} make-q
+Return a new queue.
+@end deffn
+
+@deffn {Scheme Procedure} q? obj
+Return @code{#t} if @var{obj} is a queue, or @code{#f} if not.
+
+Note that queues are not a distinct class of objects but are
+implemented with cons cells. For that reason certain list structures
+can get @code{#t} from @code{q?}.
+@end deffn
+
+@deffn {Scheme Procedure} enq! q obj
+Add @var{obj} to the rear of @var{q}, and return @var{q}.
+@end deffn
+
+@deffn {Scheme Procedure} deq! q
+@deffnx {Scheme Procedure} q-pop! q
+Remove and return the front element from @var{q}. If @var{q} is
+empty, a @code{q-empty} exception is thrown.
+
+@code{deq!} and @code{q-pop!} are the same operation, the two names
+just let an application match @code{enq!} with @code{deq!}, or
+@code{q-push!} with @code{q-pop!}.
+@end deffn
+
+@deffn {Scheme Procedure} q-push! q obj
+Add @var{obj} to the front of @var{q}, and return @var{q}.
+@end deffn
+
+@deffn {Scheme Procedure} q-length q
+Return the number of elements in @var{q}.
+@end deffn
+
+@deffn {Scheme Procedure} q-empty? q
+Return true if @var{q} is empty.
+@end deffn
+
+@deffn {Scheme Procedure} q-empty-check q
+Throw a @code{q-empty} exception if @var{q} is empty.
+@end deffn
+
+@deffn {Scheme Procedure} q-front q
+Return the first element of @var{q} (without removing it). If @var{q}
+is empty, a @code{q-empty} exception is thrown.
+@end deffn
+
+@deffn {Scheme Procedure} q-rear q
+Return the last element of @var{q} (without removing it). If @var{q}
+is empty, a @code{q-empty} exception is thrown.
+@end deffn
+
+@deffn {Scheme Procedure} q-remove! q obj
+Remove all occurrences of @var{obj} from @var{q}, and return @var{q}.
+@var{obj} is compared to queue elements using @code{eq?}.
+@end deffn
+
+@sp 1
+@cindex @code{q-empty}
+The @code{q-empty} exceptions described above are thrown just as
+@code{(throw 'q-empty)}, there's no message etc like an error throw.
+
+A queue is implemented as a cons cell, the @code{car} containing a
+list of queued elements, and the @code{cdr} being the last cell in
+that list (for ease of enqueuing).
+
+@example
+(@var{list} . @var{last-cell})
+@end example
+
+@noindent
+If the queue is empty, @var{list} is the empty list and
+@var{last-cell} is @code{#f}.
+
+An application can directly access the queue list if desired, for
+instance to search the elements or to insert at a specific point.
+
+@deffn {Scheme Procedure} sync-q! q
+Recompute the @var{last-cell} field in @var{q}.
+
+All the operations above maintain @var{last-cell} as described, so
+normally there's no need for @code{sync-q!}. But if an application
+modifies the queue @var{list} then it must either maintain
+@var{last-cell} similarly, or call @code{sync-q!} to recompute it.
+@end deffn
+
+
+@node Streams
+@section Streams
+@cindex streams
+
+A stream represents a sequence of values, each of which is calculated
+only when required. This allows large or even infinite sequences to
+be represented and manipulated with familiar operations like ``car'',
+``cdr'', ``map'' or ``fold''. In such manipulations only as much as
+needed is actually held in memory at any one time. The functions in
+this section are available from
+
+@example
+(use-modules (ice-9 streams))
+@end example
+
+Streams are implemented using promises (@pxref{Delayed Evaluation}),
+which is how the underlying calculation of values is made only when
+needed, and the values then retained so the calculation is not
+repeated.
+
+@noindent
+Here is a simple example producing a stream of all odd numbers,
+
+@example
+(define odds (make-stream (lambda (state)
+ (cons state (+ state 2)))
+ 1))
+(stream-car odds) @result{} 1
+(stream-car (stream-cdr odds)) @result{} 3
+@end example
+
+@noindent
+@code{stream-map} could be used to derive a stream of odd squares,
+
+@example
+(define (square n) (* n n))
+(define oddsquares (stream-map square odds))
+@end example
+
+These are infinite sequences, so it's not possible to convert them to
+a list, but they could be printed (infinitely) with for example
+
+@example
+(stream-for-each (lambda (n sq)
+ (format #t "~a squared is ~a\n" n sq))
+ odds oddsquares)
+@print{}
+1 squared is 1
+3 squared is 9
+5 squared is 25
+7 squared is 49
+@dots{}
+@end example
+
+@sp 1
+@defun make-stream proc initial-state
+Return a new stream, formed by calling @var{proc} successively.
+
+Each call is @code{(@var{proc} @var{state})}, it should return a pair,
+the @code{car} being the value for the stream, and the @code{cdr}
+being the new @var{state} for the next call. For the first call
+@var{state} is the given @var{initial-state}. At the end of the
+stream, @var{proc} should return some non-pair object.
+@end defun
+
+@defun stream-car stream
+Return the first element from @var{stream}. @var{stream} must not be
+empty.
+@end defun
+
+@defun stream-cdr stream
+Return a stream which is the second and subsequent elements of
+@var{stream}. @var{stream} must not be empty.
+@end defun
+
+@defun stream-null? stream
+Return true if @var{stream} is empty.
+@end defun
+
+@defun list->stream list
+@defunx vector->stream vector
+Return a stream with the contents of @var{list} or @var{vector}.
+
+@var{list} or @var{vector} should not be modified subsequently, since
+it's unspecified whether changes there will be reflected in the stream
+returned.
+@end defun
+
+@defun port->stream port readproc
+Return a stream which is the values obtained by reading from
+@var{port} using @var{readproc}. Each read call is
+@code{(@var{readproc} @var{port})}, and it should return an EOF object
+(@pxref{Reading}) at the end of input.
+
+For example a stream of characters from a file,
+
+@example
+(port->stream (open-input-file "/foo/bar.txt") read-char)
+@end example
+@end defun
+
+@defun stream->list stream
+Return a list which is the entire contents of @var{stream}.
+@end defun
+
+@defun stream->reversed-list stream
+Return a list which is the entire contents of @var{stream}, but in
+reverse order.
+@end defun
+
+@defun stream->list&length stream
+Return two values (@pxref{Multiple Values}), being firstly a list
+which is the entire contents of @var{stream}, and secondly the number
+of elements in that list.
+@end defun
+
+@defun stream->reversed-list&length stream
+Return two values (@pxref{Multiple Values}) being firstly a list which
+is the entire contents of @var{stream}, but in reverse order, and
+secondly the number of elements in that list.
+@end defun
+
+@defun stream->vector stream
+Return a vector which is the entire contents of @var{stream}.
+@end defun
+
+@defun stream-fold proc init stream0 @dots{} streamN
+Apply @var{proc} successively over the elements of the given streams,
+from first to last until the end of the shortest stream is reached.
+Return the result from the last @var{proc} call.
+
+Each call is @code{(@var{proc} elem0 @dots{} elemN prev)}, where each
+@var{elem} is from the corresponding @var{stream}. @var{prev} is the
+return from the previous @var{proc} call, or the given @var{init} for
+the first call.
+@end defun
+
+@defun stream-for-each proc stream0 @dots{} streamN
+Call @var{proc} on the elements from the given @var{stream}s. The
+return value is unspecified.
+
+Each call is @code{(@var{proc} elem0 @dots{} elemN)}, where each
+@var{elem} is from the corresponding @var{stream}.
+@code{stream-for-each} stops when it reaches the end of the shortest
+@var{stream}.
+@end defun
+
+@defun stream-map proc stream0 @dots{} streamN
+Return a new stream which is the results of applying @var{proc} to the
+elements of the given @var{stream}s.
+
+Each call is @code{(@var{proc} elem0 @dots{} elemN)}, where each
+@var{elem} is from the corresponding @var{stream}. The new stream
+ends when the end of the shortest given @var{stream} is reached.
+@end defun
+
+
+@node Buffered Input
+@section Buffered Input
+@cindex Buffered input
+@cindex Line continuation
+
+The following functions are provided by
+
+@example
+(use-modules (ice-9 buffered-input))
+@end example
+
+A buffered input port allows a reader function to return chunks of
+characters which are to be handed out on reading the port. A notion
+of further input for an application level logical expression is
+maintained too, and passed through to the reader.
+
+@defun make-buffered-input-port reader
+Create an input port which returns characters obtained from the given
+@var{reader} function. @var{reader} is called (@var{reader} cont),
+and should return a string or an EOF object.
+
+The new port gives precisely the characters returned by @var{reader},
+nothing is added, so if any newline characters or other separators are
+desired they must come from the reader function.
+
+The @var{cont} parameter to @var{reader} is @code{#f} for initial
+input, or @code{#t} when continuing an expression. This is an
+application level notion, set with
+@code{set-buffered-input-continuation?!} below. If the user has
+entered a partial expression then it allows @var{reader} for instance
+to give a different prompt to show more is required.
+@end defun
+
+@defun make-line-buffered-input-port reader
+@cindex Line buffered input
+Create an input port which returns characters obtained from the
+specified @var{reader} function, similar to
+@code{make-buffered-input-port} above, but where @var{reader} is
+expected to be a line-oriented.
+
+@var{reader} is called (@var{reader} cont), and should return a string
+or an EOF object as above. Each string is a line of input without a
+newline character, the port code inserts a newline after each string.
+@end defun
+
+@defun set-buffered-input-continuation?! port cont
+Set the input continuation flag for a given buffered input
+@var{port}.
+
+An application uses this by calling with a @var{cont} flag of
+@code{#f} when beginning to read a new logical expression. For
+example with the Scheme @code{read} function (@pxref{Scheme Read}),
+
+@example
+(define my-port (make-buffered-input-port my-reader))
+
+(set-buffered-input-continuation?! my-port #f)
+(let ((obj (read my-port)))
+ ...
+@end example
+@end defun
+
+
+@c Local Variables:
+@c TeX-master: "guile.texi"
+@c End:
HCoop / bpt / guile.git / blobdiff