| 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 |