chickadee » srfi-48

SRFI 48: Intermediate Format Strings

This egg provides SRFI 48 format strings for CHICKEN. SRFI 48 format has a wider range of features than the (chicken format) version.

SRFI Description

This page is intended to document the form exported by the egg. For a full description of SRFI 48, see the SRFI document.

Specification

formatprocedure

Accepts a format template (a 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 port is an output port, the formatted output is output into that port.
  • If port is #t, output is to the current-output-port.
  • If port is #f or omitted, the output is returned as a string.

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

A 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:

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")

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.

(format "~8F" 32e5)
; => "   3.2e6" or "3200000.0"

Examples

(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)) "")
; =>
"
"

Exceptions

This egg tries to give useful information when things go wrong. Procedure arguments are type-checked; when a type check fails, a condition of kind (exn type assertion) is raised. Similarly, arity errors raise (exn arity assertion) conditions. This conforms to the condition protocol used by CHICKEN's internal libraries. A custom condition kind, (exn format), indicates invalid format directives.

See the Module (chicken condition) page for more information.

About this egg

Author

Ken Dickey

Maintainer

Wolfgang Corcoran-Mathe

Contact: wcm at sigwinch dot xyzzy without the zy

Repository

GitHub

Version history

0.1
Ported to Chicken Scheme 5 by Sergey Goldgaber
0.2
Update maintainer, add types, minor improvements.
1.0.0
Stable public API (yes, it was already stable). Rework exceptions.

License

 Copyright (C) Kenneth A Dickey (2003). All Rights Reserved.
 Copyright (C) Wolfgang Corcoran-Mathe (2022).
 
 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.

Contents »