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.

(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 3 (cdr x))))
    (fmt #t (pad-char #\. (fmt-join 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, 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.

(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>])

  (fmt #t (columnar 4 '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)))))))
   9

6.1  C Formatting Basics

There are two approaches to using the C formatting extensions - procedural and sexp-oriented. In the procedural interface, C operators are made available as formatters with a "c-" prefix, literals are converted to their C equivalents and symbols are output as-is (you're responsible for making sure they are valid C identifiers). Indentation is handled automatically.

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

outputs

  if (1) {
      2;
  } else {
      3;
  }

In addition, the formatter knows when you're in an expression and when you're in a statement, and behaves accordingly, so that

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

outputs

  if (1 ? 2 : 3) {
      4;
  } else {
      5;
  }

Similary, c-begin, used for sequencing, will separate with semi-colons in a statement and commas in an expression.

Moreover, we also keep track of the final expression in a function and insert returns for you:

(fmt #t (c-fun 'int 'foo '() (c-if (c-if 1 2 3) 4 5)))

outputs

  int foo () {
      if (1 ? 2 : 3) {
          return 4;
      } else {
          return 5;
      }
  }

although it knows that void functions don't return.

Switch statements insert breaks by default if they don't return:

  (fmt #t (c-switch 'y
            (c-case 1 (c+= 'x 1))
            (c-default (c+= 'x 2))))

  switch (y) {
      case 1:
          x += 1;
          break;
      default:
          x += 2;
          break;
  }

though you can explicitly fallthrough if you want:

  (fmt #t (c-switch 'y
            (c-case/fallthrough 1 (c+= 'x 1))
            (c-default (c+= 'x 2))))

  switch (y) {
      case 1:
          x += 1;
      default:
          x += 2;
          break;
  }

Operators are available with just a "c" prefix, e.g. c+, c-, c*, c/, etc. c++ is a prefix operator, c++/post is postfix. ||, | and |= are written as c-or, c-bit-or and c-bit-or= respectively.

Function applications are written with c-apply. Other control structures such as c-for and c-while work as expected. The full list is in the procedure index below.

When a C formatter encounters an object it doesn't know how to write (including lists and records), it outputs them according to the format state's current 'gen variable. This allows you to specify generators for your own types, e.g. if you are using your own AST records in a compiler.

If the 'gen variable isn't set it defaults to the c-expr/sexp procedure, which formats an s-expression as if it were C code. Thus instead of c-apply you can just use a list. The full API is available via normal s-expressions - formatters that aren't keywords in C are prefixed with a % or otherwise made invalid C identifiers so that they can't be confused with function application.

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

Types are just symbols, or lists of symbols such as '(const char *).

Also accessed as %fun and %prototype at the head of a list.

(c-begin <expr> ...)

(c-switch <clause> ...)

(c-case <values> <body> ...)

(c-case/fallthrough <values> <body> ...)

(c-default <body> ...)

(c-label <name>)

(c-goto <name>)

(c-return [<result>])

c-break

c-continue

(c-const <expr>)

(c-static <expr>)

(c-volatile <expr>)

(c-restrict <expr>)

(c-register <expr>)

(c-auto <expr>)

(c-inline <expr>)

(c-extern <expr>)

(c-extern/C <body> ...)

(c-var <type> <name> [<init-value>])

(c-cast <type> <expr>)

(c-typedef <type> <new-name> ...)

(c-struct [<name>] <field-list> [<attributes>])

(c-union [<name>] <field-list> [<attributes>])

(c-class [<name>] <field-list> [<attributes>])

(c-attribute <values> ...)

  (fmt #f (c-struct 'employee
                      '((short age)
                        ((char *) name)
                        ((struct (year month day)) dob))
                      (c-attribute 'packed)))

  struct employee {
      short age;
      char* name;
      struct {
          int year;
          int month;
          int day;
      } dob;
  } __attribute__ ((packed));

(c-enum [<name>] <enum-list>)

(c-comment <formatter> ...)

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

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

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