4 The Printing Modules

4.2 Print functions

The Print module offers two functions for users to call to print objects, print and print-to-string.

print

Function

print object stream #key level length circle? pretty? => ()

: Prints object to stream according to the print request formed by the keyword arguments. A first call to print creates a printing stream to represent the print request, and recursive calls to print on this printing stream process the keyword arguments differently (see below). There are inspection functions for querying the print request. When print actually prints an object, it calls print-object. Though the inspection functions for querying the print request allow you to inspect any parameter of the print request, print-object methods should only need to call print-length. All other aspects of the print request are handled by print. There is one exception which is described in Section 4.3.
: The level keyword controls how deep into a nested data structure to print. The value #f indicates that there is no limit. The default, *print-level*, has no effect on recursive calls to print. Recursive calls to print may change the value of print-level explicitly, but print always uses a value to ensure the print request formed by the first call to print is never exceeded. For example, if a first call to print set the level to 5, and while at a depth of 3, a recursive call specified a level of 4, the recursive call would only descend 2 more levels, not 4.
: The length keyword controls how many elements of a sequence to print before printing ellipsis notation (...). The value #f indicates that there is no limit. The print-length control can be interpreted loosely by some print-object methods to control how many elements of any kind of object to print; for example, the default <object> method might regard print-length to determine how many slot-name/value pairs to print. The default, *print-length*, has no effect on recursive calls to print. Recursive calls to print may change the value of print-length explicitly, but they may only decrease the value, never increase it.
: The circle? keyword indicates whether printing should check all subcomponent references to make sure the printing process does not infinitely recurse through a data structure. Circular printing also tags objects that occur more than once when they are first printed, and later occurrences are printed as a reference to the previously emitted tag. The default, *print-circle?*, has no effect on recursive calls to print. If print-circle? is already #t, then it remains #t throughout all recursive calls. If print-circle? is #f, then recursive calls to print can change the value to #t; however, when printing exits the dynamic scope of the call that changed the value to #t, the value reverts back to #f. If the original call to print specifies circle? as #f, and dynamically distinct recursive calls turn circular printing on and off, all output generated while circular printing was on shares the same tagging space; that is, if #1# is printed twice, once from each of two distinct recursive calls to print, then each #1# is guaranteed to signify the same == object.
: The pretty? keyword indicates whether printing should attempt to insert line breaks and indentation to format objects according to how programmers tend to find it easier to read data. The default, *print-pretty?*, has no effect on recursive calls to print. If print-pretty? is already #t, then it remains #t throughout all recursive calls. If print-pretty? is #f, then recursive calls to print can change the value to #t; however, when printing exits the dynamic scope of the call that changed the value to #t, the value reverts back to #f.

print-to-string

Function

print-to-string object #key level length circle? pretty? => result

: Calls print to produce output according to the print request formed by the keyword arguments and returns the result as a string. The level, length, circle?, and pretty? keywords are as for print.

print-object

Open generic function

print-object object stream => ()

: Prints an object to a stream. You should extend the ability of print to print various objects by adding methods to the print-object function. When print actually prints an object, it calls print-object. You should never call print-object directly.

The Print module exports the following variables which provide default values for calls to the print function. Their values are implementation-dependent.

*print-level*

Variable

: This is an <integer> that controls how deeply into a nested expression to print.

*print-length*

Variable

: This is an <integer> that controls how many elements at a given level to print.

*print-circle?*

Variable

: A boolean that controls whether or not to print recursively. When *print-circle* is #f, printing proceeds recursively and attempts to print a circular structure results in failure to terminate.

*print-pretty*

Variable

: A boolean that controls whether or not print does pretty-printing.