NAME

GraphViz2::Data::Grapher - Visualize a data structure as a graph

Synopsis

        #!/usr/bin/env perl
        
        use strict;
        use warnings;
        
        use File::Spec;
        
        use GraphViz2;
        use GraphViz2::Data::Grapher;
        
        use Log::Handler;
        
        # ------------------------------------------------
        
        my($logger) = Log::Handler -> new;
        
        $logger -> add
                (
                 screen =>
                 {
                         maxlevel       => 'debug',
                         message_layout => '%m',
                         minlevel       => 'error',
                 }
                );
        
        my($sub) = sub{};
        my($s)   = 
        {
                A => 
                {
                        a => 
                        {
                        },
                        bbbbbb => $sub,
                        c123   => $sub,
                        d      => \$sub,
                },
                C =>
                {
                        b =>
                        {
                                a => 
                                {
                                        a => 
                                        {
                                        },
                                        b => sub{},
                                        c => 42,
                                },
                        },
                },
                els => [qw(element_1 element_2 element_3)],
        };
        
        my($graph) = GraphViz2 -> new
                (
                 edge   => {color => 'grey'},
                 global => {directed => 1},
                 graph  => {rankdir => 'TB', label => "Graph produced by GraphViz2::Data::Grapher's $0"},
                 logger => $logger,
                 node   => {color => 'darkblue', shape => 'oval'},
                );
        
        my($g)           = GraphViz2::Data::Grapher -> new(graph => $graph, logger => $logger);
        my($format)      = shift || 'svg';
        my($output_file) = shift || File::Spec -> catfile('html', "parse.data.$format");
        
        $g -> create(name => 's', thing => $s);
        $graph -> run(format => $format, output_file => $output_file, timeout => 11);
        
        # If you did not provide a GraphViz2 object, do this
        # to get access to the auto-created GraphViz2 object.
        
        #$g -> create(name => 's', thing => $s);
        #$g -> graph -> run(format => $format, output_file => $output_file, timeout => 11);
        
        # Or even
        
        #$g -> create(name => 's', thing => $s)
        #-> graph
        #-> run(format => $format, output_file => $output_file, timeout => 11);

See scripts/parse.data.pl ("Scripts Shipped with this Module" in GraphViz2).

Description

Takes a Perl data structure and recursively converts it into Tree::DAG_Node object, and then graphs it.

You can write the result in any format supported by Graphviz.

Here is the list of output formats.

Within the graph:

o Array names are preceeded by '@'

o Code references are preceeded by '&'

o Hash names are preceeded by '%'

o Scalar names are preceeded by '$'

Hence, a hash ref will look like '%$h'.

Further, objects of different type have different shapes.

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::Data::Grapher -> new(k1 => v1, k2 => v2, ...).

It returns a new object of type GraphViz2::Data::Grapher.

Key-value pairs accepted in the parameter list:

o graph => $graphviz_object

This option specifies the GraphViz2 object to use. This allows you to configure it as desired.

The default is GraphViz2 -> new. The default attributes are the same as in the synopsis, above, except for the graph label of course.

This key is optional.

o logger => $logger_object

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

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

The default is ''.

At the moment, the logger object is not used. This feature is mainly used for testing.

Methods

create(name => $name, thing => $thing)

Creates the graph, which is accessible via the graph() method, or via the graph object you passed to new().

Returns $self to allow method chaining.

$name is the string which will be placed in the root node of the tree.

If $s = {...}, say, use 's', not '$s', because '%$' will be prefixed automatically to the name, because $s is a hashref.

$thing is the data stucture to graph.

graph()

Returns the graph object, either the one supplied to new() or the one created during the call to new().

tree()

Returns the tree object (of type Tree::DAG_Node) built before it is traversed to generate the nodes and edges.

Traversal does change the attributes of nodes, by storing {record => $string} there, so that edges can be plotted from a parent to its daughters.

Warning: As the GraphViz2::Data::Grapher object exits its scope, $self -> tree -> delete_tree is called.

FAQ

See "FAQ" in GraphViz2 and "Scripts Shipped with this Module" in GraphViz2.

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.

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

cpanm GraphViz2

perl -MCPAN -e shell
install GraphViz2