source: project/wiki/eggref/5/format @ 36277

Last change on this file since 36277 was 36277, checked in by Mario Domenech Goulart, 2 years ago

eggref/5/format: release note for version 3.2.1

File size: 11.4 KB
Line 
1[[tags:egg]]
2== format
3
4Formatted output, Common LISP style
5[[toc:]]
6
7== Documentation
8
9<procedure>(format DESTINATION FORMAT-STRING . ARGUMENTS)</procedure>
10
11An almost complete implementation of Common LISP format description
12according to the CL reference book '''Common LISP, the Language''' from Guy L.
13Steele, Digital Press. This code was originally part of SLIB. The author
14is Dirk Lutzebaeck.
15
16Returns {{#t}}, {{#f}} or a string; has side effect of printing according to
17{{FORMAT-STRING}}.  If {{DESTINATION}} is {{#t}}, the output is to the current
18output port and {{#t}} is returned.  If {{DESTINATION}} is {{#f}}, a formatted
19string is returned as the result of the call.  If {{DESTINATION}} is a string,
20{{DESTINATION}} is regarded as the format string; {{FORMAT-STRING}} is then
21the first argument and the output is returned as a string. If {{DESTINATION}}
22is a number, the output is to the value of {{(current-error-port)}}.
23Otherwise {{DESTINATION}} must be an output port and {{#t}} is returned.
24
25{{FORMAT-STRING}} must be a string.  In case of a formatting
26error format returns {{#f}} and prints a message on the value
27of {{(current-error-port)}}.  Characters are output as if the
28string were output by the {{display}} function with the exception
29of those prefixed by a tilde (~).  For a detailed description of
30the {{FORMAT-STRING}} syntax please consult a Common LISP format
31reference manual.
32
33This code is not reentrant, nor is it thread-safe.
34
35{{format}} implements [[http://srfi.schemers.org/srfi-28/srfi-28.html|SRFI-28]]
36
37A list of all supported, non-supported and extended directives follows:
38
39Format Specification (Format version 3.1)
40-----------------------------------------
41
42Please consult a Common LISP format reference manual for a detailed
43description of the format string syntax.
44
45This implementation supports directive parameters and modifiers (`:' and `@'
46characters). Multiple parameters must be separated by a comma (`,').
47Parameters can be numerical parameters (positive or negative), character
48parameters (prefixed by a quote character (`''), variable parameters (`v'),
49number of rest arguments parameter (`#'), empty and default parameters.
50Directive characters are case independent.
51
52The general form of a directive is:
53
54DIRECTIVE ::= ~{DIRECTIVE-PARAMETER,}[:][@]DIRECTIVE-CHARACTER
55
56DIRECTIVE-PARAMETER ::= [ [-|+]{0-9}+ | 'CHARACTER | v | # ]
57
58Implemented CL Format Control Directives
59........................................
60
61Documentation syntax: Uppercase characters represent the corresponding control
62directive characters. Lowercase characters represent control directive
63parameter descriptions.
64
65`~A'
66
67    Any (print as `display' does).
68
69   `~@A'
70
71         left pad.
72
73   `~MINCOL,COLINC,MINPAD,PADCHARA'
74
75         full padding.
76
77`~S'
78
79    S-expression (print as `write' does).
80
81   `~@S'
82
83         left pad.
84
85   `~MINCOL,COLINC,MINPAD,PADCHARS'
86
87         full padding.
88
89`~D'
90
91    Decimal.
92
93   `~@D'
94
95         print number sign always.
96
97   `~:D'
98
99         print comma separated.
100
101   `~MINCOL,PADCHAR,COMMACHARD'
102
103         padding.
104
105`~X'
106
107    Hexadecimal.
108
109   `~@X'
110
111         print number sign always.
112
113   `~:X'
114
115         print comma separated.
116
117   `~MINCOL,PADCHAR,COMMACHARX'
118
119         padding.
120
121`~O'
122
123    Octal.
124
125   `~@O'
126
127         print number sign always.
128
129   `~:O'
130
131         print comma separated.
132
133   `~MINCOL,PADCHAR,COMMACHARO'
134
135         padding.
136
137`~B'
138
139    Binary.
140
141   `~@B'
142
143         print number sign always.
144
145   `~:B'
146
147         print comma separated.
148
149   `~MINCOL,PADCHAR,COMMACHARB'
150
151         padding.
152
153`~NR'
154
155    Radix N.
156
157   `~N,MINCOL,PADCHAR,COMMACHARR'
158
159         padding.
160
161`~@R'
162
163    print a number as a Roman numeral.
164
165`~:@R'
166
167    print a number as an "old fashioned" Roman numeral.
168
169`~:R'
170
171    print a number as an ordinal English number.
172
173`~R'
174
175    print a number as a cardinal English number.
176
177`~P'
178
179    Plural.
180
181   `~@P'
182
183         prints `y' and `ies'.
184
185   `~:P'
186
187         as `~P but jumps 1 argument backward.'
188
189   `~:@P'
190
191         as `~@P but jumps 1 argument backward.'
192
193`~C'
194
195    Character.
196
197   `~@C'
198
199         prints a character as the reader can understand it (i.e. `#\' prefixing).
200
201   `~:C'
202
203         prints a character as emacs does (eg. `^C' for ASCII 03).
204
205`~F'
206
207    Fixed-format floating-point (prints a flonum like MMM.NNN).
208
209   `~WIDTH,DIGITS,SCALE,OVERFLOWCHAR,PADCHARF'
210
211   `~@F'
212         If the number is positive a plus sign is printed.
213
214`~E'
215
216    Exponential floating-point (prints a flonum like MMM.NNN`E'EE).
217
218   `~WIDTH,DIGITS,EXPONENTDIGITS,SCALE,OVERFLOWCHAR,PADCHAR,EXPONENTCHARE'
219
220   `~@E'
221
222         If the number is positive a plus sign is printed.
223
224`~G'
225
226    General floating-point (prints a flonum either fixed or exponential).
227
228   `~WIDTH,DIGITS,EXPONENTDIGITS,SCALE,OVERFLOWCHAR,PADCHAR,EXPONENTCHARG'
229
230   `~@G'
231
232         If the number is positive a plus sign is printed.
233
234`~$'
235
236    Dollars floating-point (prints a flonum in fixed with signs separated).
237
238   `~DIGITS,SCALE,WIDTH,PADCHAR$'
239
240   `~@$'
241
242         If the number is positive a plus sign is printed.
243
244   `~:@$'
245
246         A sign is always printed and appears before the padding.
247
248   `~:$'
249
250         The sign appears before the padding.
251
252`~%'
253
254    Newline.
255
256   `~N%'
257
258         print N newlines.
259
260`~&'
261
262    print newline if not at the beginning of the output line.
263
264   `~N&'
265
266         prints `~&' and then N-1 newlines.
267
268`~|'
269
270    Page Separator.
271
272   `~N|'
273
274         print N page separators.
275
276`~~'
277
278    Tilde.
279
280   `~N~'
281
282         print N tildes.
283
284`~'<newline>
285
286    Continuation Line.
287
288   `~:'<newline>
289
290         newline is ignored, white space left.
291
292   `~@'<newline>
293
294         newline is left, white space ignored.
295
296`~T'
297
298    Tabulation.
299
300   `~@T'
301
302         relative tabulation.
303
304   `~COLNUM,COLINCT'
305
306         full tabulation.
307
308`~?'
309
310    Indirection (expects indirect arguments as a list).
311
312   `~@?'
313
314         extracts indirect arguments from format arguments.
315
316`~(STR~)'
317
318    Case conversion (converts by `string-downcase').
319
320   `~:(STR~)'
321
322         converts by `string-capitalize'.
323
324   `~@(STR~)'
325
326         converts by `string-capitalize-first'.
327
328   `~:@(STR~)'
329
330         converts by `string-upcase'.
331
332`~*'
333
334    Argument Jumping (jumps 1 argument forward).
335
336   `~N*'
337
338         jumps N arguments forward.
339
340   `~:*'
341
342         jumps 1 argument backward.
343
344   `~N:*'
345
346         jumps N arguments backward.
347
348   `~@*'
349
350         jumps to the 0th argument.
351
352   `~N@*'
353
354         jumps to the Nth argument (beginning from 0)
355
356`~[STR0~;STR1~;...~;STRN~]'
357
358    Conditional Expression (numerical clause conditional).
359
360   `~N['
361
362         take argument from N.
363
364   `~@['
365
366         true test conditional.
367
368   `~:['
369
370         if-else-then conditional.
371
372   `~;'
373
374         clause separator.
375
376   `~:;'
377
378         default clause follows.
379
380`~{STR~}'
381
382    Iteration (args come from the next argument (a list)). Iteration
383    bounding is controlled by configuration variables
384    format:iteration-bounded and format:max-iterations. With both variables
385    default, a maximum of 100 iterations will be performed.
386
387   `~N{'
388
389         at most N iterations.
390
391   `~:{'
392
393         args from next arg (a list of lists).
394
395   `~@{'
396
397         args from the rest of arguments.
398
399   `~:@{'
400
401         args from the rest args (lists).
402
403`~^'
404    Up and out.
405
406   `~N^'
407
408         aborts if N = 0
409
410   `~N,M^'
411
412         aborts if N = M
413
414   `~N,M,K^'
415
416         aborts if N <= M <= K
417
418Not Implemented CL Format Control Directives
419............................................
420
421`~:A'
422
423    print `#f' as an empty list (see below).
424
425`~:S'
426
427    print `#f' as an empty list (see below).
428
429`~<~>'
430
431    Justification.
432
433`~:^'
434
435    (sorry I don't understand its semantics completely)
436
437Extended, Replaced and Additional Control Directives
438....................................................
439
440`~MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHD'
441
442`~MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHX'
443
444`~MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHO'
445
446`~MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHB'
447
448`~N,MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHR'
449
450    COMMAWIDTH is the number of characters between two comma
451    characters.
452
453`~I'
454    print a R4RS complex number as `~F~@Fi' with passed parameters for
455    `~F'.
456
457`~Y'
458
459    Pretty print formatting of an argument for scheme code lists.
460
461`~K'
462
463    Same as `~?.'
464
465`~!'
466
467    Flushes the output if format DESTINATION is a port.
468
469`~_'
470
471    Print a `#\space' character
472
473   `~N_'
474         print N `#\space' characters.
475
476`~/'
477
478    Print a `#\tab' character
479
480   `~N/'
481         print N `#\tab' characters.
482
483`~NC'
484
485    Takes N as an integer representation for a character. No arguments
486    are consumed. N is converted to a character by `integer->char'.  N
487    must be a positive decimal number.
488
489`~:S'
490
491    Print out readproof.  Prints out internal objects represented as
492    `#<...>' as strings `"#<...>"' so that the format output can always
493    be processed by `read'.
494
495`~:A'
496
497    Print out readproof.  Prints out internal objects represented as
498    `#<...>' as strings `"#<...>"' so that the format output can always
499    be processed by `read'.
500
501`~Q'
502
503    Prints information and a copyright notice on the format
504    implementation.
505
506   `~:Q'
507         prints format version.
508
509`~F, ~E, ~G, ~$'
510
511    May also print number strings, i.e. passing a number as a string and
512    format it accordingly.
513
514Configuration Variables
515-----------------------
516
517Format has some configuration variables. There should be no modification
518necessary for the default configuration. If modification is desired the
519variable should be set after the format code is loaded.
520
521format:floats
522
523    System has floating-point numbers. (default #t)
524
525format:complex-numbers
526
527    System has complex numbers. (default #f)
528
529format:fn-max
530
531    Maximum number of number digits. (default 200)
532
533format:format:en-max
534
535    Maximum number of exponent digits. (default 10)
536
537format:expch
538
539    The character prefixing the exponent value in ~E printing.
540    (default #\E)
541
542format:radix-pref
543
544    Does number->string add a radix prefix? (default <detects upon load>)
545
546format:symbol-case-conv
547
548    Symbols are converted by symbol->string so the case type of the
549    printed symbols is implementation dependent.
550    format:symbol-case-conv is a one arg closure which is either #f (no
551    conversion), string-upcase, string-downcase or string-capitalize.
552    (default #f)
553
554format:iobj-case-conv
555
556    As format:symbol-case-conv but applies for the representation of
557    implementation internal objects. (default #f)
558
559format:iteration-bounded
560
561    When #t, a ~{...~} control will iterate no more than the number of
562    times specified by format:max-iterations regardless of the number
563    of iterations implied by modifiers and arguments. When #f, a
564    ~{...~} control will iterate the number of times implied by
565    modifiers and arguments, unless termination is forced by language
566    or system limitations. (default #t)
567
568format:max-iterations
569
570    The maximum number of iterations performed by a ~{...~} control.
571    Has effect only when format:iteration-bounded is #t. (default 100)
572
573format:unprocessed-arguments-error?
574
575    Are superfluous arguments treated as an error. (default #f)
576
577
578== Notes
579
580A modular and more robust implementation is available in the [[format-modular.html|format-modular]] extension.
581
582
583== License
584
585This code is in the public domain
586
587
588=== Author
589
590Dirk Lutzebaeck, maintained by felix winkelmann and Kon Lovett
591
592
593=== Version history
594
595; 3.2.1 : fix missing dependency on srfi-13
596; 3.2.0 : ported to CHICKEN 5 by Vasillij Schneidermann
597; 3.1.6 : Fix for ticket #630
598; 3.1.5 :
599; 3.1.4 : Ported to CHICKEN 4
600; 3.1.3 : Removed 'format feature & added srfi-13
601; 3.1.2 : Exports
602; 3.1 : Eggification
603
Note: See TracBrowser for help on using the repository browser.