Next: , Previous: Readline Support, Up: Guile Modules

7.9 Pretty Printing

The module (ice-9 pretty-print) provides the procedure pretty-print, which provides nicely formatted output of Scheme objects. This is especially useful for deeply nested or complex data structures, such as lists and vectors.

The module is loaded by entering the following: 

     (use-modules (ice-9 pretty-print))

This makes the procedure pretty-print available. As an example how pretty-print will format the output, see the following: 

     (pretty-print '(define (foo) (lambda (x)
     (cond ((zero? x) #t) ((negative? x) -x) (else
     (if (= x 1) 2 (* x x x)))))))
     -|
     (define (foo)
       (lambda (x)
         (cond ((zero? x) #t)
               ((negative? x) -x)
               (else (if (= x 1) 2 (* x x x))))))
— Scheme Procedure: pretty-print obj [port] [keyword-options]

Print the textual representation of the Scheme object obj to port. port defaults to the current output port, if not given.

The further keyword-options are keywords and parameters as follows,

#:display? flag
If flag is true then print using display. The default is #f which means use write style. (see Writing)
#:per-line-prefix string
Print the given string as a prefix on each line. The default is no prefix.
#:width columns
Print within the given columns. The default is 79.

Also exported by the (ice-9 pretty-print) module is truncated-print, a procedure to print Scheme datums, truncating the output to a certain number of characters. This is useful when you need to present an arbitrary datum to the user, but you only have one line in which to do so. 

     (define exp '(a b #(c d e) f . g))
     (truncated-print exp #:width 10) (newline)
     -| (a b . #)
     (truncated-print exp #:width 15) (newline)
     -| (a b # f . g)
     (truncated-print exp #:width 18) (newline)
     -| (a b #(c ...) . #)
     (truncated-print exp #:width 20) (newline)
     -| (a b #(c d e) f . g)
     (truncated-print "The quick brown fox" #:width 20) (newline)
     -| "The quick brown..."
     (truncated-print (current-module) #:width 20) (newline)
     -| #<directory (gui...>

truncated-print will not output a trailing newline. If an expression does not fit in the given width, it will be truncated – possibly ellipsized1, or in the worst case, displayed as #.

— Scheme Procedure: truncated-print obj [port] [keyword-options]

Print obj, truncating the output, if necessary, to make it fit into width characters. By default, x will be printed using write, though that behavior can be overriden via the display? keyword argument.

The default behaviour is to print depth-first, meaning that the entire remaining width will be available to each sub-expressoin of x – e.g., if x is a vector, each member of x. One can attempt to “ration” the available width, trying to allocate it equally to each sub-expression, via the breadth-first? keyword argument.

The further keyword-options are keywords and parameters as follows,

#:display? flag
If flag is true then print using display. The default is #f which means use write style. (see Writing)
#:width columns
Print within the given columns. The default is 79.
#:breadth-first? flag
If flag is true, then allocate the available width breadth-first among elements of a compound data structure (list, vector, pair, etc.). The default is #f which means that any element is allowed to consume all of the available width.

Footnotes

[1] On Unicode-capable ports, the ellipsis is represented by character `HORIZONTAL ELLIPSIS' (U+2026), otherwise it is represented by three dots.