4 * Format Specification::
7 @node Format Interface, Format Specification, Format, Format
8 @subsection Format Interface
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.
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
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}.
36 Note: @code{format} is not reentrant, i.e. only one @code{format}-call
37 may be executed at a time.
41 @node Format Specification, , Format Interface, Format
42 @subsection Format Specification (Format version 3.0)
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
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
58 @var{directive} ::= ~@{@var{directive-parameter},@}[:][@@]@var{directive-character}
61 @var{directive-parameter} ::= [ [-|+]@{0-9@}+ | '@var{character} | v | # ]
64 @subsubsection Implemented CL Format Control Directives
66 Documentation syntax: Uppercase characters represent the corresponding
67 control directive characters. Lowercase characters represent control
68 directive parameter descriptions.
72 Any (print as @code{display} does).
76 @item @code{~@var{mincol},@var{colinc},@var{minpad},@var{padchar}A}
80 S-expression (print as @code{write} does).
84 @item @code{~@var{mincol},@var{colinc},@var{minpad},@var{padchar}S}
91 print number sign always.
93 print comma separated.
94 @item @code{~@var{mincol},@var{padchar},@var{commachar}D}
101 print number sign always.
103 print comma separated.
104 @item @code{~@var{mincol},@var{padchar},@var{commachar}X}
111 print number sign always.
113 print comma separated.
114 @item @code{~@var{mincol},@var{padchar},@var{commachar}O}
121 print number sign always.
123 print comma separated.
124 @item @code{~@var{mincol},@var{padchar},@var{commachar}B}
127 @item @code{~@var{n}R}
130 @item @code{~@var{n},@var{mincol},@var{padchar},@var{commachar}R}
134 print a number as a Roman numeral.
136 print a number as an ``old fashioned'' Roman numeral.
138 print a number as an ordinal English number.
140 print a number as a cardinal English number.
145 prints @code{y} and @code{ies}.
147 as @code{~P but jumps 1 argument backward.}
149 as @code{~@@P but jumps 1 argument backward.}
155 prints a character as the reader can understand it (i.e. @code{#\} prefixing).
157 prints a character as emacs does (eg. @code{^C} for ASCII 03).
160 Fixed-format floating-point (prints a flonum like @var{mmm.nnn}).
162 @item @code{~@var{width},@var{digits},@var{scale},@var{overflowchar},@var{padchar}F}
164 If the number is positive a plus sign is printed.
167 Exponential floating-point (prints a flonum like @var{mmm.nnn}@code{E}@var{ee}).
169 @item @code{~@var{width},@var{digits},@var{exponentdigits},@var{scale},@var{overflowchar},@var{padchar},@var{exponentchar}E}
171 If the number is positive a plus sign is printed.
174 General floating-point (prints a flonum either fixed or exponential).
176 @item @code{~@var{width},@var{digits},@var{exponentdigits},@var{scale},@var{overflowchar},@var{padchar},@var{exponentchar}G}
178 If the number is positive a plus sign is printed.
181 Dollars floating-point (prints a flonum in fixed with signs separated).
183 @item @code{~@var{digits},@var{scale},@var{width},@var{padchar}$}
185 If the number is positive a plus sign is printed.
187 A sign is always printed and appears before the padding.
189 The sign appears before the padding.
194 @item @code{~@var{n}%}
195 print @var{n} newlines.
198 print newline if not at the beginning of the output line.
200 @item @code{~@var{n}&}
201 prints @code{~&} and then @var{n-1} newlines.
206 @item @code{~@var{n}|}
207 print @var{n} page separators.
212 @item @code{~@var{n}~}
213 print @var{n} tildes.
215 @item @code{~}<newline>
218 @item @code{~:}<newline>
219 newline is ignored, white space left.
220 @item @code{~@@}<newline>
221 newline is left, white space ignored.
228 @item @code{~@var{colnum,colinc}T}
232 Indirection (expects indirect arguments as a list).
235 extracts indirect arguments from format arguments.
237 @item @code{~(@var{str}~)}
238 Case conversion (converts by @code{string-downcase}).
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}.
248 Argument Jumping (jumps 1 argument forward).
250 @item @code{~@var{n}*}
251 jumps @var{n} arguments forward.
253 jumps 1 argument backward.
254 @item @code{~@var{n}:*}
255 jumps @var{n} arguments backward.
257 jumps to the 0th argument.
258 @item @code{~@var{n}@@*}
259 jumps to the @var{n}th argument (beginning from 0)
261 @item @code{~[@var{str0}~;@var{str1}~;...~;@var{strn}~]}
262 Conditional Expression (numerical clause conditional).
264 @item @code{~@var{n}[}
265 take argument from @var{n}.
267 true test conditional.
269 if-else-then conditional.
273 default clause follows.
275 @item @code{~@{@var{str}~@}}
276 Iteration (args come from the next argument (a list)).
278 @item @code{~@var{n}@{}
279 at most @var{n} iterations.
281 args from next arg (a list of lists).
283 args from the rest of arguments.
285 args from the rest args (lists).
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}
300 @subsubsection Not Implemented CL Format Control Directives
304 print @code{#f} as an empty list (see below).
306 print @code{#f} as an empty list (see below).
310 (sorry I don't understand its semantics completely)
314 @subsubsection Extended, Replaced and Additional Control Directives
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.
327 print an R5RS complex number as @code{~F~@@Fi} with passed parameters for
330 Pretty print formatting of an argument for scheme code lists.
334 Flushes the output if format @var{destination} is a port.
336 Print a @code{#\space} character
338 @item @code{~@var{n}_}
339 print @var{n} @code{#\space} characters.
342 Print a @code{#\tab} character
344 @item @code{~@var{n}/}
345 print @var{n} @code{#\tab} characters.
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
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}.
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}.
361 Prints information and a copyright notice on the format implementation.
364 prints format version.
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.
372 @subsubsection Configuration Variables
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.
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})
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})
394 @item @var{format:expch}
395 The character prefixing the exponent value in @code{~E} printing. (default
400 @subsubsection Compatibility With Other Format Implementations
403 @item SLIB format 2.x:
404 See @file{format.doc}.
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.
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
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
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
433 This implementation of format is solely useful in the SLIB context
434 because it requires other components provided by SLIB.@refill