source: project/wiki/eggref/4/describe @ 27820

Last change on this file since 27820 was 27820, checked in by Jim Ursetto, 8 years ago

wiki/describe & describe-coops: document initial release 0.1

File size: 3.2 KB
Line 
1== describe
2
3Display textual descriptions of built-in objects and user-created records.
4
5== Overview
6
7The native {{csi}} describe mechanism ({{,d}} and friends) is only
8available at the REPL.  This egg makes it available to programs,
9and also extends it a bit.
10
11To describe [[/egg/coops|coops]] objects, see the [[/egg/describe-coops|describe-coops]] extension.
12
13== REPL usage
14
15This egg adds the following convenient REPL shortcuts to {{describe}} and {{dump}}:
16
17 ,d EXP            (describe) Describe result of evaluated EXP
18 ,du EXP           (describe) Hexdump contents of bytevector EXP
19 ,dur EXP LEN      (describe) Hexdump first LEN bytes of bytevector EXP
20 ,dus EXP OFF LEN  (describe) Hexdump LEN bytes of bytevector EXP at offset OFF
21
22== API
23
24<procedure>(describe obj #!optional out)</procedure>
25
26Prints a textual description of {{OBJ}} to output port {{OUT}}, which defaults to
27{{(current-output-port)}}.
28
29<procedure>(dump obj #!optional offset length out)</procedure>
30
31Hexdump the contents of {{OBJ}} to output port {{OUT}}, starting at {{OFFSET}} and
32continuing for {{LENGTH}} bytes.  Offset defaults to 0, length to {{#f}} (meaning,
33until the end) and output to {{(current-output-port)}}.
34
35If dumping a {{pointer}} object, length defaults to 32 bytes, as the underlying
36length is unknown to us.
37
38<parameter>(describe-sequence-limit n)</parameter>
39
40Limit the number of elements displayed to {{N}} when describing the contents of
41a sequence -- e.g. a list, vector, bytevector, hash table or string.
42Defaults to 40.
43
44 #;6> (parameterize ((describe-sequence-limit 5))
45        (describe (iota 100)))
46 list of length 100
47  0: 0
48  1: 1
49  2: 2
50  3: 3
51  4: 4
52  (95 elements not displayed)
53
54<procedure>(set-describer! TAG PROC)</procedure>
55
56Sets a custom description handler that invokes {{PROC}} when the
57{{,d}} or {{describe}} command is invoked with a record-type object that has the type
58{{TAG}} (a symbol). {{PROC}} is called with two arguments: the object
59to be described and an output-port. It should write a possibly useful
60textual description of the object to the passed output-port. For
61example:
62
63 #;1> (define-record-type point (make-point x y) point?
64        (x point-x)
65        (y point-y))
66 #;2> (set-describer! 'point
67        (lambda (pt o)
68          (with-output-to-port o
69            (lambda ()
70              (print "a point with x=" (point-x pt) " and y=" (point-y pt))))))
71 #;3> ,d (make-point 1 2)
72 a point with x=1 and y=2
73
74== Low-level API
75
76<procedure>(hexdump bv start end ref out)</procedure>
77
78Hexdump the contents of bytevector-like object {{BV}} from offset {{START}} to offset {{END}},
79to output port {{OUT}}.  {{REF}} is a procedure of two arguments, {{(obj i)}}, which should
80return the byte value of {{OBJ}} at offset {{I}}.
81
82An example of {{REF}} for a u8vector might be {{u8vector-ref}}.  For string it might
83be {{(λ (obj i) (char->integer (string-ref obj i)))}}, or even {{##sys#byte}}
84if you want to live dangerously.
85
86{{dump}} provides a high-level interface to this procedure.
87
88== Version history
89
90; 0.1 : Initial release
91
92== Author
93
94[[/users/jim-ursetto|Jim Ursetto]], [[http://ursetto.com|Ursetto Consulting, Inc.]]
95
96Much of the code was taken from Chicken's {{csi.scm}}.
97
98== License
99
100[[https://bitbucket.org/ursetto/describe/raw/tip/LICENSE.txt|3-clause BSD]].
Note: See TracBrowser for help on using the repository browser.