4 The Printing Modules

4.3 Pretty printing

When writing print-object methods, you can ignore whether pretty printing is in effect. If you write your print-object method using pretty printing functions, then when pretty printing is in effect, the output is pretty printed. When pretty printing is not in effect, your method produces output as though you had not written it to use pretty printing. All print-object methods that are written to do pretty printing must call the pretty printing functions within the dynamic scope of a call to pprint-logical-block; otherwise, the pretty printing functions are no-ops.

The following interfaces are exported from the pprint module:

*default-line-length*

Variable

: An integer that controls the line length used by the pretty printer to determine how much output will fit on a single line. The value must be an integer. The default is 80.

*print-miser-width*

Variable

: An integer that controls miser mode. Whenever a logical block (see pprint-logical-block) begins in a column of output that is greater than *default-line-length* - *print-miser-width*, then pretty printing is in miser mode. The value must be an integer or #f (the default). #f indicates that the pretty printer should never enter miser mode.

pprint-logical-block

Function

pprint-logical-block stream #key prefix per-line-prefix body suffix column => ()

: Groups printing into a logical block. The logical block provides boundaries for new levels of indentation, affects #"linear" newlines, and so on. The prefix keyword is a string to print at the beginning of the logical block. The blocks indentation is automatically set to be one character position greater than the column in which prefix ends. Alternatively, per-line-prefix is a string to print on every line of the logical block. The pprint-logical-block function signals an error if it is called with both prefix and per-line-prefix supplied as non-#f.
: The suffix keyword is a string to print at the end of the logical block.
: The column keyword advises the pretty printer as to the current column of the output stream (the default is zero). This keyword may be ignored entirely by some methods, and it may be ignored in some cases by methods that can better determine the stream's current output column.
: The body keyword must be a function that can take one argument, and this argument is a stream. The function specified by body should use the stream argument passed to it; the body function should not close over the stream argument to pprint-logical-block. The function pprint-logical-block wraps stream with a pretty printing stream when stream is any other kind of stream. If stream is already a pretty printing stream, then the body function is called on stream.
: All print-object methods that are written to do pretty printing must call the other pretty printing functions within the dynamic scope of a call to pprint-logical-block; otherwise, the pretty printing functions are no-ops.

pprint-newline

Function

pprint-newline kind stream => ()

: Announces a conditional newline to the pretty printer. The pretty printer emits a newline depending on the kind and the state of the pretty printer's current line buffer. The kind argument can be one of the following:
#"fill": Emit a newline if the current section of output does not fit on one line.
#"linear": Emit a newline if any #"linear" newline in the current section needs to be emitted. That is, if a current section of output cannot fit on one line, and any one of the #"linear" newlines in the section needs to be emitted, then emit them all.
#"miser": Emit a newline as if it were a #"linear" newline, but only when miser mode is in effect. Miser style is in effect when a logical block starts past a particular column of output.
#"mandatory": Emit a newline always. Establish that any containing sections cannot be printed on a single line so that #"linear" and #"miser" newlines will be emitted as appropriate.

pprint-indent

Function

pprint-indent relative-to n stream => ()

: Specifies the indentation to use within the current logical block. When relative-to is #"block", then pprint-indent sets the indentation to the column of the first character of the logical block plus n. When relative-to is #"current", then pprint-indent sets the indentation to the current column plus n. In both cases, n is a <fixed-integer>.

pprint-tab

Function

pprint-tab kind colnum colinc stream => ()

kind: One of #"line", #"line-relative", #"section", #"section-relative".
colnum: An instance of <fixed-integer>.
colinc: An instance of <fixed-integer>.
stream: An instance of <stream>.
: Announces a tab to the pretty printer. Colnum and colinc have meaning based on the value of kind, which can be one of the following:
#"line": Tab to output column colnum. If the output is already at or beyond colnum, then add colinc to colnum until printing can continue at a column beyond the end of the output already on the line.
#"line-relative"
: Output colnum spaces. Then output enough spaces to tab to a column that is a multiple of colinc from the beginning of the line.
#"section": This is similar to #"line", but column counting is relative to the beginning of the current section rather than the beginning of the line.
#"section-relative"
: This is similar to #"line-relative", but column counting is relative to the beginning of the current section rather than the beginning of the line.
: In all cases, colnum and colinc are instances of <fixed-integer>.