dissector

  1. dissector
    1. Description
    2. Author
    3. Documentation
      1. Usage
      2. dissect
      3. Configuration parameters
      4. Supported dissector commands
    4. Changelog
    5. License

Description

An object inspector for Chicken.

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).

Documentation

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

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.