GraphViz2(3)

NAME
GraphViz2 - A wrapper for AT&T's Graphviz

Synopsis

  Sample output
Unpack the distro and copy html/*.html and html/*.svg to your web server's doc root directory.

Then, point your browser at 127.0.0.1/index.html.

Or, hit <http://savage.net.au/Perl-modules/html/graphviz2/index.html>.

  Perl code
        #!/usr/bin/env perl

        use strict;
        use warnings;

        use File::Spec;

        use GraphViz2;

        use Log::Handler;

        # ---------------

        my($logger) = Log::Handler -> new;

        $logger -> add
                (
                 screen =>
                 {
                         maxlevel       => 'debug',
                         message_layout => '%m',
                         minlevel       => 'error',
                 }
                );

        my($graph) = GraphViz2 -> new
                (
                 edge   => {color => 'grey'},
                 global => {directed => 1},
                 graph  => {label => 'Adult', rankdir => 'TB'},
                 logger => $logger,
                 node   => {shape => 'oval'},
                );

        $graph -> add_node(name => 'Carnegie', shape => 'circle');
        $graph -> add_node(name => 'Murrumbeena', shape => 'box', color => 'green');
        $graph -> add_node(name => 'Oakleigh',    color => 'blue');

        $graph -> add_edge(from => 'Murrumbeena', to    => 'Carnegie', arrowsize => 2);
        $graph -> add_edge(from => 'Murrumbeena', to    => 'Oakleigh', color => 'brown');

        $graph -> push_subgraph
        (
         name  => 'cluster_1',
         graph => {label => 'Child'},
         node  => {color => 'magenta', shape => 'diamond'},
        );

        $graph -> add_node(name => 'Chadstone', shape => 'hexagon');
        $graph -> add_node(name => 'Waverley', color => 'orange');

        $graph -> add_edge(from => 'Chadstone', to => 'Waverley');

        $graph -> pop_subgraph;

        $graph -> default_node(color => 'cyan');

        $graph -> add_node(name => 'Malvern');
        $graph -> add_node(name => 'Prahran', shape => 'trapezium');

        $graph -> add_edge(from => 'Malvern', to => 'Prahran');
        $graph -> add_edge(from => 'Malvern', to => 'Murrumbeena');

        my($format)      = shift || 'svg';
        my($output_file) = shift || File::Spec -> catfile('html', "sub.graph.$format");

        $graph -> run(format => $format, output_file => $output_file);

This program ships as scripts/sub.graph.pl. See "Scripts Shipped with this Module".

Description

  Overview
This module provides a Perl interface to the amazing Graphviz <http://www.graphviz.org/>, 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 <http://www.graphviz.org/> (lower-case v) I'm referring to the underlying tool (which is in fact a set of programs).

This version of GraphViz2 targets V 2.23.6+ of Graphviz <http://www.graphviz.org/>.

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 <http://www.graphviz.org/>.

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 <http://www.graphviz.org/>.

To ensure GraphViz2 is a light-weight module, Hash::FieldHash has been used to provide getters and setters, rather than Moose.

  What is a Graph?
An undirected graph is a collection of nodes optionally linked together with edges.

A directed graph is the same, except that the edges have a direction, normally indicated by an arrow head.

A quick inspection of Graphviz <http://www.graphviz.org/>'s gallery <http://www.graphviz.org/Gallery.php> will show better than words just how good Graphviz <http://www.graphviz.org/> is, and will reinforce the point that humans are very visual creatures.

Distributions
This module is available as a Unix-style distro (*.tgz).

See <http://savage.net.au/Perl-modules/html/installing-a-module.html> for help on unpacking and installing distros.

Installation
Install GraphViz2 as you would for any "Perl" module:

Run:

        cpanm GraphViz2

or run:

        sudo cpan GraphViz2

or unpack the distro, and then either:

        perl Build.PL
        ./Build
        ./Build test
        sudo ./Build install

or:

        perl Makefile.PL
        make (or dmake or nmake)
        make test
        make install

Constructor and Initialization

  Calling new()
"new()" is called as "my($obj) = GraphViz2 -> new(k1 => v1, k2 => v2, ...)".

It returns a new object of type "GraphViz2".

Key-value pairs accepted in the parameter list:

o edge => $hashref
    The edge key points to a hashref which is used to set default attributes for edges.

    Hence, allowable keys and values within that hashref are anything supported by Graphviz <http://www.graphviz.org/>.

    The default is {}.

    This key is optional.

o global => $hashref
    The global key points to a hashref which is used to set attributes for the output stream.

    Valid keys within this hashref are:

    o directed => $Boolean
        This option affects the content of the output stream.

        directed => 1 outputs 'digraph name {...}', while directed => 0 outputs 'graph name {...}'.

        At the Perl level, directed graphs have edges with arrow heads, such as '->', while undirected graphs have unadorned edges, such as '--'.

        The default is 0.

        This key is optional.

    o driver => $program_name
        This option specifies which external program to run to process the output stream.

        The default is to use File::Which's which() method to find the 'dot' program.

        This key is optional.

    o format => $string
        This option specifies what type of output file to create.

        The default is 'svg'.

        Output formats of the form 'png:gd' etc are also supported, but only the component before the first ':' is validated by GraphViz2.

        This key is optional.

    o label => $string
        This option specifies what an edge looks like: '->' for directed graphs and '--' for undirected graphs.

        You wouldn't normally need to use this option.

        The default is '->' if directed is 1, and '--' if directed is 0.

        This key is optional.

    o name => $string
        This option affects the content of the output stream.

        name => 'G666' outputs 'digraph G666 {...}'.

        The default is 'Perl' :-).

        This key is optional.

    o record_orientation => /^(?:horizontal|vertical)$/
        This option affects how records are plotted. The value must be 'horizontal' or 'vertical'.

        The default is 'vertical', which suits GraphViz2::DBI.

    o record_shape => /^(?:M?record)$/
        This option affects the shape of records. The value must be 'Mrecord' or 'record'.

        Mrecords have nice, rounded corners, whereas plain old records have square corners.

        The default is 'Mrecord'.

        See Record shapes <http://www.graphviz.org/content/node-shapes#record> for details.

    o strict => $Boolean
        This option affects the content of the output stream.

        strict => 1 outputs 'strict digraph name {...}', while strict => 0 outputs 'digraph name {...}'.

        The default is 0.

        This key is optional.

    o timeout => $integer
        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 <http://www.graphviz.org/>.

    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 <http://www.graphviz.org/>.

    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 <http://www.graphviz.org/> 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 <http://www.graphviz.org/> 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 <http://www.graphviz.org/> web site, it's a trivial matter to update the lists stored within this module.

See "Scripts Shipped with this Module" in GraphViz2.

Attribute Scope

  Graph Scope
The graphical elements graph, node and edge, have attributes. Attributes can be set when calling new().

Within new(), the defaults are graph => {}, node => {}, and edge => {}.

You override these with code such as new(edge => {color => 'red'}).

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

See scripts/trivial.pl ("Scripts Shipped with this Module" in GraphViz2) for an example.

  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 <http://www.graphviz.org/>, 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.

See scripts/sub.graph.pl ("Scripts Shipped with this Module" in GraphViz2) for an example.

Another call to push_subgraph(%hash), without an intervening call to pop_subgraph(), will repeat the process, leaving you with a set of attributes at level 2 in the scope stack.

Both GraphViz2 and Graphviz <http://www.graphviz.org/> handle this situation properly.

See scripts/sub.sub.graph.pl ("Scripts Shipped with this Module" in GraphViz2) for an example.

At the moment, due to design defects (IMHO) in the underlying Graphviz <http://www.graphviz.org/> logic, there are some tiny problems with this:

o A global frame
    I can't see how to make the graph at level 0 in the scope stack have a frame.

o Frame color
    When you specify graph => {color => 'red'} at the parent level, the subgraph has a red frame.

    I think a subgraph should control its own frame.

o Parent and child frames
    When you specify graph => {color => 'red'} at the subgraph level, both that subgraph and it children have red frames.

    This contradicts what happens at the global level, in that specifying color there does not given the whole graph a frame.

o Frame visibility
    A subgraph is currently forced to have a frame, unless you rig it by specifying a color the same as the background.

I've posted an email to the Graphviz <http://www.graphviz.org/> mailing list suggesting a new option, framecolor, so deal with this issue, including a special color of 'invisible'.

I'm using V 2.26.3 of Graphviz <http://www.graphviz.org/> as I write this (2011-06-06).

Methods

  add_edge(from => $from_node_name, to => $to_node_name, [label => $label, %hash])
Adds an edge to the graph.

Returns $self to allow method chaining.

Here, [] indicate optional parameters.

Add a edge from 1 node to another.

$from_node_name and $to_node_name default to ''.

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 <http://www.graphviz.org/content/attrs>. 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 => {}).

  add_node(name => $node_name, [%hash])
Adds a node to the graph.

Returns $self to allow method chaining.

If you want to embed newlines or double-quotes in node names or labels, see scripts/quote.pl in "Scripts Shipped with this Module" in GraphViz2.

If you want anonymous nodes, see scripts/anonymous.pl in "Scripts Shipped with this Module" in GraphViz2.

Here, [] indicates an optional parameter.

%hash is any node attributes accepted as Graphviz attributes <http://www.graphviz.org/content/attrs>. 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

For more details on this complex topic, see Records <http://www.graphviz.org/content/node-shapes#record> and Ports <http://www.graphviz.org/content/attrs#kportPos>.

  default_edge(%hash)
Sets defaults attributes for edges added subsequently.

Returns $self to allow method chaining.

%hash is any edge attributes accepted as Graphviz attributes <http://www.graphviz.org/content/attrs>. These are validated in exactly the same way as the edge parameters in the calls to new(edge => {}) and push_subgraph(edge => {}).

  default_graph(%hash)
Sets defaults attributes for the graph.

Returns $self to allow method chaining.

%hash is any graph attributes accepted as Graphviz attributes <http://www.graphviz.org/content/attrs>. These are validated in exactly the same way as the graph parameter in the calls to new(graph => {}) and push_subgraph(graph => {}).

  default_node(%hash)
Sets defaults attributes for nodes added subsequently.

Returns $self to allow method chaining.

%hash is any node attributes accepted as Graphviz attributes <http://www.graphviz.org/content/attrs>. These are validated in exactly the same way as the node parameters in the calls to new(node => {}) and push_subgraph(node => {}).

  dot_input()
Returns the output stream, formatted nicely, which was passed to the external program (e.g. dot).

You must call run() before calling dot_input(), since it is only during the call to run() that the output stream is stored in the buffer controlled by dot_input().

  dot_output()
Returns the output from calling the external program (e.g. dot).

You must call run() before calling dot_output(), since it is only during the call to run() that the output of the external program is stored in the buffer controlled by dot_output().

This output is available even if run() does not write the output to a file.

  load_valid_attributes()
Load various sets of valid attributes from within the source code of this module, using Data::Section::Simple.

Returns $self to allow method chaining.

These attributes are used to validate attributes in many situations.

You wouldn't normally need to use this method.

  sub log([$level, $message])
Logs the message at the given log level.

Returns $self to allow method chaining.

Here, [] indicate optional parameters.

$level defaults to 'debug', and $message defaults to ''.

If called with $level eq 'error', it dies with $message.

  logger($logger_object])
Gets or sets the log object.

Here, [] indicates an optional parameter.

  pop_subgraph()
Pop off and discard the top element of the scope stack.

Returns $self to allow method chaining.

  push_subgraph([name => $name, edge => {...}, graph => {...}, node => {...}])
Sets up a new subgraph environment.

Returns $self to allow method chaining.

Here, [] indicate optional parameters.

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 <http://www.graphviz.org/>.

edge => {...} is any edge attributes accepted as Graphviz attributes <http://www.graphviz.org/content/attrs>. 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 <http://www.graphviz.org/content/attrs>. 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 <http://www.graphviz.org/content/attrs>. 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 => {}).

  report_valid_attributes()
Prints all attributes known to this module.

Returns nothing.

You wouldn't normally need to use this method.

See scripts/report.valid.attributes.pl. See "Scripts Shipped with this Module" in GraphViz2.

  run([driver => $exe, format => $string, timeout => $integer, output_file => $output_file])
Runs the given program to process the output stream.

Returns $self to allow method chaining.

Here, [] indicate optional parameters.

$driver is the name of the external program to run.

It defaults to the value supplied in the call to new(global => {driver => '...'}), which in turn defaults to File::Which's which('dot') return value.

$format is the type of output file to write.

It defaults to the value supplied in the call to new(global => {format => '...'}), which in turn defaults to 'svg'.

$timeout is the time in seconds to wait while the external program runs, before dieing with an error.

It defaults to the value supplied in the call to new(global => {timeout => '...'}), which in turn defaults to 10.

$output_file is the name of the file into which the output from the external program is written.

Perl's binmode is called on this file.

There is no default value for $output_file. If a value is not supplied for $output_file, the only way to recover the output of the external program is to call dot_output().

This method performs a series of tasks:

o Formats the output stream
o Stores the formatted output in a buffer controlled by the dot_input() method
o Output the output stream to a file
o Run the chosen external program on that file
o Capture STDOUT and STDERR from that program
o Die if STDERR contains anything
o Copies STDOUT to the buffer controlled by the dot_output() method
o Write the captured contents of STDOUT to $output_file, if $output_file has a value

  stringify_attributes($context, $option, $bracket)
Returns a string suitable to writing to the output stream.

$context is one of 'edge', 'graph', 'node', or a special string. See the code for details.

You wouldn't normally need to use this method.

  validate_params($context, %attributes)
Validate the given attributes within the given context.

Returns $self to allow method chaining.

$context is one of 'edge', 'global', 'graph', 'node' or 'output_format'.

You wouldn't normally need to use this method.

  verbose([$integer])
Gets or sets the verbosity level, for when a logging object is not used.

Here, [] indicates an optional parameter.

FAQ

  o How do I print output files?
Under Unix, output as PDF, and then try: lp -o fitplot html/parse.marpa.pdf.

  o I'm having trouble with special characters in node names and labels
GraphViz2 escapes these characters in those contexts: []{}.

Double-quotes are escaped when the label is not an HTML label. See scripts/html.labels.pl for sample code using font color.

It would be nice to also escape | and <, but these characters are used in specifying ports in records.

See the next point for details.

  A warning about Graphviz <http://www.graphviz.org/> and ports
Ports are what Graphviz <http://www.graphviz.org/> calls those places on the outline of a node where edges leave and terminate.

The Graphviz <http://www.graphviz.org/> syntax for ports is a bit unusual:

o This works: "node_name":port5
o This doesn't: "node_name:port5"

You don't have to quote all node names in Graphviz <http://www.graphviz.org/>, but some, such as digits, must be quoted, so I've decided to quote them all.

  Why does GraphViz plot top-to-bottom but GraphViz2::Parse::ISA plot bottom-to-top?
Because the latter knows the data is a class structure. The former makes no assumptions about the nature of the data.

  I'm having trouble with ports
The code in GraphViz2's add_edge() method assumes my convention that port names match /:port\d{1,}/.

This matches the code in the add_node() method, where port names are generated.

If you adopt this convention, you should have no problems.

  What happened to GraphViz::No?
The default_node(%hash) method in GraphViz2 allows you to make nodes vanish.

Try: $graph -> default_node(label => '', height => 0, width => 0, style => 'invis');

Because that line is so simple, I feel it's unnecessary to make a subclass of GraphViz2.

  What happened to GraphViz::Regex?
See GraphViz2::Parse::Regexp.

  What happened to GraphViz::Small?
The default_node(%hash) method in GraphViz2 allows you to make nodes which are small.

Try: $graph -> default_node(label => '', height => 0.2, width => 0.2, style => 'filled');

Because that line is so simple, I feel it's unnecessary to make a subclass of GraphViz2.

  What happened to GraphViz::XML?
Use GraphViz2::Parse::XML instead, which uses the pure-Perl XML::Tiny.

Alternately, see "Scripts Shipped with this Module" in GraphViz2 for how to use XML::Bare, GraphViz2 and GraphViz2::Data::Grapher instead.

See "scripts/parse.xml.pp.pl" or "scripts/parse.xml.bare.pl" below.

  GraphViz returned a node name from add_node() when given an anonymous node. What does GraphViz2 do?
You can give the node a name, and an empty string for a label, to suppress plotting the name.

See "scripts/anonymous.pl" for demo code.

If there is some specific requirement which this does not cater for, let me know and I can change the code.

  Why such a different approach to logging?
As you can see from scripts/*.pl, I always use Log::Handler.

By default (i.e. without a logger object), GraphViz2 prints warning and debug messages to STDOUT, and dies upon errors.

However, by supplying a log object, you can capture these events.

Not only that, you can change the behaviour of your log object at any time, by calling "logger($logger_object)".

  A Note about XML Containers
The 2 demo programs "scripts/parse.html.pl" and "scripts/parse.xml.bare.pl", which both use XML::Bare, assume your XML has a single parent container for all other containers. The programs use this container to provide a name for the root node of the graph.

  Why did you choose Hash::FieldHash over Moose?
My policy is to use Hash::FieldHash for stand-alone modules and Moose for applications.

Scripts Shipped with this Module

  scripts/anonymous.pl
Demonstrates empty strings for node names and labels.

Outputs to ./html/anonymous.svg by default.

  scripts/cluster.pl
Demonstrates building a cluster as a subgraph.

Outputs to ./html/cluster.svg by default.

See also scripts/macro.*.pl below.

  scripts/dbi.schema.pl
If the environment vaiables DBI_DSN, DBI_USER and DBI_PASS are set (the latter 2 are optional), then this demonstrates building a graph from a database schema.

Outputs to ./html/dbi.schema.svg by default.

  scripts/dependency.pl
Demonstrates graphing an Algorithm::Dependency source.

Outputs to ./html/dependency.svg by default.

The default for GraphViz2 is to plot from the top to the bottom. This is the opposite of GraphViz2::Parse::ISA.

See also parse.isa.pl below.

  scripts/extract.arrow.shapes.pl
Downloads the arrow shapes from Graphviz's Arrow Shapes <http://www.graphviz.org/content/arrow-shapes> and outputs them to ./data/arrow.shapes.html. Then it extracts the reserved words into ./data/arrow.shapes.dat.

  scripts/extract.attributes.pl
Downloads the attributes from Graphviz's Attributes <http://www.graphviz.org/content/attrs> and outputs them to ./data/attributes.html. Then it extracts the reserved words into ./data/attributes.dat.

  scripts/extract.node.shapes.pl
Downloads the node shapes from Graphviz's Node Shapes <http://www.graphviz.org/content/node-shapes> and outputs them to ./data/node.shapes.html. Then it extracts the reserved words into ./data/node.shapes.dat.

  scripts/extract.output.formats.pl
Downloads the output formats from Graphviz's Output Formats <http://www.graphviz.org/content/output-formats> and outputs them to ./data/output.formats.html. Then it extracts the reserved words into ./data/output.formats.dat.

  scripts/generate.demo.pl
Run by scripts/generate.svg.sh. See next point.

  scripts/generate.png.sh
See scripts/generate.svg.sh for details.

Outputs to /tmp by default.

  scripts/generate.svg.sh
A bash script to run all the scripts and generate the *.svg and *.log files, in ./html.

You can them copy html/*.html and html/*.svg to your web server's doc root, for viewing.

Outputs to /tmp by default.

  scripts/Heawood.pl
Demonstrates the transitive 6-net, also known as Heawood's graph.

Outputs to ./html/Heawood.svg by default.

This program was reverse-engineered from graphs/undirected/Heawood.gv in the distro for Graphviz <http://www.graphviz.org/> V 2.26.3.

  scripts/html.labels.pl
Demonstrates a trivial 3-node graph, with colors and HTML labels.

Outputs to ./html/html.labels.svg by default.

  scripts/macro.1.pl
Demonstrates non-cluster subgraphs via a macro.

Outputs to ./html/macro.1.svg by default.

  scripts/macro.2.pl
Demonstrates linked non-cluster subgraphs via a macro.

Outputs to ./html/macro.2.svg by default.

  scripts/macro.3.pl
Demonstrates cluster subgraphs via a macro.

Outputs to ./html/macro.3.svg by default.

  scripts/macro.4.pl
Demonstrates linked cluster subgraphs via a macro.

Outputs to ./html/macro.4.svg by default.

  scripts/macro.5.pl
Demonstrates compound cluster subgraphs via a macro.

Outputs to ./html/macro.5.svg by default.

  scripts/parse.data.pl
Demonstrates graphing a Perl data structure.

Outputs to ./html/parse.data.svg by default.

  scripts/parse.html.pl
Demonstrates using XML::Bare to parse HTML.

Inputs from ./t/sample.html, and outputs to ./html/parse.html.svg by default.

  scripts/parse.isa.pl
Demonstrates graphing a Perl class hierarchy.

Outputs to ./html/parse.isa.svg by default.

The default for GraphViz2::Parse::ISA is to plot from the bottom to the top (Grandchild to Parent). This is the opposite of GraphViz2.

See also dependency.pl, above.

  scripts/parse.marpa.pl
Demonstrates graphing a Marpa-style grammar.

Inputs from t/sample.marpa.1 and outputs to ./html/parse.marpa.svg by default.

The input grammar was extracted from Graph::Easy::Marpa::Parser V 0.70, before the grammar supported Graph::Easy's groups.

  scripts/parse.recdescent.pl
Demonstrates graphing a Parse::RecDescent-style grammar.

Inputs from t/sample.recdescent.1.dat and outputs to ./html/parse.recdescent.svg by default.

The input grammar was extracted from t/basics.t in Parse::RecDescent V 1.965001.

You can patch the *.pl to read from t/sample.recdescent.2.dat, which was copied from a V 2 bug report <https://rt.cpan.org/Ticket/Display.html?id=36057>.

  scripts/parse.regexp.pl
Demonstrates graphing a Perl regular expression.

Outputs to ./html/parse.regexp.svg by default.

  scripts/parse.stt.pl
Demonstrates graphing a Set::FA::Element-style state transition table.

Inputs from t/sample.stt.1.dat and outputs to ./html/parse.stt.svg by default.

The input grammar was extracted from Set::FA::Element.

You can patch the *.pl to read from t/sample.stt.2.dat, which was output by Graph::Easy::Marpa::DFA V 0.70.

  scripts/parse.yacc.pl
Demonstrates graphing a byacc <http://invisible-island.net/byacc/byacc.html>-style grammar.

Inputs from t/calc3.output, and outputs to ./html/parse.yacc.svg by default.

The input was copied from test/calc3.y in byacc V 20101229 and process as below.

Note: The version downloadable via HTTP is 20101127.

I installed byacc like this:

        sudo apt-get byacc

Now get a sample file to work with:

        cd ~/Downloads
        curl ftp://invisible-island.net/byacc/byacc.tar.gz > byacc.tar.gz
        tar xvzf byacc.tar.gz
        cd ~/perl.modules/GraphViz2
        cp ~/Downloads/byacc-20101229/test/calc3.y t
        byacc -v t/calc3.y
        mv y.output t/calc3.output
        diff ~/Downloads/byacc-20101229/test/calc3.output t/calc3.output
        rm y.tab.c

It's the file calc3.output which ships in the t/ directory.

  scripts/parse.yapp.pl
Demonstrates graphing a Parse::Yapp-style grammar.

Inputs from t/calc.output, and outputs to ./html/parse.yapp.svg by default.

The input was copied from t/calc.t in Parse::Yapp's and processed as below.

I installed Parse::Yapp (and yapp) like this:

        cpanm Parse::Yapp

Now get a sample file to work with:

        cd ~/perl.modules/GraphViz2
        cp ~/.cpanm/latest-build/Parse-Yapp-1.05/t/calc.t t/calc.input

Edit t/calc.input to delete the code, leaving the grammar after the __DATA__token.

        yapp -v t/calc.input > t/calc.output
        rm t/calc.pm

It's the file calc.output which ships in the t/ directory.

  scripts/parse.xml.bare.pl
Demonstrates using XML::Bare to parse XML.

Inputs from ./t/sample.xml, and outputs to ./html/parse.xml.bare.svg by default.

  scripts/parse.xml.pp.pl
Demonstrates using XML::Tiny to parse XML.

Inputs from ./t/sample.xml, and outputs to ./html/parse.xml.pp.svg by default.

  scripts/quote.pl
Demonstrates embedded newlines and double-quotes in node names and labels.

It also demonstrates that the justification escapes, \l and \r, work too, sometimes.

Outputs to ./html/quote.svg by default.

Tests which run dot directly show this is a bug in Graphviz <http://www.graphviz.org/> itself.

For example, in this graph, it looks like \r only works after \l (node d), but not always (nodes b, c).

Call this x.dot:

        digraph G {
                rankdir=LR;
                node [shape=oval];
                a [ label ="a: Far, far, Left\rRight"];
                b [ label ="\lb: Far, far, Left\rRight"];
                c [ label ="XXX\lc: Far, far, Left\rRight"];
                d [ label ="d: Far, far, Left\lRight\rRight"];
        }

and use the command:

        dot -Tsvg x.dot

See the Graphviz docs <http://www.graphviz.org/content/attrs#kescString> for escString, where they write 'l to mean \l, for some reason.

  scripts/report.valid.attributes.pl
Prints all current (V 2.23.6) Graphviz <http://www.graphviz.org/> attributes, along with a few global ones I've invented for the purpose of writing this module.

Outputs to STDOUT.

  scripts/sub.graph.pl
Demonstrates a graph combined with a subgraph.

Outputs to ./html/sub.graph.svg by default.

  scripts/sub.sub.graph.pl
Demonstrates a graph combined with a subgraph combined with a subsubgraph.

Outputs to ./html/sub.sub.graph.svg by default.

  scripts/trivial.pl
Demonstrates a trivial 3-node graph, with colors, just to get you started.

Outputs to ./html/trivial.svg by default.

TODO

o Does GraphViz2 need to emulate the sort option in GraphViz?
    That depends on what that option really does.

o Handle edges such as 1 -> 2 -> {A B}, as seen in Graphviz <http://www.graphviz.org/>'s graphs/directed/switch.gv
    But how?

o Validate parameters more carefully, e.g. to reject non-hashref arguments where appropriate
    Some method parameter lists take keys whose value must be a hashref.

A Extremely Short List of Other Graphing Software
Axis Maps <http://www.axismaps.com/>.

Polygon Map Generation <http://www-cs-students.stanford.edu/~amitp/game-programming/polygon-map-generation/>. Read more on that here <http://blogs.perl.org/users/max_maischein/2011/06/display-your-data---randompoissondisc.html>.

Voronoi Applications <http://www.voronoi.com/wiki/index.php?title=Voronoi_Applications>.

Thanks
Many thanks are due to the people who chose to make Graphviz <http://www.graphviz.org/> Open Source.

And thanks to Leon Brocard <http://search.cpan.org/~lbrocard/>, who wrote GraphViz, and kindly gave me co-maint of the module.

Version Numbers
Version numbers < 1.00 represent development versions. From 1.00 up, they are production versions.

Machine-Readable Change Log
The file CHANGES was converted into Changelog.ini by Module::Metadata::Changes.

Support
Email the author, or log a bug on RT:

<https://rt.cpan.org/Public/Dist/Display.html?Name=GraphViz2>.

Author
GraphViz2 was written by Ron Savage <ron@savage.net.au> in 2011.

Home page: <http://savage.net.au/index.html>.

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