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.

dissector

Outdated egg!
dissector

Author

Taylor Campbell

Send questions, comments, bugs, et cetera to Taylor Campbell, either via email at

campbell (at) mumble (dot) net

or via IRC in #scheme or in #chicken on Freenode (irc.freenode.net).

The dissector is an interactive object structure inspector. It allows for expedient inspection of a tree of objects' components. It consists of a current 'focus object' --- the object currently being dissected --- a menu of that object's components, and an interactive command reader for commands that the user uses to interactively browse the objects.

This extension defines the module dissector.

Usage

(require-extension dissector)

dissect

[procedure] (dissect object [inport [outport]])

Dissect invokes the dissector. If given, inport & outport specify the ports to & from which commands & output are read & written.

Dissector commands are put each on single lines. The first part of the line should be a symbol. The remainder of the line consists of arguments to the command. After certain commands, a summary of the focus object may be printed. This summary is truncated to fit within your terminal. (Actually, it's truncated to fit within 72 lines. But that's usually enough for most terminals. And this doesn't necessarily apply if using a custom printer.) Other commands may print a selection from the menu of an object's components. In this selection is printed summaries of a number of an object's components. Each component is given a particular index; this index may be used to select the respective subcomponent of the focus object. A list of dissector commands and help for them can be acquired with the help command, or the ? alias for it.

Configuration parameters

There are several parameter objects that affect the dissector's operation.

[parameter] dissection-prompt

This specifies the prompt to be printed before waiting for the user to send a command. Must be a string.

[parameter] dissection-menu-section-size -> exact, positive integer

This specifies the maximum number of entries to be printed when disclosing a section of a menu to the user. Must be an exact, positive integer.

[parameter] dissection-overview-printer

The function to print a dissection's overview. The function takes two arguments: the object to print and the port to print it to. Must be a procedure.

<parameter>dissection-menu-entry-printer</procedure>

The function to print a dissected object's components. It takes three arguments: the object to print, the number of characters already printed to the port on the current line, and the port to print the object to. Must be a procedure.

[parameter] dissection-right-margin

The right margin for printing objects. This is merely a hint to the dissection-...-printer parameters. Its default is 71, to fit nearly all terminals. Must be an exact, positive integer.

Supported dissector commands

apply (a): Apply a function to the focus object.
apply/dissect (ad): Apply a function to the focus object & dissect its result.
dissect (d): Dissect a completely new object.
eval (e scheme): Evaluate an expression.
help (?): Print help for commands.
history (h): Print the dissection history.
menu (m): Print just the current menu.
overview (o): Print the focus value, without a menu.
print (p): Print out the entirety of the current dissection.
quit (q exit): Quit the dissection.
select (s): Select a component of the focus object to dissect.
up (u): Move back up the history of dissected objects.
walk (w): Walk about in the current menu.

 apply expression

 alias: a

Evaluates expression in the interaction environment, which should produce a unary function, and applies it to the current focus object. This does not modify the current dissection.

 apply/dissect expression

 alias: ad

Evaluates expression in the interaction environment, which should produce a unary function, and applies it to the current focus object. It must return at least one value. If it returns one value, that value is dissected; if it returns more than one, a list containing the values is dissected.

 dissect expression

 alias: d

Evaluates expression in the interaction environment and dissects the value that is produced. Expression may evaluate to one or more values. With one value, that value is dissected; with more, a list of the values is dissected.

 eval expression

 aliases: e scheme

Evalutes expression in the interaction environment and prints the results. This does not modify the current dissection.

 help [command]

 alias: ?

If command is absent, prints out a brief help synopsis for every supported command; otherwise prints out help for command.

 history

 alias: h

Prints the dissection history.

 menu

 alias: m

Prints just the current menu.

 overview

 alias: o

Prints the focus value, without a menu.

 print

 alias: p

Prints out the entirety of the current dissection.

 quit

 aliases: q exit

Quits the dissector.

 return

 aliases: r

Quits the dissection and returns the current focus object.

 select index [deep-index ...]

 alias: s

Selects the indexth slot in the focus object to dissect next. Index must be a valid index into the focus object, as shown by the menu. If more than one index is passed, it is as if the select command were applied multiple times, to each successive index.

 up [count]

 alias: u

Moves count elements back up the history of dissected objects. If count is absent, it defaults to 1.

 walk [slot-count]

 alias: w

Moves the current menu selection by slot-count elements. If slot-count is negative, the menu is moved backwards; if it's positive, it is moved forwards. If it is absent, the menu is moved forward by (dissection-menu-section-size) slots.

Changelog

1.7.6 Added return command
1.7.5 Ported to chicken4, several bugfixes
1.7.4 Fixed several bugs reported by Andre Kuehne
1.7.3 Removed incorrect redefinition of fold [Reed Sheridan]
1.7.2 Renamed tagged-pointer? which shadowed a primitive function [Thanks to Reed Sheridan]
1.7.1 Replaced use of (end-of-file) with #!eof
1.7 Initial release for Chicken

License

 Copyright (C) 2004, Taylor Campbell
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are
 met:
 
  - Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.
  - Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in the
    documentation and/or other materials provided with the distribution.
  - The name of the author may not be used to endorse or promote
    products derived from this software without specific prior written
    permission.
 
 Modifications are requested, but not required, to be sent to the author
 in source code  form, along with any accompanying new or modified
 documentation.
 
 THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
 STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
 IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 POSSIBILITY OF SUCH DAMAGE.