(guile.info.gz) Formatted Output
Info Catalog
(guile.info.gz) Pretty Printing
(guile.info.gz) Top
(guile.info.gz) Rx Regexps
43 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 `display', `write'
and `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 `format' procedure, to be found in module `(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 `fprintf'.
-- Scheme Procedure: format destination format-string args ...
The first parameter is the DESTINATION, it determines where the
output of `format' will go.
`#t'
Send the formatted output to the current output port and
return `#t'.
`#f'
Return the formatted output as a string.
Any number value
Send the formatted output to the current error port and return
`#t'.
A valid output port
Send the formatted output to the port DESTINATION and return
`#t'.
The second parameter is the format string. It has a similar
function to the format string in calls to `printf' or `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 `~'
(tilde), and not with a `%' (percent sign), as in C.
The escape sequences in the following table are supported. When
there appears "corresponding 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 `:', `@', or `:@', 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.
`~~'
Output a single `~' (tilde) character.
`~%'
Output a newline character, thus advancing to the next output
line.
`~&'
Start a new line, that is, output a newline character if not
already at the start of a line.
`~_'
Output a single space character.
`~/'
Output a single tabulator character.
`~|'
Output a page separator (formfeed) character.
`~t'
Advance to the next tabulator position.
`~y'
Pretty-print the corresponding ARG.
`~a'
Output the corresponding ARG like `display'.
`~s'
Output the corresponding ARG like `write'.
`~d'
Output the corresponding ARG as a decimal number.
`~x'
Output the corresponding ARG as a hexadecimal number.
`~o'
Output the corresponding ARG as an octal number.
`~b'
Output the corresponding ARG as a binary number.
`~r'
Output the corresponding ARG as a number word, e.g. 10 prints
as `ten'. If prefixed with `:', `tenth' is printed, if
prefixed with `:@', Roman numbers are printed.
`~f'
Output the corresponding ARG as a fixed format floating point
number, such as `1.34'.
`~e'
Output the corresponding ARG in exponential notation, such as
`1.34E+0'.
`~g'
This works either like `~f' or like `~e', whichever produces
less characters to be written.
`~$'
Like `~f', but only with two digits after the decimal point.
`~i'
Output the corresponding ARG as a complex number.
`~c'
Output the corresponding ARG as a character. If prefixed with
`@', it is printed like with `write'. If prefixed with `:',
control characters are treated specially, for example
`#\newline' will be printed as `^J'.
`~p'
"Plural". If the corresponding ARG is 1, nothing is printed
(or `y' if prefixed with `@' or `:@'), otherwise `s' is
printed (or `ies' if prefixed with `@' or `:@').
`~?, ~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.
`~!'
Flush the output to the output port.
`~#\newline (tilde-newline)'
Continuation lines.
`~*'
Argument jumping. Navigate in the argument list as specified
by the corresponding argument. If prefixed with `:', jump
backwards in the argument list, if prefixed by `:@', jump to
the parameter with the absolute index, otherwise jump forward
in the argument list.
`~('
Case conversion begin. If prefixed by `:', the following
output string will be capitalized, if prefixed by `@', the
first character will be capitalized, if prefixed by `:@' it
will be upcased and otherwise it will be downcased.
Conversion stops when the "Case conversion end" `~)'sequence
is encountered.
`~)'
Case conversion end. Stop any case conversion currently in
effect.
`~['
Conditional begin.
`~;'
Conditional separator.
`~]'
Conditional end.
`~{'
Iteration begin.
`~}'
Iteration end.
`~^'
Up and out.
`~''
Character parameter.
`~0 ... ~9, ~-, ~+'
Numeric parameter.
`~v'
Variable parameter from next argument.
`~#'
Parameter is number of remaining args. The number of the
remaining arguments is prepended to the list of unprocessed
arguments.
`~,'
Parameter separators.
`~q'
Inquiry message. Insert a copyright message into the output.
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.
You may have noticed that Guile contains a `format' procedure even
when the module `(ice-9 format)' is not loaded. The default `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 `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 `format' by
default, so that the start-up time of the interpreter is not
unnecessarily increased.
Info Catalog
(guile.info.gz) Pretty Printing
(guile.info.gz) Top
(guile.info.gz) Rx Regexps
automatically generated byinfo2html