SRFI-48: Intermediate Format Strings

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.

For more information see: SRFI-48: Intermediate Format Strings

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 desirable that baseline library code be small, attempt to eliminate 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

[procedure] 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.
Ports
Encodings
Note
Each directive code's meaning is described in the following table:
DIRECTIVE MNEMONIC      ACTION                                                                                                                               CONSUMES?
~a        Any           (display obj) for humans                                                                                                             yes
~s        Slashified    (write obj) for parsers                                                                                                              yes
~w        WriteCircular (write-with-shared-structure obj) like ~s, but handles recursive structures                                                          yes
~d        Decimal       the obj is a number which is output in decimal radix                                                                                 yes
~x        heXadecimal   the obj is a number which is output in hexdecimal radix                                                                              yes
~o        Octal         the obj is a number which is output in octal radix                                                                                   yes
~b        Binary        the obj is a number which is output in binary radix                                                                                  yes
~c        Character     the single character obj is output by write-char                                                                                      yes
~y        Yuppify       the list obj is pretty-printed to the output                                                                                         yes
~?        Indirection   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 compatibility 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        no
                            directive (e.g. "~t")
(format "~8,2F" 1/3) => "    0.33"
(format "~6F" 32) => "    32"
(format "~8,2F" 32) => "   32.00"
(format "~1,2F" 4321) => "4321.00"
(format "~1,2F" (sqrt -3.9)) => "0.00+1.97i"
(format "~8F" 32e5) => "   3.2e6" or "3200000.0"

Examples

(format "~h")
; =>
"(format [<port>] <format-string> [<arg>...]) -- <port> is #t, #f or an output-port
OPTION  [MNEMONIC]  DESCRIPTION -- This implementation Assumes ASCII Text Encoding
~H  [Help]      output this text
~A  [Any]       (display arg) for humans
~S  [Slashified]    (write arg) for parsers
~~  [tilde]     output a tilde
~T  [Tab]       output a tab character
~%  [Newline]   output a newline character
~&  [Freshline] output a newline character if the previous output was not a newline
~D  [Decimal]   the arg is a number which is output in decimal radix
~X  [heXadecimal]   the arg is a number which is output in hexdecimal radix
~O  [Octal]     the arg is a number which is output in octal radix
~B  [Binary]    the arg is a number which is output in binary radix
~w,dF   [Fixed]     the arg is a string or number which has width w and d digits after the decimal
~C  [Character] character arg is output by write-char
~_  [Space]     a single space character is output
~Y  [Yuppify]   the list arg is pretty-printed to the output
~?  [Indirection]   recursive format: next arg is a format-string and the following arg a list of arguments
~K  [Indirection]   same as ~?
"
(format "Hello, ~a" "World!")
; => "Hello, World!"

(format "Error, list is too short: ~s" '(one "two" 3))
; => "Error, list is too short: (one \"two\" 3)"

(format "test me")
; => "test me"

(format "~a ~s ~a ~s" 'this 'is "a" "test")
; => "this is a \"test\""

(format #t "#d~d #x~x #o~o #b~b~%" 32 32 32 32)
;; Prints:   #d32 #x20 #o40 #b100000
; => <unspecified>

(format "~a ~? ~a" 'a "~s" '(new) 'test)
; =>"a new test"

(format #f "~&1~&~&2~&~&~&3~%")
; =>
"
1
2
3
"

(format #f "~a ~? ~a ~%" 3 " ~s ~s " '(2 2) 3)
; =>
"3  2 2  3
"

(format "~w" (let ( (c '(a b c)) ) (set-cdr! (cddr c) c) c))
; => "#1=(a b c . #1#)"

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

(format "~8,3F" (sqrt -3.8))
; => "0.000+1.949i"

(format "~8,2F" 3.4567e11)
; => " 3.45e11"

(format "~6,3F" 1/3)
; => " 0.333"

(format "~4F" 12)
; => "  12"

(format "~8,3F" 123.3456)
; => " 123.346"

 (format "~6,3F" 123.3456)
; => "123.346"

 (format "~2,3F" 123.3456)
; => "123.346"

(format "~8,3F" "foo")
; => "     foo"

(format "~a~a~&" (list->string (list #\newline)) "")
; =>
"
"

Author

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.

Version history