chickadee » jiffi » armor-printer

Expands into an anonymous procedure which can be used to print an armor instance as a string, to make debugging easier.

On CHICKEN 5, you can pass the anonymous procedure to set-record-printer!. If you want to support both CHICKEN 4 and CHICKEN 5, it is simpler to use define-armor-printer instead of armor-printer.

Usage:

(armor-printer ARMOR-NAME
  show-address: SHOW-ADDRESS  ; optional
  (LABEL GETTER)              ; optional
  ...)

Record printers are used to output the record instance as a string, for example in REPL results, error messages, or when included in strings. The main purpose of an armor record printer is to provide information to make debugging easier.

Printers created with this macro use the following style:

#<ARMOR-NAME address LABEL: value ...>

If the armor is null, it is printed like:

#<ARMOR-NAME NULL>

ARMOR-NAME is the record type name that was passed to define-armor-type.

If SHOW-ADDRESS is #t, the armor data's memory address is shown in the output, in the format 0x12345678. If SHOW-ADDRESS is #f or the keyword clause is omitted, the address is not shown. (This option does not affect whether NULL is shown when the armor is null. There is currently no option to disable that.)

LABEL can be a non-quoted symbol or string containing the label to show for a field value. For example, it might be the name of a struct field. Or, if LABEL is #f, the field value will be printed with no label.

GETTER is an existing procedure that returns a value when passed the record instance. For example, it could be a field getter defined with define-struct-accessors or struct-getter.

Example:

;; CHICKEN 5 only
(set-record-printer! key-event
  (armor-printer key-event
    show-address: #f
    (#f key-event-code)
    (mods key-event-mods)))

(define ev (create-key-event 'a '(lctrl)))
(printf "~A" ev)    ; #<key-event a mods: (lctrl)>

(free-key-event! ev)
(printf "~A" ev)    ; #<key-event NULL>