guile18/doc/sources/format.texi

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