13.8 Printer Extension
value
A write-proc method takes three arguments: the structure to be printed, the target port, and an argument that is #t for write mode, #f for display mode, or 0 or 1 indicating the current quoting depth for print mode. The procedure should print the value to the given port using write, display, print, fprintf, write-special, etc.
The port write handler, port display handler, and print handler are specially configured for a port given to a custom-write procedure. Printing to the port through display, write, or print prints a value recursively with sharing annotations. To avoid a recursive print (i.e., to print without regard to sharing with a value currently being printed), print instead to a string or pipe and transfer the result to the target port using write-string or write-special. To print recursively to a port other than the one given to the custom-write procedure, copy the given port’s write handler, display handler, and print handler to the other port.
The port given to write-proc is not necessarily the actual target port. In particular, to detect cycles, sharing, and quoting modes (in the case of print), the printer invokes a custom-write procedure with a port that records information about recursive prints, and does not retain any other output. This information-gathering phase needs the same objects (in the eq? sense) to be printed as later, so that the recorded information can be correlated with printed values.
Recursive print operations may trigger an escape from a call to write-proc. For example, printing may escape during pretty-printing where a tentative print attempt overflows the line, or it may escape while printing error output that is constrained to a limited width.
The following example definition of a tuple type includes a write-proc procedure that prints the tuple’s list content using angle brackets in write and print mode and no brackets in display mode. Elements of the tuple are printed recursively, so that graph and cycle structure can be represented.
(define (tuple-print tuple port mode) (when mode (write-string "<" port)) (let ([l (tuple-ref tuple)] [recur (case mode [(#t) write] [(#f) display] [else (lambda (p port) (print p port mode))])]) (unless (zero? (vector-length l)) (recur (vector-ref l 0) port) (for-each (lambda (e) (write-string ", " port) (recur e port)) (cdr (vector->list l))))) (when mode (write-string ">" port)))
(struct tuple (ref) #:methods gen:custom-write [(define write-proc tuple-print)])
> (display (tuple #(1 2 "a"))) 1, 2, a
> (print (tuple #(1 2 "a"))) <1, 2, "a">
> (let ([t (tuple (vector 1 2 "a"))]) (vector-set! (tuple-ref t) 0 t) (write t)) #0=<#0#, 2, "a">
The make-constructor-style-printer function can help in the implementation of a write-proc, as in this example:
(require racket/struct)
(struct point (x y) #:methods gen:custom-write [(define write-proc (make-constructor-style-printer (lambda (obj) 'point) (lambda (obj) (list (point-x obj) (point-y obj)))))])
> (print (point 1 2)) (point 1 2)
> (write (point 1 2)) #<point: 1 2>
Changed in version 8.7.0.5 of package base: Added a check so that omitting write-proc is now a syntax error.
procedure
(custom-write? v) → boolean?
v : any/c
procedure
→ (custom-write? output-port? (or/c #t #f 0 1) . -> . any) v : custom-write?
value
value
value