Description

Overview

This module provides a Perl interface to the amazing Graphviz, an open source graph visualization tool from AT&T.

It is called GraphViz2 so that pre-existing code using (the Perl module) GraphViz continues to work.

To avoid confusion, when I use GraphViz2 (note the capital V), I'm referring to this Perl module, and when I use Graphviz (lower-case v) I'm referring to the underlying tool (which is in fact a set of programs).

Version 1.00 of GraphViz2 is a complete re-write, by Ron Savage, of GraphViz V 2, which was written by Leon Brocard. The point of the re-write is to provide access to all the latest options available to users of Graphviz.

GraphViz2 V 1 is not backwards compatible with GraphViz V 2, despite the considerable similarity. It was not possible to maintain compatibility while extending support to all the latest features of Graphviz.

This option specifies how long to wait for the external program before exiting with an error.

The default is 10 (seconds).

This key is optional.

This key (global) is optional.

o graph => $hashref

The graph key points to a hashref which is used to set default attributes for graphs.

Hence, allowable keys and values within that hashref are anything supported by Graphviz.

The default is {}.

This key is optional.

o logger => $logger_object

Provides a logger object so $logger_object -> $level($message) can be called at certain times.

See "Why such a different approach to logging?" in the "FAQ" for details.

Retrieve and update the value with the logger() method.

The default is ''.

See also the verbose option, which can interact with the logger option.

This key is optional.

o node => $hashref

The node key points to a hashref which is used to set default attributes for nodes.

Hence, allowable keys and values within that hashref are anything supported by Graphviz.

The default is {}.

This key is optional.

o verbose => $Boolean

Provides a way to control the amount of output when a logger is not specified.

Setting verbose to 0 means print nothing.

Setting verbose to 1 means print the log level and the message to STDOUT, when a logger is not specified.

Retrieve and update the value with the verbose() method.

The default is 0.

See also the logger option, which can interact with the verbose option.

This key is optional.

Validating Parameters

The secondary keys (under the primary keys 'edge|graph|node') are checked against lists of valid attributes (stored at the end of this module, after the __DATA__ token, and made available using Data::Section::Simple).

This mechanism has the effect of hard-coding Graphviz options in the source code of GraphViz2.

Nevertheless, the implementation of these lists is handled differently from the way it was done in V 2.

V 3 ships with a set of scripts, scripts/extract.*.pl, which retrieve pages from the Graphviz web site and extract the current lists of valid attributes. These are then copied manually into the source code of GraphViz2, meaning any time those lists change on the Graphviz web site, it's a trivial matter to update the lists stored within this module.

These attributes are pushed onto a scope stack during new()'s processing of its parameters, and they apply thereafter until changed. They are the 'current' attributes. They live at scope level 0 (zero).

You change the 'current' attributes by calling any of the methods default_edge(%hash), default_graph(%hash) and default_node(%hash).

Subgraph Scope

When you wish to create a subgraph, you call push_subgraph(%hash). The word push emphasises that you are moving into a new scope, and that the default attributes for the new scope are pushed onto the scope stack.

This module, as with Graphviz, defaults to using inheritance of attributes.

That means the parent's 'current' attributes are combined with the parameters to push_subgraph(%hash) to generate a new set of 'current' attributes for each of the graphical elements, graph, node and edge.

After a single call to push_subgraph(%hash), these 'current' attributes will live a level 1 in the scope stack.

If either of these node names is unknown, add_node(name => $node_name) is called automatically. The lack of attributes in this call means such nodes are created with the default set of attributes, and that may not be what you want. To avoid this, you have to call add_node(...) yourself, with the appropriate attributes, before calling add_edge(...).

$label defaults to the value supplied in the call to new(global => {label => '...'}), which in turn defaults to '->' for directed graphs and '--' for undirected graphs. You wouldn't normally need to use this option.

%hash is any edge attributes accepted as Graphviz attributes. These are validated in exactly the same way as the edge parameters in the calls to default_edge(%hash), new(edge => {}) and push_subgraph(edge => {}).

%hash is any node attributes accepted as Graphviz attributes. These are validated in exactly the same way as the node parameters in the calls to default_node(%hash), new(node => {}) and push_subgraph(node => {}).

The attribute name 'label' may point to a string or an arrayref. If it is an arrayref:

o Each element is treated as a label

o Each label is given a port number (1 .. N)

o Each label + port appears in a separate, small, rectangle

o These rectangles are combined into a single node

o The shape of this node is forced to be a record

o Judicious use of '{' and '}' in the label can make this record appear horizontally or vertically, and even nested

name => $name is the name to assign to the subgraph. Name defaults to ''.

So, without $name, 'subgraph {' is written to the output stream.

With $name, "subgraph $name {" is written to the output stream.

Note that subgraph names beginning with 'cluster' are special to Graphviz.

edge => {...} is any edge attributes accepted as Graphviz attributes. These are validated in exactly the same way as the edge parameters in the calls to default_edge(%hash), new(edge => {}) and push_subgraph(edge => {}).

graph => {...} is any graph attributes accepted as Graphviz attributes. These are validated in exactly the same way as the graph parameters in the calls to default_graph(%hash), new(graph => {}) and push_subgraph(graph => {}).

node => {...} is any node attributes accepted as Graphviz attributes. These are validated in exactly the same way as the node parameters in the calls to default_node(%hash), new(node => {}) and push_subgraph(node => {}).

Author

Copyright

Australian copyright (c) 2011, Ron Savage.

All Programs of mine are 'OSI Certified Open Source Software';
you can redistribute them and/or modify them under the terms of
The Artistic License, a copy of which is available at:
http://www.opensource.org/licenses/index.html