#
Chapter 34
`pretty.ss`: Pretty Printing

To load: `(require (lib "pretty.ss"))`

`(pretty-display``` `v``` [`port`]`)` P R O C E D U R E

Same as `pretty-print`, but `v` is printed like `display` instead of like `write`.

`(pretty-print``` `v``` [`port`]`)` P R O C E D U R E

Pretty-prints the value `v` using the same printed form as `write`, but with newlines and whitespace inserted to avoid lines longer than `(pretty-print-columns)`, as controlled by `(pretty-print-current-style-table)`. The printed form ends in a newline unless the `pretty-print-columns` parameter is set to `'infinity`.

If `port` is provided, `v` is printed into `port`; otherwise, `v` is printed to the current output port.

In addition to the parameters defined by the `pretty` library, `pretty-print` conforms to the `print-graph`, `print-struct`, and `print-vector-length` parameters.

The pretty printer also detects structures that have the `prop:custom-write` property (see section 11.2.10 in PLT MzScheme: Language Manual) and it 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).

`(pretty-print-current-style-table``` `style-table``` [`procedure`]`)`

Parameter that holds a table of style mappings. See `pretty-print-extend-style-table`.

`(pretty-print-columns``` [`width`]`)` P R O C E D U R E

Parameter that sets the default width for pretty printing to `width` and returns void. If no `width` argument is provided, the current value is returned instead.

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.

`(pretty-print-depth``` [`depth`]`)` P R O C E D U R E

Parameter that controls the default depth for recursive pretty printing. Printing to `depth` means that elements nested more deeply than `depth` are replaced with ``...''; in particular, a depth of 0 indicates that only simple values are printed. A depth of `#f` (the default) allows printing to arbitrary depths.

`(pretty-print-exact-as-decimal``` [`as-decimal?`]`)` P R O C E D U R E

Parameter that determines how exact non-integers are printed. If the parameter's value is `#t`, then an exact non-integer with a decimal representation is printed as a decimal number instead of a fraction. The initial value is `#f`.

`(pretty-print-extend-style-table``` `style-table symbol-list like-symbol-list``)` P R O C E D U R E

Creates a new style table by extending an existing `style-table`, so that the style mapping for each symbol of `like-symbol-list` in the original table is used for the corresponding symbol of `symbol-list` in the new table. The `symbol-list` and `like-symbol-list` lists must have the same length. The `style-table` argument can be `#f`, in which case with default mappings are used for the original table (see below).

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

`(pretty-print-handler``` `v``)` P R O C E D U R E

Pretty-prints `v` if `v` is not void or prints nothing otherwise. Pass this procedure to `current-print` to install the pretty printer into the `read`-`eval`-`print` loop.

`(pretty-print-newline``` `port width-k``)` P R O C E D U R E

Calls the procedure associated with the `pretty-print-print-line` parameter to print a newline to `port`, if `port` is the output port that is redirected to the original output port for printing, otherwise a plain newline is printed to `port`. The `width-k` argument should be the target column width, typically obtained from `pretty-print-columns`.

`(pretty-print-print-hook``` [`proc`]`)` P R O C E D U R E

Parameter that sets the print hook for pretty-printing to `proc`. If `proc` is not provided, the current hook is returned.

The print hook is applied to a value for printing when the sizing hook (see `pretty-print-size-hook`) returns an integer size for the value.

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

`(pretty-print-print-line``` [`proc`]`)` P R O C E D U R E

Parameter that sets a procedure for printing the newline separator between lines of a pretty-printed value. The `proc` procedure is called with four arguments: a new line number, an output port, the old line's length, and the number of destination columns. The return value from `proc` is the number of extra characters it printed at the beginning of the new line.

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 for a value is 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`.

`(pretty-print-show-inexactness``` [`explicit?`]`)` P R O C E D U R E

Parameter that determines how inexact numbers are printed. If the parameter's value is `#t`, then inexact numbers are always printed with a leading `#i`. The initial value is `#f`.

`(pretty-print-style-table?``` `v``)` P R O C E D U R E

Returns `#t` if `v` is a style table,`#f` otherwise.

`(pretty-print-post-print-hook``` [`proc`]`)` P R O C E D U R E

Parameter that sets a hook procedure to be called just after an object is printed. The hook receives two arguments: the object and the output port. The port is the one supplied to `pretty-print` or `pretty-display` (or the current output port).

`(pretty-print-pre-print-hook``` [`proc`]`)` P R O C E D U R E

Parameter that sets a hook procedure to be called just before an object is printed. The hook receives two arguments: the object and the output port. The port is the one supplied to `pretty-print` or `pretty-display` (or the current output port).

`(pretty-print-size-hook``` [`hook`]`)` P R O C E D U R E

Parameter that sets the sizing hook for pretty-printing to `hook`. If `hook` is not provided, the current hook is returned.

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.

`(pretty-print-.-symbol-without-bars``` [`bool`]`)` P R O C E D U R E

Parameter that controls the printing of the symbol whose print name is just a period. If set to a true value, it is printed as only the period. If set to a false value, it is printed as a period with vertical bars surrounding it.

`(pretty-printing``` [`on?`]`)` P R O C E D U R E

Parameter that is set to `#t` when the pretty printer calls a custom-write procedure (see section 11.2.10 in PLT MzScheme: Language Manual) for output.

When pretty printer calls a custom-write procedure merely to detect cycles, it sets this parameter to `#f`.

`(make-tentative-pretty-print-output-port``` `output-port width-k overflow-thunk``)` P R O C E D U R E

Produces an output port that is suitable for recursive pretty printing without actually producing output. Use such a port to tentatively print when proper output depends on the size of recursive prints. Determine the size of the tentative print using `port-count-lines`.

The `output-port` 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-k` argument should be a target column width, usually obtained from `pretty-print-column-count`, possibly decremented to leave room for a terminator. The `overflow-thunk` procedure is called if more than `width-k` items are printed to the port; it can escape from the recursive print through a continuation as a short cut, 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.

`(tentative-pretty-print-port-transfer``` `tentative-output-port output-port``)` P R O C E D U R E

Causes the data written to `tentative-output-port` to be transferred as if written to `output-port`. The `tentative-output-port` argument should be a port produced by `make-tentative-pretty-print-output-port`, and `output-port` should be either a pretty-printing port (provided to a custom-write procedure) or another tentative output port.

`(tentative-pretty-print-port-cancel``` `tentative-output-port``)` P R O C E D U R E

Cancels the content of `tentative-output-port`, which was produced by `make-tentative-pretty-print-output-port`. The main effect of canceling is that graph-reference definitions are undone, so that a future print of a graph-referenced object includes the defining `#`n`=`.