s48-refman/library/format.texi

@node Common-Lisp-style formatting
@section Common-Lisp-style formatting

@stindex formats
Scheme48 provides a simple Common-Lisp-style @code{format} facility in
the @code{formats} structure.  It does not provide nearly as much
functionality as Common Lisp, however: the considerable complexity of
Common Lisp's @code{format} was deliberately avoided because it was
deemed inconsistent with Scheme48's design goals.  Scheme48's
@code{format} is suitable for most simple purposes, anyhow.

@deffn procedure format port control-string argument @dots{} @returns{} unspecified or string
Prints @var{control-string} to @var{port}.  If, anywhere in
@var{control-string}, the character @code{~} (tilde) occurs, the
following character determines what to print in the place of the tilde
and following character.  Some formatting directives consume arguments
from @var{argument} @dots{}.  Formatting directive characters are
case-insensitive.  If @var{port} is @code{#t}, the output is printed to
to the value of @code{(current-output-port)}; if @var{port} is false,
the output is collected in a string and returned.

The complete list of formatting directives:

@table @code
@item ~~
Prints a single @code{~} (tilde), and does not consume an argument.

@item ~A
Consumes and prints the first remaining argument with @code{display}.
(`A'ny)

@item ~D
Consumes and prints the first remaining argument as a decimal number
using @code{number->string}.  (`D'ecimal)

@item ~S
Consumes and prints the first remaining argument with @code{write}.
(`S'-expression)

@item ~%
Prints a newline with @code{newline}.

@item ~&
Prints a newline with @code{newline}, unless it can be determined that
a newline was immediately previously printed to @var{port}
(@pxref{I/O extensions}).

@item ~?
Recursively formats.  The first remaining argument is consumed and must
be another control string; the argument directly thereafter is also
consumed, and it must be a list of arguments corresponding with that
control string.  The control string is formatted with those arguments
using @code{format}.

@end table

@code{Format} examples:

@lisp
(format #t "Hello, ~A!~%" "world")
    @print{} Hello, world!
    @print{}

(format #t "Hello~?~S~%" "~A world" '(#\,) '!)
    @print{} Hello, world!
    @print{}

(format #f "~A~A ~A." "cH" "uMBLE" "spuZz")
    @result{} "cHuMBLE spuZz."

(let ((x 10) (y .1))
  (format #t "x: ~D~%~&y: ~D~%~&" x y))
    @print{} x: 10
    @print{} y: .1@end lisp
@end deffn