/ 
GraphViz2-2.56
River stage two • 22 direct dependents • 24 total dependents
⭐ Starred 12 GitHub stars
/ README.md

NAME

GraphViz2 - A wrapper for AT&T's Graphviz

Synopsis

Sample output

See https://graphviz-perl.github.io/.

Perl code

Typical Usage

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

Image Maps Usage

As of V 2.43, GraphViz2 supports image maps, both client and server side.

See "Image Maps" below.

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.

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

As of V 2.43, GraphViz2 supports image maps, both client and server side.

See "Image Maps" below.

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's gallery will show better than words just how good Graphviz is, and will reinforce the point that humans are very visual creatures.

Installation

Of course you need to install AT&T's Graphviz before using this module. See http://www.graphviz.org/download/.

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:

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

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, 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 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 logic, there are some tiny problems with this:

Also, check the pencolor docs for how the color of the frame is chosen by cascading thru a set of options.

I've posted an email to the Graphviz mailing list suggesting a new option, framecolor, so deal with this issue, including a special color of 'invisible'.

Image Maps

As of V 2.43, GraphViz2 supports image maps, both client and server side.

The Default URL

See the Graphviz docs for 'cmapx'.

Their sample code has a dot file - x.gv - containing this line:

    URL="http://www.research.att.com/base.html";

The way you set such a url in GraphViz2 is via a new parameter to new(). This parameter is called im_meta and it takes a hashref as a value. Currently the only key used within that hashref is the case-sensitive URL.

Thus you must do this to set a URL:

    my($graph) = GraphViz2 -> new
                 (
                    ...
                    im_meta =>
                    {
                        URL => 'http://savage.net.au/maps/demo.3.1.html', # Note: URL must be in caps.
                    },
                 );

See maps/demo.3.pl and maps/demo.4.pl for sample code.

Typical Code

Normally you would call run() as:

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

That line was copied from scripts/cluster.pl.

To trigger image map processing, you must include 2 new parameters:

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

That line was copied from maps/demo.3.pl, and there is an identical line in maps/demo.4.pl.

The New Parameters to run()

Sample Code

Various demos are shipped in the new maps/ directory:

Each demo, when FTPed to your web server displays some text with an image in the middle. In each case you can click on the upper oval to jump to one page, or click on the lower oval to jump to a different page, or click anywhere else in the image to jump to a third page.

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

%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 => {}).

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. 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 a string...

The string is the label.

The string may contain ports and orientation markers ({}).

If it is an arrayref of strings...

If it is an arrayref of hashrefs...

See scripts/html.labels.*.pl and scripts/record.*.pl for sample code.

See also "How labels interact with ports".

For more details on this complex topic, see Records and Ports.

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. 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. 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. These are validated in exactly the same way as the node parameters in the calls to new(node => {}) and push_subgraph(node => {}).

default_subgraph(%hash)

Sets defaults attributes for clusters and subgraphs.

Returns $self to allow method chaining.

%hash is any cluster or subgraph attribute accepted as Graphviz attributes. These are validated in exactly the same way as the subgraph parameter in the calls to new(subgraph => {}) and push_subgraph(subgraph => {}).

dot_input()

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

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.

edge_hash()

Returns, at the end of the run, a hashref keyed by node name, specifically the node at the arrow_tail_ end of the hash, i.e. where the edge starts from.

Use this to get a list of all nodes and the edges which leave those nodes, the corresponding destination nodes, and the attributes of each edge.

    my($node_hash) = $graph -> node_hash;
    my($edge_hash) = $graph -> edge_hash;

    for my $from (sort keys %$node_hash)
    {
            my($attr) = $$node_hash{$from}{attributes};
            my($s)    = join(', ', map{"$_ => $$attr{$_}"} sort keys %$attr);

            print "Node: $from\n";
            print "\tAttributes: $s\n";

            for my $to (sort keys %{$$edge_hash{$from} })
            {
                    for my $edge (@{$$edge_hash{$from}{$to} })
                    {
                            $attr = $$edge{attributes};
                            $s    = join(', ', map{"$_ => $$attr{$_}"} sort keys %$attr);

                            print "\tEdge: $from$$edge{from_port} -> $to$$edge{to_port}\n";
                            print "\t\tAttributes: $s\n";
                    }
            }
    }

If the caller adds the same edge two (or more) times, the attributes from each call are not coalesced (unlike "node_hash()"), but rather the attributes from each call are stored separately in an arrayref.

A bit more formally then, $$edge_hash{$from_node}{$to_node} is an arrayref where each element describes one edge, and which defaults to:

    {
            attributes => {},
            from_port  => $from_port,
            to_port    => $to_port,
    }

