source: project/release/5/format/tags/3.2.0/format.txt @ 36265

Last change on this file since 36265 was 36265, checked in by felix winkelmann, 2 years ago

format 3.2.0

File size: 9.4 KB
Line 
1Format Specification (Format version 3.1)
2-----------------------------------------
3
4  Please consult a Common LISP format reference manual for a detailed
5description of the format string syntax.
6
7  This implementation supports directive parameters and modifiers (`:'
8and `@' characters). Multiple parameters must be separated by a comma
9(`,').  Parameters can be numerical parameters (positive or negative),
10character parameters (prefixed by a quote character (`''), variable
11parameters (`v'), number of rest arguments parameter (`#'), empty and
12default parameters.  Directive characters are case independent. The
13general form of a directive is:
14
15DIRECTIVE ::= ~{DIRECTIVE-PARAMETER,}[:][@]DIRECTIVE-CHARACTER
16
17DIRECTIVE-PARAMETER ::= [ [-|+]{0-9}+ | 'CHARACTER | v | # ]
18
19
20Implemented CL Format Control Directives
21........................................
22
23  Documentation syntax: Uppercase characters represent the corresponding
24control directive characters. Lowercase characters represent control
25directive parameter descriptions.
26
27`~A'
28     Any (print as `display' does).
29    `~@A'
30          left pad.
31
32    `~MINCOL,COLINC,MINPAD,PADCHARA'
33          full padding.
34
35`~S'
36     S-expression (print as `write' does).
37    `~@S'
38          left pad.
39
40    `~MINCOL,COLINC,MINPAD,PADCHARS'
41          full padding.
42
43`~D'
44     Decimal.
45    `~@D'
46          print number sign always.
47
48    `~:D'
49          print comma separated.
50
51    `~MINCOL,PADCHAR,COMMACHARD'
52          padding.
53
54`~X'
55     Hexadecimal.
56    `~@X'
57          print number sign always.
58
59    `~:X'
60          print comma separated.
61
62    `~MINCOL,PADCHAR,COMMACHARX'
63          padding.
64
65`~O'
66     Octal.
67    `~@O'
68          print number sign always.
69
70    `~:O'
71          print comma separated.
72
73    `~MINCOL,PADCHAR,COMMACHARO'
74          padding.
75
76`~B'
77     Binary.
78    `~@B'
79          print number sign always.
80
81    `~:B'
82          print comma separated.
83
84    `~MINCOL,PADCHAR,COMMACHARB'
85          padding.
86
87`~NR'
88     Radix N.
89    `~N,MINCOL,PADCHAR,COMMACHARR'
90          padding.
91
92`~@R'
93     print a number as a Roman numeral.
94
95`~:@R'
96     print a number as an "old fashioned" Roman numeral.
97
98`~:R'
99     print a number as an ordinal English number.
100
101`~:@R'
102     print a number as a cardinal English number.
103
104`~P'
105     Plural.
106    `~@P'
107          prints `y' and `ies'.
108
109    `~:P'
110          as `~P but jumps 1 argument backward.'
111
112    `~:@P'
113          as `~@P but jumps 1 argument backward.'
114
115`~C'
116     Character.
117    `~@C'
118          prints a character as the reader can understand it (i.e. `#\'
119          prefixing).
120
121    `~:C'
122          prints a character as emacs does (eg. `^C' for ASCII 03).
123
124`~F'
125     Fixed-format floating-point (prints a flonum like MMM.NNN).
126    `~WIDTH,DIGITS,SCALE,OVERFLOWCHAR,PADCHARF'
127
128    `~@F'
129          If the number is positive a plus sign is printed.
130
131`~E'
132     Exponential floating-point (prints a flonum like MMM.NNN`E'EE).
133    `~WIDTH,DIGITS,EXPONENTDIGITS,SCALE,OVERFLOWCHAR,PADCHAR,EXPONENTCHARE'
134
135    `~@E'
136          If the number is positive a plus sign is printed.
137
138`~G'
139     General floating-point (prints a flonum either fixed or
140     exponential).
141    `~WIDTH,DIGITS,EXPONENTDIGITS,SCALE,OVERFLOWCHAR,PADCHAR,EXPONENTCHARG'
142
143    `~@G'
144          If the number is positive a plus sign is printed.
145
146`~$'
147     Dollars floating-point (prints a flonum in fixed with signs
148     separated).
149    `~DIGITS,SCALE,WIDTH,PADCHAR$'
150
151    `~@$'
152          If the number is positive a plus sign is printed.
153
154    `~:@$'
155          A sign is always printed and appears before the padding.
156
157    `~:$'
158          The sign appears before the padding.
159
160`~%'
161     Newline.
162    `~N%'
163          print N newlines.
164
165`~&'
166     print newline if not at the beginning of the output line.
167    `~N&'
168          prints `~&' and then N-1 newlines.
169
170`~|'
171     Page Separator.
172    `~N|'
173          print N page separators.
174
175`~~'
176     Tilde.
177    `~N~'
178          print N tildes.
179
180`~'<newline>
181     Continuation Line.
182    `~:'<newline>
183          newline is ignored, white space left.
184
185    `~@'<newline>
186          newline is left, white space ignored.
187
188`~T'
189     Tabulation.
190    `~@T'
191          relative tabulation.
192
193    `~COLNUM,COLINCT'
194          full tabulation.
195
196`~?'
197     Indirection (expects indirect arguments as a list).
198    `~@?'
199          extracts indirect arguments from format arguments.
200
201`~(STR~)'
202     Case conversion (converts by `string-downcase').
203    `~:(STR~)'
204          converts by `string-capitalize'.
205
206    `~@(STR~)'
207          converts by `string-capitalize-first'.
208
209    `~:@(STR~)'
210          converts by `string-upcase'.
211
212`~*'
213     Argument Jumping (jumps 1 argument forward).
214    `~N*'
215          jumps N arguments forward.
216
217    `~:*'
218          jumps 1 argument backward.
219
220    `~N:*'
221          jumps N arguments backward.
222
223    `~@*'
224          jumps to the 0th argument.
225
226    `~N@*'
227          jumps to the Nth argument (beginning from 0)
228
229`~[STR0~;STR1~;...~;STRN~]'
230     Conditional Expression (numerical clause conditional).
231    `~N['
232          take argument from N.
233
234    `~@['
235          true test conditional.
236
237    `~:['
238          if-else-then conditional.
239
240    `~;'
241          clause separator.
242
243    `~:;'
244          default clause follows.
245
246`~{STR~}'
247     Iteration (args come from the next argument (a list)). Iteration
248     bounding is controlled by configuration variables
249     format:iteration-bounded and format:max-iterations. With both variables
250     default, a maximum of 100 iterations will be performed.
251    `~N{'
252          at most N iterations.
253
254    `~:{'
255          args from next arg (a list of lists).
256
257    `~@{'
258          args from the rest of arguments.
259
260    `~:@{'
261          args from the rest args (lists).
262
263`~^'
264     Up and out.
265    `~N^'
266          aborts if N = 0
267
268    `~N,M^'
269          aborts if N = M
270
271    `~N,M,K^'
272          aborts if N <= M <= K
273
274Not Implemented CL Format Control Directives
275............................................
276
277`~:A'
278     print `#f' as an empty list (see below).
279
280`~:S'
281     print `#f' as an empty list (see below).
282
283`~<~>'
284     Justification.
285
286`~:^'
287     (sorry I don't understand its semantics completely)
288
289Extended, Replaced and Additional Control Directives
290....................................................
291
292`~MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHD'
293
294`~MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHX'
295
296`~MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHO'
297
298`~MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHB'
299
300`~N,MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHR'
301     COMMAWIDTH is the number of characters between two comma
302     characters.
303
304`~I'
305     print a R4RS complex number as `~F~@Fi' with passed parameters for
306     `~F'.
307
308`~Y'
309     Pretty print formatting of an argument for scheme code lists.
310
311`~K'
312     Same as `~?.'
313
314`~!'
315     Flushes the output if format DESTINATION is a port.
316
317`~_'
318     Print a `#\space' character
319    `~N_'
320          print N `#\space' characters.
321
322`~/'
323     Print a `#\tab' character
324    `~N/'
325          print N `#\tab' characters.
326
327`~NC'
328     Takes N as an integer representation for a character. No arguments
329     are consumed. N is converted to a character by `integer->char'.  N
330     must be a positive decimal number.
331
332`~:S'
333     Print out readproof.  Prints out internal objects represented as
334     `#<...>' as strings `"#<...>"' so that the format output can always
335     be processed by `read'.
336
337`~:A'
338     Print out readproof.  Prints out internal objects represented as
339     `#<...>' as strings `"#<...>"' so that the format output can always
340     be processed by `read'.
341
342`~Q'
343     Prints information and a copyright notice on the format
344     implementation.
345    `~:Q'
346          prints format version.
347
348`~F, ~E, ~G, ~$'
349     May also print number strings, i.e. passing a number as a string
350     and format it accordingly.
351
352Configuration Variables
353-----------------------
354
355  Format has some configuration variables. There should be no modification
356necessary for the default configuration. If modification is
357desired the variable should be set after the format code is loaded.
358
359format:floats
360     System has floating-point numbers. (default #t)
361
362format:complex-numbers
363     System has complex numbers. (default #f)
364
365format:fn-max
366     Maximum number of number digits. (default 200)
367
368format:format:en-max
369     Maximum number of exponent digits. (default 10)
370
371format:expch
372     The character prefixing the exponent value in ~E printing.
373     (default #\E)
374
375format:radix-pref
376     Does number->string add a radix prefix? (default <detects upon load>)
377
378format:symbol-case-conv
379     Symbols are converted by symbol->string so the case type of the
380     printed symbols is implementation dependent.
381     format:symbol-case-conv is a one arg closure which is either #f (no
382     conversion), string-upcase, string-downcase or string-capitalize.
383     (default #f)
384
385format:iobj-case-conv
386     As format:symbol-case-conv but applies for the representation of
387     implementation internal objects. (default #f)
388
389format:iteration-bounded
390     When #t, a ~{...~} control will iterate no more than the number of
391     times specified by format:max-iterations regardless of the number
392     of iterations implied by modifiers and arguments. When #f, a
393     ~{...~} control will iterate the number of times implied by
394     modifiers and arguments, unless termination is forced by language
395     or system limitations. (default #t)
396
397format:max-iterations
398     The maximum number of iterations performed by a ~{...~} control.
399     Has effect only when format:iteration-bounded is #t. (default 100)
400
401format:unprocessed-arguments-error?
402     Are superfluous arguments treated as an error. (default #f)
Note: See TracBrowser for help on using the repository browser.