source: project/wiki/eggref/4/describe-coops @ 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.0 KB
Line 
1== describe-coops
2
3Display textual descriptions of built-in objects, user-created records, and coops objects.
4
5== Overview
6
7{{describe-coops}} provides the same API as {{describe}} but
8additionally supports [[/egg/coops|coops]] objects.
9
10The only API difference is the addition of a {{describe-object}}
11generic procedure, with a useful default implementation for coops
12classes and objects.  If {{coops-primitive-objects}} is loaded, you
13can specialize on primitive objects as well.
14
15== Usage
16
17 (use describe-coops)
18
19There's no need to load {{describe}}, as this egg loads {{describe}}
20itself and exports a compatible API.  Loading {{describe}} after
21{{describe-coops}} will wipe out the REPL shortcuts.
22
23== REPL
24
25The REPL shortcuts -- {{,d}} and friends -- provided by the ''describe'' egg
26are extended to support coops objects.
27
28== API
29
30<procedure>(describe obj #!optional out)</procedure>
31
32Prints a textual description of {{OBJ}} to output port {{OUT}}, which defaults to
33{{(current-output-port)}}.  For coops objects, this dispatches to {{describe-object}};
34otherwise it calls {{describe}} from the [[/egg/describe|describe egg]].
35
36Note that this is not a generic procedure.
37
38<procedure>(describe-object obj out)</procedure>
39
40Generic procedure specialized on {{OBJ}}, responsible for printing
41the textual description of {{OBJ}}.  {{describe}} calls this under
42the hood.
43
44 #;> (define-class <point> () (x y z))
45
46 #;> (describe <point>)
47 coops standard-class <point>
48   class precedence list: (<standard-object>)
49   slots: (x y z)
50
51 #;> (describe (make <point> 'x 1 'y 2 'z 3))
52 coops instance of class <point>:
53   x : 1
54   y : 2
55   z : 3
56
57 #;> (define-method (describe-object (obj <point>) out)
58       (fprintf out "<point> object with coordinates (~A, ~A, ~A)~%"
59        (slot-value obj 'x) (slot-value obj 'y) (slot-value obj 'z)))
60
61 #;> (describe (make <point> 'x 1 'y 2 'z 3))
62 <point> object with coordinates (1, 2, 3)
63
64If {{coops-primitive-objects}} is loaded, you can specialize on
65primitive objects such as fixnums; the default implementation prints
66both the object's class and the ''describe'' egg's description. For example:
67
68 #;> (describe 3)
69 exact integer 3 (#x3 #o3 #b11 #\x3)
70 #;> (use coops-primitive-objects)
71 #;> (describe 3)
72 coops instance of primitive class <fixnum>
73 exact integer 3 (#x3 #o3 #b11 #\x3)
74
75<parameter>(describe-sequence-limit n)</parameter>
76<procedure>(set-describer! tag proc)</procedure>
77<procedure>(dump obj #!optional offset length out)</procedure>
78<procedure>(hexdump bv start end ref out)</procedure>
79
80Same as their [[/egg/describe|describe egg]] equivalents.
81They are exported for convenience, so {{(use describe)}} is not required
82when using this egg.
83
84It's not currently possible to dump a coops object.
85
86== Version history
87
88; 0.1 : Initial release
89
90== Author
91
92[[/users/jim-ursetto|Jim Ursetto]], [[http://ursetto.com|Ursetto Consulting, Inc.]]
93
94Some code was taken from Kon Lovett's [[/egg/coops-utils|coops-utils]] egg.
95
96== License
97
98[[https://bitbucket.org/ursetto/describe-coops/raw/tip/LICENSE.txt|MIT]].
Note: See TracBrowser for help on using the repository browser.