12.6 Pretty Printing

In addition to the parameters defined in this section, pretty-print conforms to the print-graph, print-struct, print-hash-table, print-vector-length, print-box, and print-as-expression parameters.

The pretty printer detects structures that have the prop:custom-write property and calls the corresponding custom-write procedure. The custom-write procedure can check the parameter pretty-printing to cooperate with the pretty-printer. Recursive printing to the port automatically uses pretty printing, but if the structure has multiple recursively printed sub-expressions, a custom-write procedure may need to cooperate more to insert explicit newlines. Use port-next-location to determine the current output column, use pretty-print-columns to determine the target printing width, and use pretty-print-newline to insert a newline (so that the function in the pretty-print-print-line parameter can be called appropriately). Use make-tentative-pretty-print-output-port to obtain a port for tentative recursive prints (e.g., to check the length of the output).

The optional argument columns argument is used to parameterize pretty-print-columns.

12.6.1 Basic Pretty-Print Options

If the display width is 'infinity, then pretty-printed output is never broken into lines, and a newline is not added to the end of the output.

12.6.2 Per-Symbol Special Printing

See also pretty-print-remap-stylable.

The style mapping for a symbol controls the way that whitespace is inserted when printing a list that starts with the symbol. In the absence of any mapping, when a list is broken across multiple lines, each element of the list is printed on its own line, each with the same indentation.

The default style mapping includes mappings for the following symbols, so that the output follows popular code-formatting rules:

'lambda 'case-lambda

'define 'define-macro 'define-syntax

'let 'letrec 'let*

'let-syntax 'letrec-syntax

'let-values 'letrec-values 'let*-values

'let-syntaxes 'letrec-syntaxes

'begin 'begin0 'do

'if 'set! 'set!-values

'unless 'when

'cond 'case 'and 'or

'module

'syntax-rules 'syntax-case 'letrec-syntaxes+values

'import 'export 'link

'require 'require-for-syntax 'require-for-template 'provide

'public 'private 'override 'rename 'inherit 'field 'init

'shared 'send 'class 'instantiate 'make-object

This procedure is called with each sub-expression that appears as the first element in a sequence. If it returns a symbol, the style table is used, as if that symbol were at the head of the sequence. If it returns #f, the style table is treated normally. Similarly, when determining whether to abbreviate reader macros, this parameter is consulted.

12.6.3 Line-Output Hook

The proc procedure is called before any characters are printed with 0 as the line number and 0 as the old line length; proc is called after the last character of a value has been printed with #f as the line number and with the length of the last line. Whenever the pretty-printer starts a new line, proc is called with the new line’s number (where the first new line is numbered 1) and the just-finished line’s length. The destination-columns argument to proc is always the total width of the destination printing area, or 'infinity if pretty-printed values are not broken into lines.

The default proc procedure prints a newline whenever the line number is not 0 and the column count is not 'infinity, always returning 0. A custom proc procedure can be used to print extra text before each line of pretty-printed output; the number of characters printed before each line should be returned by proc so that the next line break can be chosen correctly.

The destination port supplied to proc is generally not the port supplied to pretty-print or pretty-display (or the current output port), but output to this port is ultimately redirected to the port supplied to pretty-print or pretty-display.

12.6.4 Value Output Hook

The sizing hook is applied to each value to be printed. If the hook returns #f, then printing is handled internally by the pretty-printer. Otherwise, the value should be an integer specifying the length of the printed value in characters; the print hook will be called to actually print the value (see pretty-print-print-hook).

The sizing hook receives three arguments. The first argument is the value to print. The second argument is a boolean: #t for printing like display and #f for printing like write. The third argument is the destination port; the port is the one supplied to pretty-print or pretty-display (or the current output port). The sizing hook may be applied to a single value multiple times during pretty-printing.

The print hook receives three arguments. The first argument is the value to print. The second argument is a boolean: #t for printing like display and #f for printing like write. The third argument is the destination port; this port is generally not the port supplied to pretty-print or pretty-display (or the current output port), but output to this port is ultimately redirected to the port supplied to pretty-print or pretty-display.

12.6.5 Additional Custom-Output Support

The out argument should be a pretty-printing port, such as the one supplied to a custom-write procedure when pretty-printing is set to true, or another tentative output port. The width argument should be a target column width, usually obtained from pretty-print-columns, possibly decremented to leave room for a terminator. The overflow-thunk procedure is called if more than width items are printed to the port or if a newline is printed to the port via pretty-print-newline; it can escape from the recursive print through a continuation as a shortcut, but overflow-thunk can also return, in which case it is called every time afterward that additional output is written to the port.

After tentative printing, either accept the result with tentative-pretty-print-port-transfer or reject it with tentative-pretty-print-port-cancel. Failure to accept or cancel properly interferes with graph-structure printing, calls to hook procedures, etc. Explicitly cancel the tentative print even when overflow-thunk escapes from a recursive print.