Kawa, the Java-based Scheme system

Node:Format, Previous:Ports, Up:Input-Output

### Formatted Output (Common-Lisp-style)

format destination fmt . arguments | Function

An almost complete implementation of Common LISP format description according to the CL reference book Common LISP from Guy L. Steele, Digital Press. Backward compatible to most of the available Scheme format implementations. Returns `#t`, `#f` or a string; has side effect of printing according to fmt. If destination is `#t`, the output is to the current output port and `#!void` is returned. If destination is `#f`, a formatted string is returned as the result of the call. If destination is a string, destination is regarded as the format string; fmt is then the first argument and the output is returned as a string. If destination is a number, the output is to the current error port if available by the implementation. Otherwise destination must be an output port and `#!void` is returned. fmt must be a string or an instance of `gnu.text.MessageFormat` or `java.text.MessageFormat`. If fmt is a string, it is parsed as if by `parse-format`.

parse-format format-string | Function

Parses `format-string`, which is a string of the form of a Common LISP format description. Returns an instance of `gnu.text.ReportFormat`, which can be passed to the `format` function.

A format string passed to `format` or `parse-format` consists of format directives (that start with `~`), and regular characters (that are written directly to the destination). Most of the Common Lisp (and Slib) format directives are implemented. Neither justification, nor pretty-printing are supported yet.

Plus of course, we need documentation for `format`!

#### Implemented CL Format Control Directives

Documentation syntax: Uppercase characters represent the corresponding control directive characters. Lowercase characters represent control directive parameter descriptions.

`~A`
  Any (print as `display` does).
  `~@A`
    left pad.
  `~`mincol`,`colinc`,`minpad`,`padchar`A`
    full padding.
`~S`
  S-expression (print as `write` does).
  `~@S`
    left pad.
  `~`mincol`,`colinc`,`minpad`,`padchar`S`
    full padding.
