Title

Author

Status

This SRFI is currently in ``final'' status. To see an explanation of each status that a
SRFI can hold, see here.
You can access
previous messages via
the archive of the mailing list.

Received: 2003/11/24

Draft: 2003/11/25-2004/02/25

Revised: 2003/12/04

Revised: 2003/12/28

Final: 2004/03/02

Revised: 2005/06/01

Abstract

This document specifies Format Strings, a method of interpreting a Scheme string which contains a
number of format directives that are replaced with other string data according to the semantics of each directive.
This SRFI extends SRFI-28 in being more generally useful but is less general than
advanced format strings in that it does not allow, aside from ~F, for controlled positioning of text within fields.

Issues

Some may disagree with specific escape options or return values.
For those who desire complex options as implemented by SLIB
or Common Lisp's FORMAT, an upwards compatible
"Advanced Format" SRFI should be proposed.

In particular, the reference implementation given here does not accept numeric arguments
(aside from ~F).
Hence it does not support SRFI-29.

It is highly desireable that baseline library code be small, attempt to
eliminiate heap allocation and bound stack usage.
This is especially important in embedded systems.
This can be accomplished by writing directly to a port,
rather than a string, by not supporting ~W or ~F,
and by replacing
(display (number->string n r) p) with a carefully written
(display:number->string n r p) which does not build intermediate strings.

As this is intermediate format, it was felt that ~F and ~W are too highly useful to elide.
The ~H option is helpful to users, allows for programattic query, and makes clear which format directives are supported.

Rationale

Inheriting from MacLisp, nearly all Lisp and Scheme implementations support some form of
FORMAT function with support for various numbers of format directives.
By agreeing to the options here, we raise the bar for portable code.

The reference implementation is R5RS compliant and easy to port.
In not requiring advanced features (aside from ~W and ~F) small implementations are possible.
E.g. the reference code does not use side effects (assignment) and is less than
a third the source size of the latest SLIB implementation of FORMAT
(less than a tenth if ~F support is elided).

The optional port argument allows for compatibility with older code
written for, e.g. scheme48, MIT Scheme, T, et cetera, which required a port argument.
It is also useful in cases where a synoptic
implementation of Scheme and CommonLisp is maintained.

Specification

format[port] format-string [obj ...]

Accepts a format template (a Scheme String), and
processes it, replacing any format directives in order with
one or more characters, the characters themselves dependent
on the semantics of the format directive encountered. Each directive
may consume one obj. It is an error if fewer or more obj values are
provided than format directives that require them.

When a port is specified it must be either an output port or
a boolean. If an output-port is specified, the formatted output is
output into that port. If the port argument is #t, output is to the
current-output-port. If the port is #f or no port is specified, the
output is returned as a string. If the port is specified and is #t
or an output-port, the result of the format function is unspecified.

It is unspecified which encoding is used (e.g. ASCII, EBCDIC, UNICODE).
A given implementation must specify which encoding is used.
The implementation may or may not allow the encoding to be selected or changed.

It is an error if an format directive consumes an obj argument and
that argument does not
confirm to a required type as noted in the table below.

It is permissible, but highly discouraged, to implement pretty-print as
(define pretty-print write).

An format directive is a two character sequence in the
string where the first character is a tilde '~'. Directive characters
are case-independent, i.e. upper and lower case characters
are interpreted the same. Each directive
code's meaning is described in the following table:

the obj is another format-string and the following obj is a list of arguments; format is called recursively

yes

~K

Indirection

the same as ~? for backward compatability with some existing implementations

yes

~[w[,d]]F

Fixed

~w,dF outputs a number with width w and d digits after the decimal;
~wF outputs a string or number with width w.

yes

~~

Tilde

output a tilde

no

~t

Tab

output a tab character

no

~%

Newline

output a newline character

no

~&

Freshline

output a newline character if it is known that the previous output was not a newline

no

~_

Space

a single space character is output

no

~h

Help

outputs one line of call synopsis, one line of comment, and one line of
synopsis for each format directive, starting with the directive (e.g. "~t")

no

The ~F, fixed format, directive requires some elucidation.

~wF is useful for strings or numbers. Where the string (or number->string
of the number) has fewer characters than the integer width w, the string is
padded on the left with space characters.

~w,dF is typically used only on numbers. For strings, the d
specifier is ignored. For numbers, the integer d specifies the number
of decimal digits after the decimal place. Both w and d must be
zero or positive.

If d is specified, the number is processed
as if added to 0.0, i.e. it is converted to an inexact value.

(format "~8,2F" 1/3) => " 0.33"

If no d is specified, the number is not coerced to inexact.

(format "~6F" 32) => " 32"

Digits are padded to the right with zeros

(format "~8,2F" 32) => " 32.00"

If the number it too large to fit in the width specified,
a string longer than the width is returned

(format "~1,2F" 4321) => "4321.00"

If the number is complex, d is applied to both real and imaginal parts

(format "~1,2F" (sqrt -3.9)) => "0.00+1.97i"

For very large or very small numbers, the point where exponential notation
is used is implementation defined.

Copyright

Copyright (C) Kenneth A Dickey (2003). All Rights Reserved.

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.