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

Last change on this file since 37635 was 37635, checked in by wasamasa, 7 weeks ago

Fix markup

File size: 11.9 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
39 Format Specification (Format version 3.1)
40 -----------------------------------------
41 
42 Please consult a Common LISP format reference manual for a detailed
43 description of the format string syntax.
44 
45 This implementation supports directive parameters and modifiers (`:' and `@'
46 characters). Multiple parameters must be separated by a comma (`,').
47 Parameters can be numerical parameters (positive or negative), character
48 parameters (prefixed by a quote character (`''), variable parameters (`v'),
49 number of rest arguments parameter (`#'), empty and default parameters.
50 Directive characters are case independent.
51 
52 The general form of a directive is:
53 
54 DIRECTIVE ::= ~{DIRECTIVE-PARAMETER,}[:][@]DIRECTIVE-CHARACTER
55 
56 DIRECTIVE-PARAMETER ::= [ [-|+]{0-9}+ | 'CHARACTER | v | # ]
57 
58 Implemented CL Format Control Directives
59 ........................................
60 
61 Documentation syntax: Uppercase characters represent the corresponding control
62 directive characters. Lowercase characters represent control directive
63 parameter 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 
418 Not 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 
437 Extended, 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 
514 Configuration Variables
515 -----------------------
516 
517 Format has some configuration variables. There should be no modification
518 necessary for the default configuration. If modification is desired the
519 variable should be set after the format code is loaded.
520 
521 format:floats
522 
523     System has floating-point numbers. (default #t)
524 
525 format:complex-numbers
526 
527     System has complex numbers. (default #f)
528 
529 format:fn-max
530 
531     Maximum number of number digits. (default 200)
532 
533 format:format:en-max
534 
535     Maximum number of exponent digits. (default 10)
536 
537 format:expch
538 
539     The character prefixing the exponent value in ~E printing.
540     (default #\E)
541 
542 format:radix-pref
543 
544     Does number->string add a radix prefix? (default <detects upon load>)
545 
546 format: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 
554 format:iobj-case-conv
555 
556     As format:symbol-case-conv but applies for the representation of
557     implementation internal objects. (default #f)
558 
559 format: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 
568 format: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 
573 format: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.