source: project/wiki/eggref/5/srfi-48 @ 39251

Last change on this file since 39251 was 39251, checked in by gnosis, 2 months ago

Initial revision of SRFI-48 documentation

File size: 12.1 KB
Line 
1== SRFI-48: Intermediate Format Strings
2=== Abstract
3This 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.
4
5For more information see: [[https://srfi.schemers.org/srfi-48/|SRFI-48: Intermediate Format Strings]]
6=== Issues
7Some 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.
8
9In particular, the reference implementation given here does not accept numeric arguments (aside from {{~F}}). Hence it does not support SRFI-29.
10
11It 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.
12
13As 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.
14=== Rationale
15Inheriting 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.
16
17The 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).
18
19The 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.
20=== Specification
21
22<procedure>format [port] format-string [obj ...]</procedure>
23
24Accepts 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.
25===== Each directive may consume one obj.
26* It is an error if fewer or more obj values are provided than format directives that require them.
27===== Ports
28* When a port is specified it must be either an output port or a boolean.
29* If an output-port is specified, the formatted output is output into that port.
30* If the port argument is {{#t}}, output is to the current-output-port.
31* If the port is {{#f}} or no port is specified, the output is returned as a string.
32* If the port is specified and is {{#t}} or an output-port, the result of the format function is unspecified.
33===== Encodings
34* It is unspecified which encoding is used (e.g. ASCII, EBCDIC, UNICODE).
35* A given implementation must specify which encoding is used.
36* The implementation may or may not allow the encoding to be selected or changed.
37===== Note
38* 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.
39* It is permissible, but highly discouraged, to implement pretty-print as (define pretty-print write).
40* An format directive is a two character sequence in the string where the first character is a tilde {{'~'}}.
41* Directive characters are case-independent, i.e. upper and lower case characters are interpreted the same.
42===== Each directive code's meaning is described in the following table:
43 DIRECTIVE MNEMONIC      ACTION                                                                                                                               CONSUMES?
44 ~a        Any           (display obj) for humans                                                                                                             yes
45 ~s        Slashified    (write obj) for parsers                                                                                                              yes
46 ~w        WriteCircular (write-with-shared-structure obj) like ~s, but handles recursive structures                                                          yes
47 ~d        Decimal       the obj is a number which is output in decimal radix                                                                                 yes
48 ~x        heXadecimal   the obj is a number which is output in hexdecimal radix                                                                              yes
49 ~o        Octal         the obj is a number which is output in octal radix                                                                                   yes
50 ~b        Binary        the obj is a number which is output in binary radix                                                                                  yes
51 ~c        Character     the single character obj is output by write-char                                                                                      yes
52 ~y        Yuppify       the list obj is pretty-printed to the output                                                                                         yes
53 ~?        Indirection   the obj is another format-string and the following obj is a list of arguments; format is called recursively                          yes
54 ~K        Indirection   the same as ~? for backward compatibility with some existing implementations                                                         yes
55 ~[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
56 ~~        Tilde         output a tilde                                                                                                                       no
57 ~t        Tab           output a tab character                                                                                                               no
58 ~%        Newline       output a newline character                                                                                                           no
59 ~&        Freshline     output a newline character if it is known that the previous output was not a newline                                                 no
60 ~_        Space         a single space character is output                                                                                                   no
61 ~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
62                             directive (e.g. "~t")
63* The {{~F}}, fixed format, directive requires some elucidation.
64* {{~wF}} is useful for strings or numbers.
65* 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.
66* {{~w,dF}} is typically used only on numbers.
67* For strings, the {{d}} specifier is ignored.
68* For numbers, the integer {{d}} specifies the number of decimal digits after the decimal place.
69* Both {{w}} and {{d}} must be zero or positive.
70* If {{d}} is specified, the number is processed as if added to {{0.0}}, i.e. it is converted to an inexact value.
71<enscript highlight="scheme">
72(format "~8,2F" 1/3) => "    0.33"
73</enscript>
74* If no {{d}} is specified, the number is not coerced to inexact.
75<enscript highlight="scheme">
76(format "~6F" 32) => "    32"
77</enscript>
78* Digits are padded to the right with zeros
79<enscript highlight="scheme">
80(format "~8,2F" 32) => "   32.00"
81</enscript>
82* If the number it too large to fit in the width specified, a string longer than the width is returned
83<enscript highlight="scheme">
84(format "~1,2F" 4321) => "4321.00"
85</enscript>
86* If the number is complex, {{d}} is applied to both real and imaginal parts
87<enscript highlight="scheme">
88(format "~1,2F" (sqrt -3.9)) => "0.00+1.97i"
89</enscript>
90* For very large or very small numbers, the point where exponential notation is used is implementation defined.
91<enscript highlight="scheme">
92(format "~8F" 32e5) => "   3.2e6" or "3200000.0"
93</enscript>
94=== Examples
95<enscript highlight="scheme">
96(format "~h")
97; =>
98"(format [<port>] <format-string> [<arg>...]) -- <port> is #t, #f or an output-port
99OPTION  [MNEMONIC]  DESCRIPTION -- This implementation Assumes ASCII Text Encoding
100~H  [Help]      output this text
101~A  [Any]       (display arg) for humans
102~S  [Slashified]    (write arg) for parsers
103~~  [tilde]     output a tilde
104~T  [Tab]       output a tab character
105~%  [Newline]   output a newline character
106~&  [Freshline] output a newline character if the previous output was not a newline
107~D  [Decimal]   the arg is a number which is output in decimal radix
108~X  [heXadecimal]   the arg is a number which is output in hexdecimal radix
109~O  [Octal]     the arg is a number which is output in octal radix
110~B  [Binary]    the arg is a number which is output in binary radix
111~w,dF   [Fixed]     the arg is a string or number which has width w and d digits after the decimal
112~C  [Character] character arg is output by write-char
113~_  [Space]     a single space character is output
114~Y  [Yuppify]   the list arg is pretty-printed to the output
115~?  [Indirection]   recursive format: next arg is a format-string and the following arg a list of arguments
116~K  [Indirection]   same as ~?
117"
118</enscript>
119
120<enscript highlight="scheme">
121(format "Hello, ~a" "World!")
122; => "Hello, World!"
123
124(format "Error, list is too short: ~s" '(one "two" 3))
125; => "Error, list is too short: (one \"two\" 3)"
126
127(format "test me")
128; => "test me"
129
130(format "~a ~s ~a ~s" 'this 'is "a" "test")
131; => "this is a \"test\""
132
133(format #t "#d~d #x~x #o~o #b~b~%" 32 32 32 32)
134;; Prints:   #d32 #x20 #o40 #b100000
135; => <unspecified>
136
137(format "~a ~? ~a" 'a "~s" '(new) 'test)
138; =>"a new test"
139
140(format #f "~&1~&~&2~&~&~&3~%")
141; =>
142"
1431
1442
1453
146"
147
148(format #f "~a ~? ~a ~%" 3 " ~s ~s " '(2 2) 3)
149; =>
150"3  2 2  3
151"
152
153(format "~w" (let ( (c '(a b c)) ) (set-cdr! (cddr c) c) c))
154; => "#1=(a b c . #1#)"
155
156(format "~8,2F" 32)
157; => "   32.00"
158
159(format "~8,3F" (sqrt -3.8))
160; => "0.000+1.949i"
161
162(format "~8,2F" 3.4567e11)
163; => " 3.45e11"
164
165(format "~6,3F" 1/3)
166; => " 0.333"
167
168(format "~4F" 12)
169; => "  12"
170
171(format "~8,3F" 123.3456)
172; => " 123.346"
173
174 (format "~6,3F" 123.3456)
175; => "123.346"
176
177 (format "~2,3F" 123.3456)
178; => "123.346"
179
180(format "~8,3F" "foo")
181; => "     foo"
182
183(format "~a~a~&" (list->string (list #\newline)) "")
184; =>
185"
186"
187</enscript>
188=== Author
189* Ken Dickey
190* Ported to Chicken Scheme 5 by Sergey Goldgaber
191=== Copyright
192Copyright (C) Kenneth A Dickey (2003). All Rights Reserved.
193
194Permission 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:
195
196The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
197
198THE 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.
199=== Version history
200* [[https://github.com/diamond-lizard/srfi-48/releases/tag/0.1|0.1]] - Ported to Chicken Scheme 5
Note: See TracBrowser for help on using the repository browser.