chickadee » describe


Display textual descriptions of built-in objects and user-created records.


The native csi describe mechanism (,d and friends) is only available at the REPL. This egg makes it available to programs, and also extends it a bit.

To describe coops objects, see the describe-coops extension.

REPL usage

This egg adds the following convenient REPL shortcuts to describe and dump:

,d EXP            (describe) Describe result of evaluated EXP
,du EXP           (describe) Hexdump contents of bytevector EXP
,dur EXP LEN      (describe) Hexdump first LEN bytes of bytevector EXP
,dus EXP OFF LEN  (describe) Hexdump LEN bytes of bytevector EXP at offset OFF


(describe obj #!optional out) procedure

Prints a textual description of OBJ to output port OUT, which defaults to (current-output-port).

(dump obj #!optional offset length out) procedure

Hexdump the contents of OBJ to output port OUT, starting at OFFSET and continuing for LENGTH bytes. Offset defaults to 0, length to #f (meaning, until the end) and output to (current-output-port).

If dumping a pointer object, length defaults to 32 bytes, as the underlying length is unknown to us.

(describe-sequence-limit n) parameter

Limit the number of elements displayed to N when describing the contents of a sequence -- e.g. a list, vector, bytevector, hash table or string. Defaults to 40.

#;6> (parameterize ((describe-sequence-limit 5))
       (describe (iota 100)))
list of length 100
 0: 0
 1: 1
 2: 2
 3: 3
 4: 4
 (95 elements not displayed)
(set-describer! TAG PROC) procedure

Sets a custom description handler that invokes PROC when the ,d or describe command is invoked with a record-type object that has the type TAG (a symbol). PROC is called with two arguments: the object to be described and an output-port. It should write a possibly useful textual description of the object to the passed output-port. For example:

#;1> (define-record-type point (make-point x y) point?
       (x point-x)
       (y point-y))
#;2> (set-describer! 'point 
       (lambda (pt o)
         (with-output-to-port o
           (lambda ()
             (print "a point with x=" (point-x pt) " and y=" (point-y pt))))))
#;3> ,d (make-point 1 2)
a point with x=1 and y=2

Low-level API

(hexdump bv start end ref out) procedure

Hexdump the contents of bytevector-like object BV from offset START to offset END, to output port OUT. REF is a procedure of two arguments, (obj i), which should return the byte value of OBJ at offset I.

An example of REF for a u8vector might be u8vector-ref. For string it might be (λ (obj i) (char->integer (string-ref obj i))), or even ##sys#byte if you want to live dangerously.

dump provides a high-level interface to this procedure.

Version history

Initial release


Jim Ursetto, Ursetto Consulting, Inc.

Much of the code was taken from Chicken's csi.scm.


3-clause BSD.

Contents »