source: project/release/4/dissector/README @ 12286

Last change on this file since 12286 was 12286, checked in by felix winkelmann, 13 years ago

ported to chicken-4

File size: 6.5 KB
Line 
1Dissector 1.7: An object inspector for Chicken
2
3--
4
5Copyright (C) 2004, Taylor Campbell
6All rights reserved.
7See the LICENCE file for details.
8
9--
10
11The dissector is an interactive object structure inspector.  It allows
12for expedient inspection of a tree of objects' components.  It consists
13of a current 'focus object' -- the object currently being dissected --,
14a menu of that object's components, and an interactive command reader
15for commands that the user uses to interactively browse the objects.
16
17(DISSECT <object> [<inport> [<outport>]])                    ;procedure
18    DISSECT invokes the dissector.  If given, INPORT & OUTPORT specify
19    the ports to & from which commands & output are read & written.
20    (Bug, due to csi: when first invoking the dissector, the prompt is
21    printed twice.)
22
23Dissector commands are put each on single lines.  The first part of the
24line should be a symbol.  The remainder of the line consists of
25arguments to the command.  After certain commands, a summary of the
26focus object may be printed.  This summary is truncated to fit within
27your terminal.  (Actually, it's truncated to fit within 72 lines.  But
28that's usually enough for most terminals.)  Other commands may print a
29selection from the menu of an object's components.  In this selection
30is printed summaries of a number of an object's components.  Each
31component is given a particular index; this index may be used to select
32the respective subcomponent of the focus object.  A list of dissector
33commands and help for them can be acquired with the HELP command, or
34the ? alias for it.
35
36There are several parameter objects that affect the dissector.
37
38DISSECTION-PROMPT -> string                                  ;parameter
39    This specifies the prompt to be printed before waiting for the user
40    to send a command.
41
42DISSECTION-MENU-SECTION-SIZE -> exact, positive integer      ;parameter
43    This specifies the maximum number of entries to be printed when
44    disclosing a section of a menu to the user.
45
46DISSECTION-MENU-SECTION-SIZE -> procedure                    ;parameter
47    The function to print a dissection's overview.  The function takes
48    two arguments: the object to print and the port to print it to.
49
50DISSECTION-MENU-ENTRY-PRINTER -> procedure                   ;parameter
51    The function to print a dissected object's components.  It takes
52    three arguments: the object to print, the number of characters
53    already printed to the port on the current line, and the port to
54    print the object to.
55
56DISSECTOR-RIGHT-MARGIN -> exact, positive integer            ;parameter
57    The right margin for printing objects.  This is merely a hint to
58    the DISSECTION-...-PRINTER parameters.  Its default is 71, to fit
59    nearly all terminals.
60
61Supported dissector commands:
62   apply (a) - Apply a function to the focus object.
63   apply/dissect (ad) - Apply a function to the focus object & dissect
64     its result.
65   dissect (d) - Dissect a completely new object.
66   eval (e scheme) - Evaluate an expression.
67   help (?) - Print help for commands.
68   history (h) - Print the dissection history.
69   menu (m) - Print just the current menu.
70   overview (o) - Print the focus value, without a menu.
71   print (p) - Print out the entirety of the current dissection.
72   quit (q exit) - Quit the dissection.
73   select (s) - Select a component of the focus object to dissect.
74   up (u) - Move back up the history of dissected objects.
75   walk (w) - Walk about in the current menu.
76
77apply <expression>                                   ;dissector command
78      (aliases: a)
79   Evaluates EXPRESSION in the interaction environment, which should
80   produce a unary function, and applies it to the current focus
81   object.  This does not modify the current dissection.
82
83apply/dissect <expression>                           ;dissector command
84      (aliases: ad)
85   Evaluates EXPRESSION in the interaction environment, which should
86   produce a unary function, and applies it to the current focus
87   object.  It must return at least one value.  If it returns one
88   value, that value is dissected; if it returns more than one, a
89   list containing the values is dissected.
90
91dissect <expression>                                 ;dissector command
92      (aliases: d)
93   Evaluates EXPRESSION in the interaction environment and dissects
94   the value that is produced.  EXPRESSION may evaluate to one or
95   more values.  With one value, that value is dissected; with more,
96   a list of the values is dissected.
97
98eval <expression>                                    ;dissector command
99      (aliases: e scheme)
100   Evalutes EXPRESSION in the interaction environment and prints the
101   results.  This does not modify the current dissection.
102
103help [<command>]                                     ;dissector command
104      (aliases: ?)
105   If COMMAND is absent, prints out a brief help synopsis for every
106   supported command; otherwise prints out help for COMMAND.
107
108history                                              ;dissector command
109      (aliases: h)
110   Prints the dissection history.
111
112menu                                                 ;dissector command
113      (aliases: m)
114   Prints just the current menu.
115
116overview                                             ;dissector command
117      (aliases: o)
118   Prints the focus value, without a menu.
119
120print                                                ;dissector command
121      (aliases: p)
122   Prints out the entirety of the current dissection.
123
124quit                                                 ;dissector command
125      (aliases: q exit)
126   Quits the dissector.
127
128select <index> [<deep-index> ...]                    ;dissector command
129      (aliases: s)
130   Selects the INDEX'th slot in the focus object to dissect next.
131   INDEX must be a valid index into the focus object, as shown by
132   the menu.  If more than one index is passed, it is as if the
133   select command were applied multiple times, to each successive
134   index.
135
136up [<count>]                                         ;dissector command
137      (aliases: u)
138   Moves COUNT elements back up the history of dissected objects.
139   If COUNT is absent, it defaults to 1.
140
141walk [<slot-count>]                                  ;dissector command
142      (aliases: w)
143   Moves the current menu selection by SLOT-COUNT.  If SLOT-COUNT is
144   negative, the menu is moved backwards; if it's positive, it is
145   moved forwards.  If it is absent, the menu is moved forward by
146   (dissection-menu-section-size) slots.
147
148--
149
150Send questions, comments, bugs, et cetera to Taylor Campbell, either
151via email at campbell@bloodandcoffee.net or via IRC in #scheme or in
152#chicken on Freenode (irc.freenode.net).
Note: See TracBrowser for help on using the repository browser.