Print Module

The Print module provides ways to print objects. It also provides printing properties (depth, circular, etc), and inspection of those properties.

Prints an object on a stream

Synopsis

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

Parameters

object	An instance of <object>.
stream	An instance of <stream>.
level:	An instance of <integer-or-false-or-not-supplied>. Holds the maximum depth to which the user wants recursive printing to go. Defaults to $not-supplied.
length:	An instance of <integer-or-false-or-not-supplied>. Holds the maximum number of elements the user wants a sequence to be printed. This does not apply to some sequences, such as strings. Defaults to $not-supplied.
circle?:	An instance of <boolean-or-not-supplied>. Defines print behavior when printing a circular list Defaults to $not-supplied.
pretty?:	An instance of <boolean-or-not-supplied>. Whether the user wants pretty printing. Defaults to $not-supplied.

Return Values

None.

Description

Prints object to stream according to the print request formed by the keyed 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 keyed arguments differently (see below). There are inspection functions for querying the print request (see their descriptions below). 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 the PPrint module (pretty-printing).

Level controls how deep into a nested data structure to print. The value #f indicates that there is no limit. The default, *default-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.

Length 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, *default-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.

Circle? 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, *default-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 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.

Pretty? 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, *default-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 to #f.

The default way to print objects

Synopsis

print-object (object, stream) => ()

Parameters

object	An instance of <object>.
stream	An instance of <stream>.

Return Values

None.

Description

Users extend print's ability to print various objects by adding methods to the print-object function. When print actually prints an object, it calls print-object. Users should never call print-object directly.

Provides the printed object representation for print and for the "%=" format directive (see the Section called Format Directives in Chapter 5). Default print-object methods exist for instances of <object>, <character>, <string>, <list>, <vector>, <sequence>, <array>, <table>, <range>, <function>, <singleton>, <limited-integer>, <union>, <symbol>, <general-integer>, <integer>, <ratio>, <single-float>, <double-float>, <extended-float>, <class>, and for #t and #f.

Users may choose to modify the printed representation in two ways: override the print-object method for that instance's type, or provide a printing function to the "%m" directive for format or format-out.

Creates a string that contains a printed object representation

Synopsis

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

Parameters

object	An instance of <object>.
level:	An instance of <integer-or-false-or-not-supplied>. Holds the maximum depth to which the user wants recursive printing to go. Defaults to $not-supplied.
length:	An instance of <integer-or-false-or-not-supplied>. Holds the maximum number of elements the user wants a sequence to be printed. This does not apply to some sequences, such as strings. Defaults to $not-supplied.
circle?:	An instance of <boolean-or-not-supplied>. Defines print behavior when printing a circular list Defaults to $not-supplied.
pretty?:	An instance of <boolean-or-not-supplied>. Whether the user wants pretty printing. Defaults to $not-supplied.

Return Values

result

An instance of <byte-string>.

Description

Calls print to produce output according to the print request formed by the keyed arguments and returns the output as a string.

The above print functions use or set the below exported variables to accomplish their work (#f (the default value of all these variables) indicates there is no bounds for the variable):

Gives how far down recursively to print

Type

false-or(<integer>)

Description

If a number is given, print prints a # when it reached the level.

How many elements to print of a sequence

Type

false-or(<integer>)

Description

If a number is given, print prints a ... to indicate that it reached the maximum number of printable elements.

What to do for circular lists

Type

<boolean>

Description

If on, prints identical objects as, e.g.: #1#

Formats outputted object

Type

<boolean>

Description

If on, prints object indented with proper line breaks, according to the formatting specifications given to pprint-logical-block.

The below functions give printing information on <stream>s. It seems, however, that these functions are neither used nor implemented, as they all give #f or 0 as their response, no matter the <stream>.

Always returns #f

Synopsis

print-length (stream) => (length)

Parameters

stream

An instance of <stream>.

Return Values

length

An instance of false-or(<integer>).

Description

Returns the current value for the print request. See the print function for details.

Always returns #f

Synopsis

print-level (stream) => (level)

Parameters

stream

An instance of <stream>.

Return Values

level

An instance of false-or(<integer>).

Description

Returns the current value for the print request. See the print function for details. Users should have little use for this function because print takes care to call print-object only when the print level has not been exhausted.

Always returns 0

Synopsis

print-depth (stream) => (depth)

Parameters

stream

An instance of <stream>.

Return Values

depth

An instance of <integer>.

Description

Returns the current depth to which printing has descended into the object on which print was originally called. Print takes care to call print-object only when the print depth has not been exhausted.

Always returns #f

Synopsis

print-pretty? (stream) => (pretty?)

Parameters

stream

An instance of <stream>.

Return Values

pretty?

An instance of #f.

Description

Returns whether pretty printing is on. Users should have little use for this function (see the Section called PPrint Module).

Always returns #f

Synopsis

print-circle? (stream) => (circle?)

Parameters

stream

An instance of <stream>.

Return Values

circle?

An instance of #f.

Description

Returns whether circular printing is on. Users should have little use for this function because print takes care to detect circularities, tag multiply referenced objects, and emit tags rather than descending into objects to repeatedly print them.