2  Installation

For Gauche run "make gauche && make install-gauche". The modules are installed as text.fmt, text.fmt.c, text.fmt.color and text.fmt.unicode.

For MzScheme you can download and install the latest fmt.plt yourself from:

(fmt <output-dest> <format> ...)

where <output-dest> has the same semantics as with format - specifically it can be an output-port, #t to indicate the current output port, or #f to accumulate output into a string.

Each <format> should be a format closure as discussed below. As a convenience, non-procedure arguments are also allowed and are formatted similar to display, so that

(fmt #f "Result: " res nl)

would return the string "Result: 42n", assuming RES is bound to 42.

nl is the newline format combinator.

(dsp <obj>)

(wrt <obj>)

(num <n> [<radix> <precision> <sign> <comma> <comma-sep> <decimal-sep>])

A <sign> of #t indicates to output a plus sign (+) for positive integers. However, if <sign> is a character, it means to wrap the number with that character and its mirror opposite if the number is negative. For example, #\( prints negative numbers in parenthesis, financial style: -3.14 => (3.14)

<comma> is an integer specifying the number of digits between commas. Variable length, as in subcontinental-style, is not yet supported.

<comma-sep> is the character to use for commas, defaulting to #\,.

<decimal-sep> is the character to use for decimals, defaulting to #\., or to #\, (European style) if <comma-sep> is already #\..

These parameters may seem unwieldy, but they can also take their defaults from state variables, described below.

(num/comma <n> [<base> <precision> <sign>])

(fmt #f (num/comma 1234567))

=> "1,234,567"

(num/si <n> [<base> <suffix>])

The <suffix> argument is appended only if an abbreviation is used.

(fmt #f (num/si 608))

=> "608"

(fmt #f (num/si 3986))

=> "3.9Ki"

(fmt #f (num/si 3986 1000 "B"))

=> "4kB"

nl

fl

(space-to <column>)

(tab-to [<tab-width>])

fmt-null

(cat <format> ...)

(apply-cat <list>)

(fmt-join <formatter> <list> [<sep>])

(fmt #f (fmt-join dsp '(a b c) ", "))

=> "a, b, c"

(fmt-join/prefix <formatter> <list> [<sep>])

(fmt-join/suffix <formatter> <list> [<sep>])

=> "/usr/local/bin"

As fmt-join, but inserts <sep> before/after every element.

(fmt-join/last <formatter> <last-formatter> <list> [<sep>])

(fmt-join/dot <formatter> <dot-formatter> <list> [<sep>])

(pad <width> <format> ...)

(pad/left <width> <format> ...)

(pad/both <width> <format> ...)

pad does not accumulate any intermediate data.

Note these are column-oriented padders, so won't necessarily work with multi-line output (padding doesn't seem a likely operation for multi-line output).

(trim <width> <format> ...)

(trim/left <width> <format> ...)

(trim/both <width> <format> ...)

If a truncation ellipse is set (e.g. with the ellipses procedure below), then when any truncation occurs trim and trim/left will append and prepend the ellipse, respectively. trim/both will both prepend and append. The length of the ellipse will be considered when truncating the original string, so that the total width will never be longer than <width>.

(fmt #f (ellipses "..." (trim 5 "abcde")))

=> "abcde"

(fmt #f (ellipses "..." (trim 5 "abcdef")))

=> "ab..."

(trim/length <width> <format> ...)

(fit <width> <format> ...)

(fit/left <width> <format> ...)

(fit/both <width> <format> ...)

(fmt-let <name> <value> <format> ...)

(fmt-bind <name> <value> <format> ...)

A convenience control structure can be useful in combination with these states:

(fmt-if <pred> <pass> [<fail>])

Many of the previously mentioned combinators have behavior which can be altered with state variables. Although fmt-let and fmt-bind could be used, these common variables have shortcuts:

(radix <k> <format> ...)

(fix <k> <format> ...)

(fmt #f (radix 16 '(70 80 90)))

will return the string "(#x46 #x50 #x5a)". Note that read/write invariance is essential, so for dsp, wrt and pretty the radix prefix is always included when not decimal. Use num if you want to format numbers in alternate bases without this prefix. For example,

(fmt #f (radix 16 "(" (fmt-join num '(70 80 90) " ") ")"))

would return "(46 50 5a)", the same output as above without the "#x" radix prefix.

Note that fixed point formatting supports arbitrary precision in implementations with exact non-integral rationals. When trying to print inexact numbers more than the machine precision you will typically get results like

(fmt #f (fix 30 #i2/3))

=> "0.666666666666666600000000000000"

but with an exact rational it will give you as many digits as you request:

(fmt #f (fix 30 2/3))

=> "0.666666666666666666666666666667"

(decimal-align <k> <format> ...)

  (define (print-angles x)
     (fmt-join num (list x (sin x) (cos x) (tan x)) " "))

  (fmt #t (decimal-align 5 (fix 3 (fmt-join/suffix print-angles (iota 5) nl))))

would output

   0.000    0.000    1.000    0.000
   1.000    0.842    0.540    1.557
   2.000    0.909   -0.416   -2.185
   3.000    0.141   -0.990   -0.142
   4.000   -0.757   -0.654    1.158

(comma-char <k> <format> ...)

(decimal-char <k> <format> ...)

(pad-char <k> <format> ...)

  (define (print-table-of-contents alist)
    (define (print-line x)
      (cat (car x) (space-to 72) (pad/left 3 (cdr x))))
    (fmt #t (pad-char #\. (fmt-join/suffix print-line alist nl))))

  (print-table-of-contents
   '(("An Unexpected Party" . 29)
     ("Roast Mutton" . 60)
     ("A Short Rest" . 87)
     ("Over Hill and Under Hill" . 100)
     ("Riddles in the Dark" . 115)))

would output

  An Unexpected Party.....................................................29
  Roast Mutton............................................................60
  A Short Rest............................................................87
  Over Hill and Under Hill...............................................100
  Riddles in the Dark....................................................115

(ellipse <ell> <format> ...)

(with-width <width> <format> ...)

(columnar <column> ...)

(fmt #t (columnar (dsp "abcndefn") (dsp "123n456n")))

outputs

     abc     123
     def     456

assuming a 16-char width (the left side gets half the width, or 8 spaces, and is left aligned). Note that we explicitly use DSP instead of the strings directly. This is because columnar treats raw strings as literals inserted into the given location on every line, to be used as borders, for example:

  (fmt #t (columnar "/* " (dsp "abcndefn")
                    " | " (dsp "123n456n")
                    " */"))

would output

  /* abc | 123 */
  /* def | 456 */

You may also prefix any column with any of the symbols 'left, 'right or 'center to control the justification. The symbol 'infinite can be used to indicate the column generates an infinite stream of output.

You can further prefix any column with a width modifier. Any positive integer is treated as a fixed width, ignoring the available width. Any real number between 0 and 1 indicates a fraction of the available width (after subtracting out any fixed widths). Columns with unspecified width divide up the remaining width evenly.

Note that columnar builds its output incrementally, interleaving calls to the generators until each has produced a line, then concatenating that line together and outputting it. This is important because as noted above, some columns may produce an infinite stream of output, and in general you may want to format data larger than can fit into memory. Thus columnar would be suitable for line numbering a file of arbitrary size, or implementing the Unix yes(1) command, etc.

As an implementation detail, columnar uses first-class continuations to interleave the column output. The core fmt itself has no knowledge of or special support for columnar, which could complicate and potentially slow down simpler fmt operations. This is a testament to the power of call/cc - it can be used to implement coroutines or arbitrary control structures even where they were not planned for.

(tabular <column> ...)

(fmt #t (tabular "|" (dsp "a\\nbc\\ndef\\n") "|" (dsp "123n45n6n") "|"))

outputs

|a  |123|
|bc |45 |
|def|6  |

This makes it easier to generate tables without knowing widths in advance. However, because it requires generating the entire output in advance to determine the correct column widths, tabular cannot format a table larger than would fit in memory.

(fmt-columns <column> ...)

(<line-formatter> <line-generator> [<infinite?>])

where <line-generator> is the column generator as above, and the <line-formatter> is how each line is formatted. Raw concatenation of each line is performed, without any spacing or width adjustment. <infinite?>, if true, indicates this generator produces an infinite number of lines and termination should be determined without it.

(wrap-lines <format> ...)

(justify <format> ...)

  (define func
    '(define (fold kons knil ls)
       (let lp ((ls ls) (acc knil))
         (if (null? ls) acc (lp (cdr ls) (kons (car ls) acc))))))

  (define doc
    (string-append
      "The fundamental list iterator.  Applies KONS to each element "
      "of LS and the result of the previous application, beginning "
      "with KNIL.  With KONS as CONS and KNIL as '(), equivalent to REVERSE."))

  (fmt #t (columnar (pretty func) " ; " (justify doc)))

outputs

  (define (fold kons knil ls)          ; The   fundamental   list   iterator.
    (let lp ((ls ls) (acc knil))       ; Applies  KONS  to  each  element  of
      (if (null? ls)                   ; LS  and  the  result of the previous
          acc                          ; application,  beginning  with  KNIL.
          (lp (cdr ls)                 ; With  KONS  as CONS and KNIL as '(),
              (kons (car ls) acc)))))  ; equivalent to REVERSE.

(fmt-file <pathname>)

(line-numbers [<start>])

The Unix nl(1) utility could be implemented as:

  (fmt #t (columnar 6 'right 'infinite (line-numbers)
                    " " (fmt-file "read-line.scm")))

     1 
     2 (define (read-line . o)
     3   (let ((port (if (pair? o) (car o) (current-input-port))))
     4     (let lp ((res '()))
     5       (let ((c (read-char port)))
     6         (if (or (eof-object? c) (eqv? c #\newline))
     7             (list->string (reverse res))
     8             (lp (cons c res)))))))

6.1  C Formatting Basics

  (fmt #t (c-switch 'y
            (c-case 1 (c= 'x 1))
            (cpp-ifdef 'H_TWO (c-case 2 (c= 'x 4)))
            (c-default (c= 'x 5))))

  switch (y) {
      case 1:
          x = 1;
          break;

  #ifdef H_TWO
      case 2:
          x = 4;
          break;
  #endif /* H_TWO */
      default:
          x = 5;
          break;
  }

Macros can be handled with cpp-define, which knows to wrap individual variable references in parenthesis:

(fmt #t (cpp-define '(min x y) (c-if (c< 'x 'y) 'x 'y)))

  #define min(x, y) (((x) < (y)) ? (x) : (y))

As with all C formatters, the CPP output is pretty printed as needed, and if it wraps over several lines the lines are terminated with a backslash.

To write a C header file that is included at most once, you can wrap the entire body in cpp-wrap-header:

  (fmt #t (cpp-wrap-header "FOO_H"
            (c-extern (c-prototype 'int 'foo '()))))

  #ifndef FOO_H
  #define FOO_H

  extern int foo ();

  #endif /* ! FOO_H */

'indent-space

'switch-indent-space

'newline-before-brace?

'braceless-bodies?

'non-spaced-ops?

'no-wrap?

The C formatters also respect the 'radix and 'precision settings.

(c-if <condition> <pass> [<fail> [<condition2> <pass2> ...]])

(c-for <init> <condition> <update> <body> ...)

(c-while <condition> <body> ...)

(c-fun <type> <name> <params> <body> ...)

(c-prototype <type> <name> <params>)

(cpp-include <file>)

(fmt #f (cpp-include 'stdio.h))

=> "#include <stdio.h>n"

(fmt #f (cpp-include "config.h"))

=> "#include "config.h"n"

(cpp-define <macro> [<value>])

(fmt #t (cpp-define '(eprintf . args) '(fprintf stderr args)))

  #define eprintf(...) (fprintf(stderr, __VA_ARGS__))

(cpp-if <condition> <pass> [<fail> ...])

(cpp-ifdef <condition> <pass> [<fail> ...])

(cpp-ifndef <condition> <pass> [<fail> ...])

(cpp-elif <condition> <pass> [<fail> ...])

(cpp-else <body> ...)

(cpp-line <num> [<file>])

(cpp-pragma <args> ...)

(cpp-error <args> ...)

(cpp-warning <args> ...)

(cpp-stringify <expr>)

(cpp-sym-cat <args> ...)

(cpp-wrap-header <name> <body> ...)

Operators:

c++ c-- c+ c- c* c/ c% c& c^ c~ c! c&& c<< c>> c== c!=
c< c> c<= c>= c= c+= c-= c*= c/= c%= c&= c^= c<<= c>>=
c++/post c--/post c-or c-bit-or c-bit-or=

Typically a type is just a symbol such as 'char or 'int. You can wrap types with modifiers such as c-const, but as a convenience you can just use a list such as in '(const unsignedchar *). You can also nest these lists, so the previous example is equivalent to '(* (const (unsigned char))).

Pointers may be written as '(%pointer <type>) for readability - %pointer is exactly equivalent to * in types.

Unamed structs, classes, unions and enums may be used directly as types, using their respective keywords at the head of a list.

Two special types are the %array type and function pointer type. An array is written:

(%array <type> [<size>])

where <type> is any other type (including another array or function pointer), and <size>, if given, will print the array size. For example:

(c-var '(%array (unsigned long) SIZE) 'table '#(1 2 3 4))

unsigned long table[SIZE] = {1, 2, 3, 4};

A function pointer is written:

(%fun <return-type> (<param-types> ...))

For example:

(c-typedef '(%fun double (double double int)) 'f)

typedef double (*f)(double, double, int);

Wherever a type is expected but not given, the value of the 'default-type formatting state variable is used. By default this is just 'int.

Type declarations work uniformly for variables and parameters, as well for casts and typedefs.

Rather than building formatting closures by hand, it can be more convenient to just build a normal s-expression and ask for it to be formatted as C code. This can be thought of as a simple Scheme->C compiler without any runtime support.

In a s-expression, strings and characters are printed as C strings and characters, booleans are printed as 0 or 1, symbols are displayed as-is, and numbers are printed as C numbers (using the current formatting radix if specified). Vectors are printed as comma-separated lists wrapped in braces, which can be used for initializing arrays or structs.

A list indicates a C expression or statement. Any of the existing C keywords can be used to pretty-print the expression as described with the c-keyword formatters above. Thus, the example above

(fmt #t (c-if (c-if 1 2 3) 4 5))

could also be written

(fmt #t (c-expr '(if (if 1 2 3) 4 5)))

C constructs that are dependent on the underlying syntax and have no keyword are written with a % prefix (%fun, %var, %pointer, %array, %cast), including C preprocessor constructs (%include, %define, %pragma, %error, %warning, %if, %ifdef, %ifndef, %elif). Labels are written as (: <label-name>). You can write a sequence as (%begin <expr> ...).

For example, the following definition of the fibonacci sequence, which apart from the return type of #f looks like a Lisp definition:

(fmt #t (c-expr '(%fun #f fib (n) (if (<= n 1) 1 (+ (fib (- n 1)) (fib (- n 2)))))))

prints the working C definition:

int fib (int n) {
    if (n <= 1) {
        return 1;
    } else {
        return fib((n - 1)) + fib((n - 2));
    }
}

(js-expr x)

Currently expressions will all be terminated with a semi-colon, but that will be made optional in a later release.

(js-function [<name>] (<params>) <body> ...)

(js-var <name> [<init-value>])

(js-comment <formatter> ...)

  (fmt-red <formatter> ...)
  (fmt-blue <formatter> ...)
  (fmt-green <formatter> ...)
  (fmt-cyan <formatter> ...)
  (fmt-yellow <formatter> ...)
  (fmt-magenta <formatter> ...)
  (fmt-white <formatter> ...)
  (fmt-black <formatter> ...)
  (fmt-bold <formatter> ...)
  (fmt-underline <formatter> ...)

and more generally

(fmt-color <color> <formatter> ...)

where color can be a symbol name or #xRRGGBB numeric value. Outputs the formatters colored with ANSI escapes. In addition

(fmt-in-html <formatter> ...)

can be used to mark the format state as being inside HTML, which the above color formats will understand and output HTML <span> tags with the appropriate style colors, instead of ANSI escapes.

It also recognizes and ignores ANSI escapes, in particular useful if you want to combine this with the fmt-color utilities.

If you don't have an aggressively optimizing compiler, you can easily achieve large speedups on common cases with CL-style compiler macros.

format	fmt
~a	dsp
~c	dsp
~s	wrt/unshared
~w	wrt
~y	pretty
~x	(radix 16 ...) or (num <n> 16)
~o	(radix 8 ...) or (num <n> 8)
~b	(radix 2 ...) or (num <n> 2)
~f	(fix <digits> ...) or (num <n> <radix> <digits>)
~%	nl
~&	fl
~[...~]	normal if or fmt-if (delayed test)
~{...~}	(fmt-join ... <list> [<sep>])