If from_port is not provided by the caller, it defaults to '' (the empty string). If it is provided, it contains a leading ':'. Likewise for to_port.

See scripts/report.nodes.and.edges.pl (a version of scripts/html.labels.1.pl) for a complete example.

escape_some_chars($s)

Escapes various chars in various circumstances, because some chars are treated specially by Graphviz.

See "Special characters in node names and labels" for a discussion of this tricky topic.

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.

node_hash()

Returns, at the end of the run, a hashref keyed by node name. Use this to get a list of all nodes and their attributes.

    my($node_hash) = $graph -> node_hash;

    for my $name (sort keys %$node_hash)
    {
            my($attr) = $$node_hash{$name}{attributes};
            my($s)    = join(', ', map{"$_ => $$attr{$_}"} sort keys %$attr);

            print "Node: $name\n";
            print "\tAttributes: $s\n";
    }

If the caller adds the same node two (or more) times, the attributes from each call are coalesced (unlike "edge_hash()"), meaning all attributes from all calls are combined under the attributes sub-key.

A bit more formally then, $$node_hash{$node_name} is a hashref where each element describes one node, and which defaults to:

    {
            attributes => {},
    }

See scripts/report.nodes.and.edges.pl (a version of scripts/html.labels.1.pl) for a complete example, including usage of the corresponding "edge_hash()" method.

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 => {...}, subgraph => {...}])

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.

See scripts/rank.sub.graph.[1234].pl for the effect of various values for $name.

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 => {}).

subgraph => {..} is for setting attributes applicable to clusters and subgraphs.

Currently the only subgraph attribute is rank, but clusters have many attributes available.

See the second column of the Graphviz attribute docs for details.

A typical usage would be push_subgraph(subgraph => {rank => 'same'}) so that all nodes mentioned within the subgraph are constrained to be horizontally aligned.

See scripts/rank.sub.graph.[12].pl and scripts/sub.graph.frames.pl for sample code.

valid_attributes()

Returns a hashref of all attributes known to this module, keyed by type to hashrefs to true values.

Stored in this module, using Data::Section::Simple.

These attributes are used to validate attributes in many situations.

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.

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:

stringify_attributes($context, $option)

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.

Also, if $context is 'subgraph', attributes are allowed to be in the 'cluster' context.

Returns $self to allow method chaining.

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

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.

MISC

Graphviz version supported

GraphViz2 targets V 2.34.0 of Graphviz.

This affects the list of available attributes per graph item (node, edge, cluster, etc) available.

See the second column of the Graphviz attribute docs for details.

Supported file formats

Parses the output of dot -T?, so depends on local installation.

Special characters in node names and labels

GraphViz2 escapes these 2 characters in those contexts: [].

Escaping the 2 chars [] started with V 2.10. Previously, all of []{} were escaped, but {} are used in records to control the orientation of fields, so they should not have been escaped in the first place.

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

See the next couple of points for details.

Ports

Ports are what Graphviz calls those places on the outline of a node where edges leave and terminate.

The Graphviz syntax for ports is a bit unusual:

Let me repeat - that is Graphviz syntax, not GraphViz2 syntax. In Perl, you must do this:

    $graph -> add_edge(from => 'struct1:f1', to => 'struct2:f0', color => 'blue');

You don't have to quote all node names in Graphviz, but some, such as digits, must be quoted, so I've decided to quote them all.

How labels interact with ports

You can specify labels with ports in these ways:

See also the docs for the add_node(name => $node_name, [%hash]) method.

Attributes for clusters

Just use subgraph => {...}, because the code (as of V 2.22) accepts attributes belonging to either clusters or subgraphs.

An example attribute is pencolor, which is used for clusters but not for subgraphs:

    $graph->push_subgraph(
            graph    => {label => 'Child the Second'},
            name     => 'cluster Second subgraph',
            node     => {color => 'magenta', shape => 'diamond'},
            subgraph => {pencolor => 'white'}, # White hides the cluster's frame.
    );
    # other nodes or edges can be added within it...
    $graph->pop_subgraph;

TODO

A Extremely Short List of Other Graphing Software

Axis Maps.

Polygon Map Generation. Read more on that here.

Voronoi Applications.

Thanks

Many thanks are due to the people who chose to make Graphviz Open Source.

And thanks to Leon Brocard, 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.

Repository

https://github.com/ronsavage/GraphViz2.git

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 Perl License, a copy of which is available at:
    http://dev.perl.org/licenses/