`~C`
  Character.
  `~@C`
    prints a character as the reader can understand it (i.e. `#\` prefixing).
  `~:C`
    prints a character as emacs does (eg. `^C` for ASCII 03).

#### Formatting Integers

`~D`
  Decimal.
  `~@D`
    print number sign always.
  `~:D`
    print comma separated.
  `~`mincol`,`padchar`,`commachar`,`commawidth`D`
    padding.
`~X`
  Hexadecimal.
  `~@X`
    print number sign always.
  `~:X`
    print comma separated.
  `~`mincol`,`padchar`,`commachar`,`commawidth`X`
    padding.
`~O`
  Octal.
  `~@O`
    print number sign always.
  `~:O`
    print comma separated.
  `~`mincol`,`padchar`,`commachar`,`commawidth`O`
    padding.
`~B`
  Binary.
  `~@B`
    print number sign always.
  `~:B`
    print comma separated.
  `~`mincol`,`padchar`,`commachar`,`commawidth`B`
    padding.
`~`n`R`
  Radix n.
  `~`n`,`mincol`,`padchar`,`commachar`,`commawidth`R`
    padding.
`~@R`
  print a number as a Roman numeral.
`~:@R`
  print a number as an "old fashioned" Roman numeral.
`~:R`
  print a number as an ordinal English number.
`~R`
  print a number as a cardinal English number.
`~P`
  Plural.
  `~@P`
    prints `y` and `ies`.
  `~:P`
    as `~P but jumps 1 argument backward.`
  `~:@P`
    as `~@P but jumps 1 argument backward.`

commawidth is the number of characters between two comma characters.

#### Formatting floating-point (real) numbers

`~F`
  Fixed-format floating-point (prints a flonum like mmm.nnn).
  `~`width`,`digits`,`scale`,`overflowchar`,`padchar`F`
  `~@F`
    If the number is positive a plus sign is printed.

`~E`
  Exponential floating-point (prints a flonum like mmm.nnn`E`ee)
  `~`width`,`digits`,`exponentdigits`,`scale`,`overflowchar`,`padchar`,`exponentchar`E`
  `~@E`
    If the number is positive a plus sign is printed.

`~G`
  General floating-point (prints a flonum either fixed or exponential).
  `~`width`,`digits`,`exponentdigits`,`scale`,`overflowchar`,`padchar`,`exponentchar`G`
  `~@G`
    If the number is positive a plus sign is printed.
  A slight difference from Common Lisp: If the number is printed in fixed form and the fraction is zero, then a zero digit is printed for the fraction, if allowed by the width and digits is unspecified.

`~$`
  Dollars floating-point (prints a flonum in fixed with signs separated).
  `~`digits`,`scale`,`width`,`padchar`$`
  `~@$`
    If the number is positive a plus sign is printed.
  `~:@$`
    A sign is always printed and appears before the padding.
  `~:$`
    The sign appears before the padding.

#### Miscellaneous formatting operators

`~%`
  Newline.
  `~`n`%`
    print n newlines.
`~&`
  print newline if not at the beginning of the output line.
  `~`n`&`
    prints `~&` and then n-1 newlines.
`~|`
  Page Separator.
  `~`n`|`
    print n page separators.
`~~`
  Tilde.
  `~`n`~`
    print n tildes.
`~`<newline>
  Continuation Line.
  `~:`<newline>
    newline is ignored, white space left.
  `~@`<newline>
    newline is left, white space ignored.
`~T`
  Tabulation.
  `~@T`
    relative tabulation.
  `~`colnum`,`colinc`T`
    full tabulation.
`~?`
  Indirection (expects indirect arguments as a list).
  `~@?`
    extracts indirect arguments from format arguments.
`~(`str`~)`
  Case conversion (converts by `string-downcase`).
  `~:(`str`~)`
    converts by `string-capitalize`.
  `~@(`str`~)`
    converts by `string-capitalize-first`.
  `~:@(`str`~)`
    converts by `string-upcase`.
`~*`
  Argument Jumping (jumps 1 argument forward).
  `~`n`*`
    jumps n arguments forward.
  `~:*`
    jumps 1 argument backward.
  `~`n`:*`
    jumps n arguments backward.
  `~@*`
    jumps to the 0th argument.
  `~`n`@*`
    jumps to the nth argument (beginning from 0)
`~[`str0`~;`str1`~;...~;`strn`~]`
  Conditional Expression (numerical clause conditional).
  `~`n`[`
    take argument from n.
  `~@[`
    true test conditional.
  `~:[`
    if-else-then conditional.
  `~;`
    clause separator.
  `~:;`
    default clause follows.
`~{`str`~}`
  Iteration (args come from the next argument (a list)).
  `~`n`{`
    at most n iterations.
  `~:{`
    args from next arg (a list of lists).
  `~@{`
    args from the rest of arguments.
  `~:@{`
    args from the rest args (lists).
`~^`
  Up and out.
  `~`n`^`
    aborts if n = 0
  `~`n`,`m`^`
    aborts if n = m
  `~`n`,`m`,`k`^`
    aborts if n <= m <= k

#### Not Implemented CL Format Control Directives

`~:A`
  print `#f` as an empty list (see below).
`~:S`
  print `#f` as an empty list (see below).
`~<~>`
  Justification.
`~:^`

##### Extended, Replaced and Additional Control Directives

These are not necesasrily implemented in Kawa!

`~I`
  print a R4RS complex number as `~F~@Fi` with passed parameters for `~F`.
`~Y`
  Pretty print formatting of an argument for scheme code lists.
`~K`
  Same as `~?.`
`~!`
  Flushes the output if format destination is a port.
`~_`
  Print a `#\space` character
  `~`n`_`
    print n `#\space` characters.
`~`n`C`
  Takes n as an integer representation for a character. No arguments are consumed. n is converted to a character by `integer->char`. n must be a positive decimal number.
`~:S`
  Print out readproof. Prints out internal objects represented as `#<...>` as strings `"#<...>"` so that the format output can always be processed by `read`.
`~:A`
  Print out readproof. Prints out internal objects represented as `#<...>` as strings `"#<...>"` so that the format output can always be processed by `read`.
`~F, ~E, ~G, ~$`
  may also print number strings, i.e. passing a number as a string and format it accordingly.