9.8 Printables
Any value is printable. Implementing the Printable interface customizes the way that instances of a class print.
An interface that a class can implement (publicly or privately) to customize the way its objects print. In the simplest case, an implementation of the interface’s describe method returns a string to use as an object’s printed form. More generally, a describe method implementation returns a description of how to print a value, where the description is created using functions like PrintDesc.concat, PrintDesc.newline, and PrintDesc.or.
The Printable interface has one method:
describe(mode, recur) —
returns a PrintDesc given a mode, which is either #'text or #'expr, and a recur function, which accepts a value, an optional ~mode like Printable.describe (unlike Printable.describe, the ~mode defaults to #'expr, which is generally desirable when printing subcomponents), and an optional ~as argument; the recur function is specific to a particular overall print action so that it can handle cycles and graph references. The optional ~as argument for recur can be #'print or #'super, and the default is #'print. When ~as is #'super, the supplied object to print must be the same object whose describe method is called; in that case, instead of immediately recurring back to describe, the default printing implementation is used. An exception is thrown for #'super mode for any other object to print.
function | ||||
Generates a pretty-printing description for v. The print function composes Printable.describe with Printable.render.
function | |||||
|
The optional column argument indicates the current column for output, in case pd contains a PrintDesc.align description that needs to update indentation based on the current column.
annotation | |
A string or byte string prints as its content. Other PrintDesc values describe concatenations, line breaks, indentation, and formatting options.
function | ||
| ||
| ||
function | ||
| ||
function | ||
| ||
function | ||
| ||
function | ||
| ||
function | ||
|
PrintDesc.concat concatenates the pds in order, with nothing in between.
"a", "b",
))
ab
PrintDesc.newline prints a newline plus indentation, where indentation is determined by the surrounding description.
"a", PrintDesc.newline(),
"b",
))
a
b
PrintDesc.nest increases the current indentation by n while printing pd.
"a",
2,
"b",
)),
))
a
b
PrintDesc.align sets the current indentation (independent of the current indentation) to the current output column while printing pd.
"a",
"b", PrintDesc.newline(),
"c",
)),
))
ab
c
PrintDesc.or offers two printing alternatives. Either pd1 or pd2 will be printed, depending on choices made by a pretty-printer configuration and as constrained by PrintDesc.flat constraints.
"a", "; ", "b",
),
"a", PrintDesc.newline(),
"b",
)))
a; b
PrintDesc.flat prints the same as pd, but only if that is possible without any newlines. If all possible ways of rendering pd involve a newline, printing fails. A PrintDesc.flat constraint it particularly useful in one branch of a PrintDesc.or to constrain a description received by recursive description.
> def sub = PrintDesc.or(
"a", "; ", "b",
),
"a", PrintDesc.newline(),
"b",
))
"f(", PrintDesc.flat(sub), ")",
),
"f(",
2,
sub,
)),
")",
)))
f(a; b)
function | |||||
| |||||
| |||||
function | |||||
The single-line variant constrains pre_pd, head, and any member of elements other than the last one to be printed as a single-line, too. If one of those has no single-line option, then the combined single-line variant will not be used (which can cause the description to be unprintable).
"Posn(",
["x", "y"],
")"
))
Posn(x, y)
"begin",
"one", PrintDesc.newline(),
"two",
)))
begin:
one
two
enumeration | |||||
function | ||||||
|
Prints v using Racket printing when the output port supports “special” output, otherwise prints as the given alt_pd. For the purposes of pretty printing, v is counted as using length columns. The mode argument indicates which Racket printing function is used.
context parameter | ||
|
context parameter | ||
|
context parameter | ||
|
context parameter | ||
|
Sharing is reported by a #n= prefix on a printed value, and then #n# with the same number n is used for later occurrences of the value.
The same notation is used to show cyclic data, which is shown independent of the value of the Printable.current_graph parameter.