chickadee » object-graph

object-graph

Graph description generator for graphs of arbitrary Scheme objects.

Usage

(require-extension object-graph)

Documentation

The object-graph library is a graph generator that accepts Scheme objects as nodes, and produces descriptions for the Tulip and http://www.graphviz.org/ graph visualization frameworks. It is based on the bouquet Common Lisp package by Eugene Zaikonnikov.

object-graph maintains the nodes and edges of the current graph instance in Chicken parameters that are manipulated via the procedures in this library. These procedures are destructive; they implicitly modify the current graph instance.

The node representation of a Scheme object in the graph is computed by first obtaining its string representation with ->string and then by computing the hash of the string. The hash value is used as the node number in the graph.

The above means that by default all instances of a record type will have the same node representation, because they have the same string representation. In those cases, you must use define-record-printer to create distinct representations of distinct record instances.

Library procedures

Graph construction

reset-graph:: UNDEFINED -> UNDEFINED procedure

Resets the current graph instance and sets the lists of nodes and edges to empty lists.

register-node:: OBJECT -> NODE procedure

Creates node instance and associates it with the given object. Returns the newly constructed node instance.

register-node-unless-exists:: OBJECT -> NODE procedure

Registers the given node only if it does not already exist in the graph.

register-edge:: FROM-OBJECT TO-OBJECT -> EDGE procedure

Registers a directed edge between FROM and TO, and returns the resulting edge. e

Node and edge lookup operations

assoc-node:: NODE -> (HASH . NODE) procedure

Looks up a node in the current graph instance and if found, returns a pair containing the hash value associated with this node, and the node instance. If not found, returns #f.

lookup-node:: NODE -> NODE procedure

Looks up a node in the current graph instance and if found, returns the node instance.

lookup-object-node:: OBJECT -> NODE procedure

Given an object, computes its hash, looks up that hash value in the current graph instance and if found, returns the corresponding node instance.

assoc-edge:: EDGE -> EDGE procedure

Looks up an edge in the current graph instance and if found, returns a pair containing the hash value associated with this edge, and the edge instance. If not found, returns #f.

lookup-edge:: FROM TO -> EDGE procedure

Given objects or node instances FROM and TO, looks up the corresponding edge in the graph and if found, returns the edge instance, #f otherwise.

Cluster operations

new-cluster:: NAME [nodes: NODE-LIST] [edges: EDGE-LIST] [subclusters: CLUSTER-LIST] -> CLUSTER procedure

Creates a new cluster instance in the current graph. The optional arguments can be used to supply a list of nodes, edges and subclusters that belong to this cluster. Returns the newly created cluster instance.

add-to-cluster:: CLUSTER OBJECT -> OBJECT procedure

Adds a node or an edge to the given cluster instance. If the given object is not a node or an edge instance, its hash is computed, and a new node is added to the graph and the cluster.

lookup-cluster:: NAME -> CLUSTER procedure

Looks up the given cluster name in the current graph and if found, returns the cluster instance, #f otherwise.

Operations with node and edge properties

new-property:: NAME TYPE CLUSTER [nodes-default: VALUE] [edges-default: VALUE] -> PROPERTY procedure

Registers a new property type in the current graph instance. TYPE is currently a Tulip property type, such as string or size. The optional arguments can be used to supply default values for this type of property. The default values are currently only used by the Tulip renderer.

set-node-property:: PROPERTY NODE VALUE -> PROPERTY procedure
set-edge-property:: PROPERTY EDGE VALUE -> PROPERTY procedure
reset-property:: PROPERTY -> PROPERTY procedure
set-label:: OBJECT VALUE -> PROPERTY procedure
label:: OBJECT -> LABEL procedure
lookup-property:: NAME -> PROPERTY procedure
lookup-node-property:: NAME NODE -> PROPERTY procedure
lookup-edge-property:: NAME EDGE -> PROPERTY procedure

Graph rendering

render-graph/tlp:: PORT -> UNDEFINED procedure

Outputs a textual description of the current graph in Tulip TLP format.

render-graph/dot:: PORT -> UNDEFINED procedure

Outputs a textual description of the current graph in GraphViz DOT format.

Examples

(use object-graph)

(reset-graph)
(register-node 'a)
(set-label 'a "Start")
(register-node 'b)
(register-node 'c)
(set-label 'c "Finish")


(register-edge 'a 'b)
(set-label (register-edge 'b 'c) "woo oho")

(register-edge 'b 'c)

(new-cluster "sniff" 
      nodes: (list (lookup-object-node 'a) (lookup-object-node 'c)) 
      edges: (list (lookup-edge 'b 'c)))
 
(new-cluster "puff")
 
(add-to-cluster (lookup-cluster "puff") (lookup-object-node 'a))
(add-to-cluster (lookup-cluster "puff") (lookup-object-node 'b))
 
(with-output-to-file "test.tlp"
  (lambda () (render-graph/tlp (current-output-port))))

About this egg

Author

Ivan Raikov

Version history

1.2
Support for edge labels in dot output [patch by Andrei Barbu]
1.1
Using assert in test script
1.0
Initial release

License

Copyright 2010-2011 Ivan Raikov and the Okinawa Institute of Science and Technology

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or (at
your option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

A full copy of the GPL license can be found at
<http://www.gnu.org/licenses/>.

Contents »