Outdated egg!

This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for the CHICKEN 5 version of this egg, if it exists.

If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.

describe

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

Overview

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

API

[procedure] (describe obj #!optional out)

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

[procedure] (dump obj #!optional offset length out)

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.

[parameter] (describe-sequence-limit n)

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)

[procedure] (set-describer! TAG PROC)

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

[procedure] (hexdump bv start end ref out)

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

0.1: Initial release

Author

Jim Ursetto, Ursetto Consulting, Inc.

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

License

3-clause BSD.