Visualizing toolkit browsers

Visualizing generated decoders

It can be tricky to understand the structure of a decoder by looking at the generated code. The -ascii-dag and -ascii-tree options dump complete listings of decision dags and trees, but it can be difficult to understand these dumps. The toolkit can also generate Icon code that you can use to explore trees, viewing one path at a time. This Icon code, when combined with a suitable main program, can act as a CGI script on the World-Wide Web, and you can explore the trees using your favorite Web browser.

The CGI script provides dual views of each node in the decision tree for each matching statement:

The text view shows the path to that node and the choices available at that node. A ``choice'' is simply a range of values for a particular field, and the path to the node gives the choices made that enabled us to reach this node.
The graphical view shows the path to the node, plus all nodes reachable from the current node. Ellipses represent decision nodes that test the value of the field written in the node. Double ellipses represent decisions that have already been made. Leaf nodes are shown as boxes; they execute code in the matching statement.
If your browser supports client-side image maps, you can click on any visible node to move to that node. Clicking on a leaf node moves you back to the text view, so you can see the code associated with that node. Graphical views of large trees are unwieldy and unhelpful, and they will probably break your browser. Confine graphical views to those of interior nodes that don't reach too many leaves.

We have an example based on our SPARC disassembler. Here's a fairly simple interior node. Here's an interesting node from a user's matching statement. For subtrees like this, the toolkit should be generating better code than it is. The graph-drawing is by dot.

Setting up your own browser

This section shows how to set things up so you can browse matching statements that you write.

Let's suppose you have a SLED specification called problem.spec, and you've written one or more matching statements in the file problem.m.

Create the Icon file used to describe the matching statements:
```
tools -icon-dag problem.icn -matcher problem.m problem.spec
```
The writes a description of the generated matchers into problem.icn. You need an experimental version of the toolkit, which supports the -icon-dag option.
Combine this Icon file with the htmltree.icn file supplied with the toolkit distribution, and call the resulting program problem:
```
icont -o problem problem.icn htmltree.icn
```
(If you want the graphics view, you'll have to install dot from the AT&T graphviz package, and you'll have to edit htmltree.icn to use the appropriate path name.)
Put the resulting executable where it can be executed as a CGI script. You'll probably need help from your friendly local systems administrator. Here's what I had to do at my site, which runs the Apache 1.0.3 server; your mileage may vary:
1. Put the executable Icon program in the directory /home/nr/public_html/cgi-bin/trees/. The corresponding URL is http://www.cs.virginia.edu/cgi-bin/cgiwrap/nr/trees/.
2. The code in htmltree.icn uses the environment variables SERVER_NAME and SCRIPT_NAME to reconstruct the URL. With luck, these will be independent of server. Ha ha.
3. For some unknown reason, Icon programs won't run as CGI scripts at my site, so I had to wrap things in this shell script:
```
#!/bin/sh
tree="$1"
shift
SCRIPT_NAME="${SCRIPT_NAME}?$tree"
export SCRIPT_NAME
exec /home/nr/public_html/cgi-bin/trees/$tree "$@"
```
Use the URL to explore the matching statements. You can see matcher for the sample SPARC disassembler at http://www.cs.virginia.edu/cgi-bin/cgiwrap/nr/trees/view?sparcdis.

Visit the Toolkit home page