Commit | Line | Data |
---|---|---|
8da8776b JB |
1 | |
2 | @menu | |
3 | * Format Interface:: | |
4 | * Format Specification:: | |
5 | @end menu | |
6 | ||
7 | @node Format Interface, Format Specification, Format, Format | |
8 | @subsection Format Interface | |
9 | ||
10 | @defun format destination format-string . arguments | |
11 | An almost complete implementation of Common LISP format description | |
12 | according to the CL reference book @cite{Common LISP} from Guy L. | |
13 | Steele, Digital Press. Backward compatible to most of the available | |
14 | Scheme format implementations. | |
15 | ||
16 | Returns @code{#t}, @code{#f} or a string; has side effect of printing | |
17 | according to @var{format-string}. If @var{destination} is @code{#t}, | |
18 | the output is to the current output port and @code{#t} is returned. If | |
19 | @var{destination} is @code{#f}, a formatted string is returned as the | |
20 | result of the call. NEW: If @var{destination} is a string, | |
21 | @var{destination} is regarded as the format string; @var{format-string} is | |
22 | then the first argument and the output is returned as a string. If | |
23 | @var{destination} is a number, the output is to the current error port | |
24 | if available by the implementation. Otherwise @var{destination} must be | |
25 | an output port and @code{#t} is returned.@refill | |
26 | ||
27 | @var{format-string} must be a string. In case of a formatting error | |
28 | format returns @code{#f} and prints a message on the current output or | |
29 | error port. Characters are output as if the string were output by the | |
30 | @code{display} function with the exception of those prefixed by a tilde | |
31 | (~). For a detailed description of the @var{format-string} syntax | |
32 | please consult a Common LISP format reference manual. For a test suite | |
33 | to verify this format implementation load @file{formatst.scm}. Please | |
34 | send bug reports to @code{lutzeb@@cs.tu-berlin.de}. | |
35 | ||
36 | Note: @code{format} is not reentrant, i.e. only one @code{format}-call | |
37 | may be executed at a time. | |
38 | ||
39 | @end defun | |
40 | ||
41 | @node Format Specification, , Format Interface, Format | |
42 | @subsection Format Specification (Format version 3.0) | |
43 | ||
44 | Please consult a Common LISP format reference manual for a detailed | |
45 | description of the format string syntax. For a demonstration of the | |
46 | implemented directives see @file{formatst.scm}.@refill | |
47 | ||
48 | This implementation supports directive parameters and modifiers | |
49 | (@code{:} and @code{@@} characters). Multiple parameters must be | |
50 | separated by a comma (@code{,}). Parameters can be numerical parameters | |
51 | (positive or negative), character parameters (prefixed by a quote | |
52 | character (@code{'}), variable parameters (@code{v}), number of rest | |
53 | arguments parameter (@code{#}), empty and default parameters. Directive | |
54 | characters are case independent. The general form of a directive | |
55 | is:@refill | |
56 | ||
57 | @noindent | |
58 | @var{directive} ::= ~@{@var{directive-parameter},@}[:][@@]@var{directive-character} | |
59 | ||
60 | @noindent | |
61 | @var{directive-parameter} ::= [ [-|+]@{0-9@}+ | '@var{character} | v | # ] | |
62 | ||
63 | ||
64 | @subsubsection Implemented CL Format Control Directives | |
65 | ||
66 | Documentation syntax: Uppercase characters represent the corresponding | |
67 | control directive characters. Lowercase characters represent control | |
68 | directive parameter descriptions. | |
69 | ||
70 | @table @asis | |
71 | @item @code{~A} | |
72 | Any (print as @code{display} does). | |
73 | @table @asis | |
74 | @item @code{~@@A} | |
75 | left pad. | |
76 | @item @code{~@var{mincol},@var{colinc},@var{minpad},@var{padchar}A} | |
77 | full padding. | |
78 | @end table | |
79 | @item @code{~S} | |
80 | S-expression (print as @code{write} does). | |
81 | @table @asis | |
82 | @item @code{~@@S} | |
83 | left pad. | |
84 | @item @code{~@var{mincol},@var{colinc},@var{minpad},@var{padchar}S} | |
85 | full padding. | |
86 | @end table | |
87 | @item @code{~D} | |
88 | Decimal. | |
89 | @table @asis | |
90 | @item @code{~@@D} | |
91 | print number sign always. | |
92 | @item @code{~:D} | |
93 | print comma separated. | |
94 | @item @code{~@var{mincol},@var{padchar},@var{commachar}D} | |
95 | padding. | |
96 | @end table | |
97 | @item @code{~X} | |
98 | Hexadecimal. | |
99 | @table @asis | |
100 | @item @code{~@@X} | |
101 | print number sign always. | |
102 | @item @code{~:X} | |
103 | print comma separated. | |
104 | @item @code{~@var{mincol},@var{padchar},@var{commachar}X} | |
105 | padding. | |
106 | @end table | |
107 | @item @code{~O} | |
108 | Octal. | |
109 | @table @asis | |
110 | @item @code{~@@O} | |
111 | print number sign always. | |
112 | @item @code{~:O} | |
113 | print comma separated. | |
114 | @item @code{~@var{mincol},@var{padchar},@var{commachar}O} | |
115 | padding. | |
116 | @end table | |
117 | @item @code{~B} | |
118 | Binary. | |
119 | @table @asis | |
120 | @item @code{~@@B} | |
121 | print number sign always. | |
122 | @item @code{~:B} | |
123 | print comma separated. | |
124 | @item @code{~@var{mincol},@var{padchar},@var{commachar}B} | |
125 | padding. | |
126 | @end table | |
127 | @item @code{~@var{n}R} | |
128 | Radix @var{n}. | |
129 | @table @asis | |
130 | @item @code{~@var{n},@var{mincol},@var{padchar},@var{commachar}R} | |
131 | padding. | |
132 | @end table | |
133 | @item @code{~@@R} | |
134 | print a number as a Roman numeral. | |
135 | @item @code{~:@@R} | |
136 | print a number as an ``old fashioned'' Roman numeral. | |
137 | @item @code{~:R} | |
138 | print a number as an ordinal English number. | |
139 | @item @code{~:@@R} | |
140 | print a number as a cardinal English number. | |
141 | @item @code{~P} | |
142 | Plural. | |
143 | @table @asis | |
144 | @item @code{~@@P} | |
145 | prints @code{y} and @code{ies}. | |
146 | @item @code{~:P} | |
147 | as @code{~P but jumps 1 argument backward.} | |
148 | @item @code{~:@@P} | |
149 | as @code{~@@P but jumps 1 argument backward.} | |
150 | @end table | |
151 | @item @code{~C} | |
152 | Character. | |
153 | @table @asis | |
154 | @item @code{~@@C} | |
155 | prints a character as the reader can understand it (i.e. @code{#\} prefixing). | |
156 | @item @code{~:C} | |
157 | prints a character as emacs does (eg. @code{^C} for ASCII 03). | |
158 | @end table | |
159 | @item @code{~F} | |
160 | Fixed-format floating-point (prints a flonum like @var{mmm.nnn}). | |
161 | @table @asis | |
162 | @item @code{~@var{width},@var{digits},@var{scale},@var{overflowchar},@var{padchar}F} | |
163 | @item @code{~@@F} | |
164 | If the number is positive a plus sign is printed. | |
165 | @end table | |
166 | @item @code{~E} | |
167 | Exponential floating-point (prints a flonum like @var{mmm.nnn}@code{E}@var{ee}). | |
168 | @table @asis | |
169 | @item @code{~@var{width},@var{digits},@var{exponentdigits},@var{scale},@var{overflowchar},@var{padchar},@var{exponentchar}E} | |
170 | @item @code{~@@E} | |
171 | If the number is positive a plus sign is printed. | |
172 | @end table | |
173 | @item @code{~G} | |
174 | General floating-point (prints a flonum either fixed or exponential). | |
175 | @table @asis | |
176 | @item @code{~@var{width},@var{digits},@var{exponentdigits},@var{scale},@var{overflowchar},@var{padchar},@var{exponentchar}G} | |
177 | @item @code{~@@G} | |
178 | If the number is positive a plus sign is printed. | |
179 | @end table | |
180 | @item @code{~$} | |
181 | Dollars floating-point (prints a flonum in fixed with signs separated). | |
182 | @table @asis | |
183 | @item @code{~@var{digits},@var{scale},@var{width},@var{padchar}$} | |
184 | @item @code{~@@$} | |
185 | If the number is positive a plus sign is printed. | |
186 | @item @code{~:@@$} | |
187 | A sign is always printed and appears before the padding. | |
188 | @item @code{~:$} | |
189 | The sign appears before the padding. | |
190 | @end table | |
191 | @item @code{~%} | |
192 | Newline. | |
193 | @table @asis | |
194 | @item @code{~@var{n}%} | |
195 | print @var{n} newlines. | |
196 | @end table | |
197 | @item @code{~&} | |
198 | print newline if not at the beginning of the output line. | |
199 | @table @asis | |
200 | @item @code{~@var{n}&} | |
201 | prints @code{~&} and then @var{n-1} newlines. | |
202 | @end table | |
203 | @item @code{~|} | |
204 | Page Separator. | |
205 | @table @asis | |
206 | @item @code{~@var{n}|} | |
207 | print @var{n} page separators. | |
208 | @end table | |
209 | @item @code{~~} | |
210 | Tilde. | |
211 | @table @asis | |
212 | @item @code{~@var{n}~} | |
213 | print @var{n} tildes. | |
214 | @end table | |
215 | @item @code{~}<newline> | |
216 | Continuation Line. | |
217 | @table @asis | |
218 | @item @code{~:}<newline> | |
219 | newline is ignored, white space left. | |
220 | @item @code{~@@}<newline> | |
221 | newline is left, white space ignored. | |
222 | @end table | |
223 | @item @code{~T} | |
224 | Tabulation. | |
225 | @table @asis | |
226 | @item @code{~@@T} | |
227 | relative tabulation. | |
228 | @item @code{~@var{colnum,colinc}T} | |
229 | full tabulation. | |
230 | @end table | |
231 | @item @code{~?} | |
232 | Indirection (expects indirect arguments as a list). | |
233 | @table @asis | |
234 | @item @code{~@@?} | |
235 | extracts indirect arguments from format arguments. | |
236 | @end table | |
237 | @item @code{~(@var{str}~)} | |
238 | Case conversion (converts by @code{string-downcase}). | |
239 | @table @asis | |
240 | @item @code{~:(@var{str}~)} | |
241 | converts by @code{string-capitalize}. | |
242 | @item @code{~@@(@var{str}~)} | |
243 | converts by @code{string-capitalize-first}. | |
244 | @item @code{~:@@(@var{str}~)} | |
245 | converts by @code{string-upcase}. | |
246 | @end table | |
247 | @item @code{~*} | |
248 | Argument Jumping (jumps 1 argument forward). | |
249 | @table @asis | |
250 | @item @code{~@var{n}*} | |
251 | jumps @var{n} arguments forward. | |
252 | @item @code{~:*} | |
253 | jumps 1 argument backward. | |
254 | @item @code{~@var{n}:*} | |
255 | jumps @var{n} arguments backward. | |
256 | @item @code{~@@*} | |
257 | jumps to the 0th argument. | |
258 | @item @code{~@var{n}@@*} | |
259 | jumps to the @var{n}th argument (beginning from 0) | |
260 | @end table | |
261 | @item @code{~[@var{str0}~;@var{str1}~;...~;@var{strn}~]} | |
262 | Conditional Expression (numerical clause conditional). | |
263 | @table @asis | |
264 | @item @code{~@var{n}[} | |
265 | take argument from @var{n}. | |
266 | @item @code{~@@[} | |
267 | true test conditional. | |
268 | @item @code{~:[} | |
269 | if-else-then conditional. | |
270 | @item @code{~;} | |
271 | clause separator. | |
272 | @item @code{~:;} | |
273 | default clause follows. | |
274 | @end table | |
275 | @item @code{~@{@var{str}~@}} | |
276 | Iteration (args come from the next argument (a list)). | |
277 | @table @asis | |
278 | @item @code{~@var{n}@{} | |
279 | at most @var{n} iterations. | |
280 | @item @code{~:@{} | |
281 | args from next arg (a list of lists). | |
282 | @item @code{~@@@{} | |
283 | args from the rest of arguments. | |
284 | @item @code{~:@@@{} | |
285 | args from the rest args (lists). | |
286 | @end table | |
287 | @item @code{~^} | |
288 | Up and out. | |
289 | @table @asis | |
290 | @item @code{~@var{n}^} | |
291 | aborts if @var{n} = 0 | |
292 | @item @code{~@var{n},@var{m}^} | |
293 | aborts if @var{n} = @var{m} | |
294 | @item @code{~@var{n},@var{m},@var{k}^} | |
295 | aborts if @var{n} <= @var{m} <= @var{k} | |
296 | @end table | |
297 | @end table | |
298 | ||
299 | ||
300 | @subsubsection Not Implemented CL Format Control Directives | |
301 | ||
302 | @table @asis | |
303 | @item @code{~:A} | |
304 | print @code{#f} as an empty list (see below). | |
305 | @item @code{~:S} | |
306 | print @code{#f} as an empty list (see below). | |
307 | @item @code{~<~>} | |
308 | Justification. | |
309 | @item @code{~:^} | |
310 | (sorry I don't understand its semantics completely) | |
311 | @end table | |
312 | ||
313 | ||
314 | @subsubsection Extended, Replaced and Additional Control Directives | |
315 | ||
316 | @table @asis | |
317 | @item @code{~@var{mincol},@var{padchar},@var{commachar},@var{commawidth}D} | |
318 | @item @code{~@var{mincol},@var{padchar},@var{commachar},@var{commawidth}X} | |
319 | @item @code{~@var{mincol},@var{padchar},@var{commachar},@var{commawidth}O} | |
320 | @item @code{~@var{mincol},@var{padchar},@var{commachar},@var{commawidth}B} | |
321 | @item @code{~@var{n},@var{mincol},@var{padchar},@var{commachar},@var{commawidth}R} | |
322 | @var{commawidth} is the number of characters between two comma characters. | |
323 | @end table | |
324 | ||
325 | @table @asis | |
326 | @item @code{~I} | |
327 | print a R4RS complex number as @code{~F~@@Fi} with passed parameters for | |
328 | @code{~F}. | |
329 | @item @code{~Y} | |
330 | Pretty print formatting of an argument for scheme code lists. | |
331 | @item @code{~K} | |
332 | Same as @code{~?.} | |
333 | @item @code{~!} | |
334 | Flushes the output if format @var{destination} is a port. | |
335 | @item @code{~_} | |
336 | Print a @code{#\space} character | |
337 | @table @asis | |
338 | @item @code{~@var{n}_} | |
339 | print @var{n} @code{#\space} characters. | |
340 | @end table | |
341 | @item @code{~/} | |
342 | Print a @code{#\tab} character | |
343 | @table @asis | |
344 | @item @code{~@var{n}/} | |
345 | print @var{n} @code{#\tab} characters. | |
346 | @end table | |
347 | @item @code{~@var{n}C} | |
348 | Takes @var{n} as an integer representation for a character. No arguments | |
349 | are consumed. @var{n} is converted to a character by | |
350 | @code{integer->char}. @var{n} must be a positive decimal number.@refill | |
351 | @item @code{~:S} | |
352 | Print out readproof. Prints out internal objects represented as | |
353 | @code{#<...>} as strings @code{"#<...>"} so that the format output can always | |
354 | be processed by @code{read}. | |
355 | @refill | |
356 | @item @code{~:A} | |
357 | Print out readproof. Prints out internal objects represented as | |
358 | @code{#<...>} as strings @code{"#<...>"} so that the format output can always | |
359 | be processed by @code{read}. | |
360 | @item @code{~Q} | |
361 | Prints information and a copyright notice on the format implementation. | |
362 | @table @asis | |
363 | @item @code{~:Q} | |
364 | prints format version. | |
365 | @end table | |
366 | @refill | |
367 | @item @code{~F, ~E, ~G, ~$} | |
368 | may also print number strings, i.e. passing a number as a string and | |
369 | format it accordingly. | |
370 | @end table | |
371 | ||
372 | @subsubsection Configuration Variables | |
373 | ||
374 | Format has some configuration variables at the beginning of | |
375 | @file{format.scm} to suit the systems and users needs. There should be | |
376 | no modification necessary for the configuration that comes with SLIB. | |
377 | If modification is desired the variable should be set after the format | |
378 | code is loaded. Format detects automatically if the running scheme | |
379 | system implements floating point numbers and complex numbers. | |
380 | ||
381 | @table @asis | |
382 | ||
383 | @item @var{format:symbol-case-conv} | |
384 | Symbols are converted by @code{symbol->string} so the case type of the | |
385 | printed symbols is implementation dependent. | |
386 | @code{format:symbol-case-conv} is a one arg closure which is either | |
387 | @code{#f} (no conversion), @code{string-upcase}, @code{string-downcase} | |
388 | or @code{string-capitalize}. (default @code{#f}) | |
389 | ||
390 | @item @var{format:iobj-case-conv} | |
391 | As @var{format:symbol-case-conv} but applies for the representation of | |
392 | implementation internal objects. (default @code{#f}) | |
393 | ||
394 | @item @var{format:expch} | |
395 | The character prefixing the exponent value in @code{~E} printing. (default | |
396 | @code{#\E}) | |
397 | ||
398 | @end table | |
399 | ||
400 | @subsubsection Compatibility With Other Format Implementations | |
401 | ||
402 | @table @asis | |
403 | @item SLIB format 2.x: | |
404 | See @file{format.doc}. | |
405 | ||
406 | @item SLIB format 1.4: | |
407 | Downward compatible except for padding support and @code{~A}, @code{~S}, | |
408 | @code{~P}, @code{~X} uppercase printing. SLIB format 1.4 uses C-style | |
409 | @code{printf} padding support which is completely replaced by the CL | |
410 | @code{format} padding style. | |
411 | ||
412 | @item MIT C-Scheme 7.1: | |
413 | Downward compatible except for @code{~}, which is not documented | |
414 | (ignores all characters inside the format string up to a newline | |
415 | character). (7.1 implements @code{~a}, @code{~s}, | |
416 | ~@var{newline}, @code{~~}, @code{~%}, numerical and variable | |
417 | parameters and @code{:/@@} modifiers in the CL sense).@refill | |
418 | ||
419 | @item Elk 1.5/2.0: | |
420 | Downward compatible except for @code{~A} and @code{~S} which print in | |
421 | uppercase. (Elk implements @code{~a}, @code{~s}, @code{~~}, and | |
422 | @code{~%} (no directive parameters or modifiers)).@refill | |
423 | ||
424 | @item Scheme->C 01nov91: | |
425 | Downward compatible except for an optional destination parameter: S2C | |
426 | accepts a format call without a destination which returns a formatted | |
427 | string. This is equivalent to a #f destination in S2C. (S2C implements | |
428 | @code{~a}, @code{~s}, @code{~c}, @code{~%}, and @code{~~} (no directive | |
429 | parameters or modifiers)).@refill | |
430 | ||
431 | @end table | |
432 | ||
433 | This implementation of format is solely useful in the SLIB context | |
434 | because it requires other components provided by SLIB.@refill |