14.10 Custom Output

MIT/GNU Scheme provides hooks for specifying that specified objects have special written representations. There are no restrictions on the written representations.

procedure: define-print-method predicate print-method

Defines the print method for objects satisfying predicate to be print-method. The predicate argument must be a unary procedure that returns true for the objects to print specially, and print-method must be a binary procedure that accepts one of those objects and a textual output port.

Although print-method can print the object in any way, we strongly recomment using one of the following special printers.

procedure: standard-print-method name [get-parts]

The name argument may be a unary procedure, a string, or a symbol; if it is a procedure it is called with the object to be printed as its argument and should return a string or a symbol. The get-parts argument, if provided, must be a unary procedure that is called with the object to be printed and must return a list of objects. If get-parts is not provided, it defaults to a procedure that returns an empty list.

The output generated by this method is in a standard format:

#[<name> <hash> <part>…]

where <name> is the string or symbol from name as printed by display, <hash> is a unique nonnegative integer generated by calling hash-object on the object, and the <part>s are the result of calling get-parts as printed by write and separated by spaces.

One significant advantage of print methods generated by standard-print-method is that the parts returned by get-parts are examined when searching for circular structure (as by write) or shared structure (as by write-shared). In effect the printer sees one of these objects as a compound object containing those parts.

procedure: bracketed-print-method name printer

The name argument may be a unary procedure, a string, or a symbol; if it is a procedure it is called with the object to be printed as its argument and should return a string or a symbol. The printer argument must be a binary procedure, which is called with the object to print and a textual output port as its arguments.

Similar to standard-print-method, this procedure prints an object

#[<name> <hash><output>]

where <name> is the string or symbol from name as printed by display, <hash> is a unique nonnegative integer generated by calling hash-object on the object, and <output> is the text written by printer.

This procedure has the benefit of printing objects using the standard bracketed form, but because its output is unstructured can not be examined for sharing or circularity. Generally speaking it’s preferable to use standard-print-method instead.

The following are deprecated procedures that have been replaced by the above.

obsolete procedure: set-record-type-unparser-method! record-type unparser-method

This procedure is deprecated; instead use

(define-print-method (record-constructor record-type)
  unparser-method)

provided that unparser-method is really a print method.

obsolete procedure: unparser/set-tagged-vector-method! tag unparser-method

obsolete procedure: unparser/set-tagged-pair-method! tag unparser-method

These procedures arg deprecated. There is no direct replacement for them.

These were primarily used by define-structure, which now generates new-style print methods. If you have other uses of these, it should be possible to translate them to use define-print-method with hand-written predicates.

obsolete procedure: standard-unparser-method name procedure

This procedure is deprecated; it is currently an alias for bracketed-print-method.

obsolete procedure: with-current-unparser-state unparser-state procedure

This procedure is deprecated, with no direct replacement. In general just use procedure without wrapping it.