source: project/wiki/eggref/4/dissector @ 13306

Last change on this file since 13306 was 13306, checked in by felix winkelmann, 12 years ago

added xlib page and removed download links

File size: 8.3 KB
Line 
1[[tags: egg]]
2
3== dissector
4
5[[toc:]]
6
7=== Description
8
9An object inspector for Chicken.
10
11=== Author
12
13Taylor Campbell
14
15Send questions, comments, bugs, et cetera to Taylor Campbell,
16either via email at
17<nowiki>
18<tt>&#99;</tt><tt>&#97;</tt><tt>&#109;</tt><tt>&#112;</tt><tt>&#98;</tt><tt>&#101;</tt><tt>&#108;</tt><tt>&#108;</tt><tt>&#32;</tt><tt>&#40;</tt><tt>&#97;</tt><tt>&#116;</tt><tt>&#41;</tt><tt>&#32;</tt><tt>&#109;</tt><tt>&#117;</tt><tt>&#109;</tt><tt>&#98;</tt><tt>&#108;</tt><tt>&#101;</tt><tt>&#32;</tt><tt>&#40;</tt><tt>&#100;</tt><tt>&#111;</tt><tt>&#116;</tt><tt>&#41;</tt><tt>&#32;</tt><tt>&#110;</tt><tt>&#101;</tt><tt>&#116;</tt>
19</nowiki>
20or via IRC in {{#scheme}} or in {{#chicken}} on [[http://freenode.net|Freenode]] ({{irc.freenode.net}}).
21
22=== Documentation
23
24The dissector is an interactive object structure inspector.  It allows
25for expedient inspection of a tree of objects' components.  It
26consists of a current 'focus object' --- the object currently being
27dissected --- a menu of that object's components, and an interactive
28command reader for commands that the user uses to interactively browse
29the objects.
30
31This extension defines the module {{dissector}}.
32
33
34==== Usage
35
36{{(require-extension dissector)}}
37
38
39==== dissect
40
41<procedure>(dissect object [inport [outport]])</procedure>
42
43{{Dissect}} invokes the dissector.  If given, {{inport}} & {{outport}}
44specify the ports to & from which commands & output are read &
45written.
46
47Dissector commands are put each on single lines.  The first part of
48the line should be a symbol.  The remainder of the line consists of
49arguments to the command.  After certain commands, a summary of the
50focus object may be printed.  This summary is truncated to fit within
51your terminal.  (Actually, it's truncated to fit within 72 lines.  But
52that's usually enough for most terminals.  And this doesn't
53necessarily apply if using a custom printer.)  Other commands may
54print a selection from the menu of an object's components.  In this
55selection is printed summaries of a number of an object's components.
56Each component is given a particular index; this index may be used to
57select the respective subcomponent of the focus object.  A list of
58dissector commands and help for them can be acquired with the
59{{help}} command, or the {{?}} alias for it.
60
61==== Configuration parameters
62
63There are several parameter objects that affect the dissector's
64operation.
65
66<parameter>dissection-prompt</parameter>
67
68This specifies the prompt to be printed before waiting for the user to
69send a command.  Must be a string.
70
71<parameter>dissection-menu-section-size -> exact, positive integer</parameter>
72
73This specifies the maximum number of entries to be printed when
74disclosing a section of a menu to the user.  Must be an exact,
75positive integer.
76
77<parameter>dissection-overview-printer</parameter>
78
79The function to print a dissection's overview.  The function takes two
80arguments: the object to print and the port to print it to.  Must be a
81procedure.
82
83<parameter>dissection-menu-entry-printer</procedure>
84
85The function to print a dissected object's components.  It takes
86three arguments: the object to print, the number of characters
87already printed to the port on the current line, and the port to
88print the object to.  Must be a procedure.
89
90<parameter>dissection-right-margin</parameter>
91
92The right margin for printing objects.  This is merely a hint to the
93{{dissection-...-printer}} parameters.  Its default is 71, to fit
94nearly all terminals. Must be an exact, positive integer.
95
96
97==== Supported dissector commands
98
99; {{apply (a)}} : Apply a function to the focus object.
100
101; {{apply/dissect (ad)}} : Apply a function to the focus object & dissect its result.
102
103; {{dissect (d)}} : Dissect a completely new object.
104
105; {{eval (e scheme)}} : Evaluate an expression.
106
107; {{help (?)}} : Print help for commands.
108
109; {{history (h)}} : Print the dissection history.
110
111; {{menu (m)}} : Print just the current menu.
112
113; {{overview (o)}} : Print the focus value, without a menu.
114
115; {{print (p)}} : Print out the entirety of the current dissection.
116
117; {{quit (q exit)}} : Quit the dissection.
118
119; {{select (s)}} : Select a component of the focus object to dissect.
120
121; {{up (u)}} : Move back up the history of dissected objects.
122
123; {{walk (w)}} : Walk about in the current menu.
124
125
126  apply expression
127
128  alias: a
129
130Evaluates {{expression}} in the interaction
131environment, which should produce a unary function, and applies it
132to the current focus object.  This does not modify the current
133dissection.
134
135  apply/dissect expression
136
137  alias: ad
138
139Evaluates {{expression}} in the interaction environment, which should
140produce a unary function, and applies it to the current focus object.
141It must return at least one value.  If it returns one value, that
142value is dissected; if it returns more than one, a list containing the
143values is dissected.
144
145  dissect expression
146
147  alias: d
148
149Evaluates {{expression}} in the interaction environment and dissects
150the value that is produced.  {{Expression}} may evaluate to one or
151more values.  With one value, that value is dissected; with more, a
152list of the values is dissected.
153
154  eval expression
155
156  aliases: e scheme
157
158Evalutes {{expression}} in the interaction environment and prints the
159results.  This does not modify the current dissection.
160
161  help [command]
162
163  alias: ?
164
165If {{command}} is absent, prints out a brief help synopsis for every
166supported command; otherwise prints out help for {{command}}.
167
168  history
169
170  alias: h
171
172Prints the dissection history.
173
174  menu
175
176  alias: m
177
178Prints just the current menu.
179
180  overview
181
182  alias: o
183
184Prints the focus value, without a menu.
185
186  print
187
188  alias: p
189
190Prints out the entirety of the current dissection.
191
192  quit
193
194  aliases: q exit
195
196Quits the dissector.
197
198  select index [deep-index ...]
199
200  alias: s
201
202Selects the {{index}}th slot in the focus object to dissect
203next. {{Index}} must be a valid index into the focus object, as shown
204by the menu.  If more than one index is passed, it is as if the select
205command were applied multiple times, to each successive index.
206
207  up [count]
208
209  alias: u
210
211Moves {{count}} elements back up the history of dissected objects.  If
212{{count}} is absent, it defaults to 1.
213
214  walk [slot-count]
215
216  alias: w
217
218Moves the current menu selection by {{slot-count}} elements.  If
219{{slot-count}} is negative, the menu is moved backwards; if it's
220positive, it is moved forwards.  If it is absent, the menu is moved
221forward by {{(dissection-menu-section-size)}} slots.
222
223
224=== Changelog
225
226* 1.7.5 Ported to chicken4, several bugfixes
227* 1.7.4 Fixed several bugs reported by Andre Kuehne
228* 1.7.3 Removed incorrect redefinition of {{fold}} [Reed Sheridan]
229* 1.7.2 Renamed {{tagged-pointer?}} which shadowed a primitive function [Thanks to Reed Sheridan]
230* 1.7.1 Replaced use of {{(end-of-file)}} with {{#!eof}}
231* 1.7 Initial release for Chicken
232
233=== License
234
235  Copyright (C) 2004, Taylor Campbell
236  All rights reserved.
237 
238  Redistribution and use in source and binary forms, with or without
239  modification, are permitted provided that the following conditions are
240  met:
241 
242   - Redistributions of source code must retain the above copyright
243     notice, this list of conditions and the following disclaimer.
244   - Redistributions in binary form must reproduce the above copyright
245     notice, this list of conditions and the following disclaimer in the
246     documentation and/or other materials provided with the distribution.
247   - The name of the author may not be used to endorse or promote
248     products derived from this software without specific prior written
249     permission.
250 
251  Modifications are requested, but not required, to be sent to the author
252  in source code  form, along with any accompanying new or modified
253  documentation.
254 
255  THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
256  IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
257  WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
258  DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
259  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
260  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
261  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
262  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
263  STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
264  IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
265  POSSIBILITY OF SUCH DAMAGE.
Note: See TracBrowser for help on using the repository browser.