object-graph (historical revision 20153)

You are looking at historical revision 20153 of this page. It may differ significantly from its current revision.

object-graph

Graph description generator for graphs of arbitrary Scheme objects.

object-graph
Usage
Documentation
1. Library procedures
Examples
About this egg

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

[procedure] reset-graph:: UNDEFINED -> UNDEFINED

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

[procedure] register-node:: OBJECT -> NODE

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

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

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

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

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

Node and edge lookup operations

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

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.

[procedure] lookup-node:: NODE -> NODE

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

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

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

[procedure] assoc-edge:: EDGE -> EDGE

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.

[procedure] lookup-edge:: FROM TO -> EDGE

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

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

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.

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

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.

[procedure] lookup-cluster:: NAME -> CLUSTER

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

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

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.

[procedure] 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

Graph rendering

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

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

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

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

1.0: Initial release

License

Copyright 2010 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/>.

object-graph

Usage

Documentation