| GraphViz(3pm) | User Contributed Perl Documentation | GraphViz(3pm) |
GraphViz - Interface to AT&T's GraphViz. Deprecated. See GraphViz2
use GraphViz;
my $g = GraphViz->new();
$g->add_node('London');
$g->add_node('Paris', label => 'City of\nlurve');
$g->add_node('New York');
$g->add_edge('London' => 'Paris');
$g->add_edge('London' => 'New York', label => 'Far');
$g->add_edge('Paris' => 'London');
print $g->as_png;
This module provides an interface to layout and image generation of directed and undirected graphs in a variety of formats (PostScript, PNG, etc.) using the "dot", "neato", "twopi", "circo" and "fdp" programs from the Graphviz project (http://www.graphviz.org/ or http://www.research.att.com/sw/tools/graphviz/).
GraphViz is deprecated in favour of GraphViz2.
Of course you need to install AT&T's Graphviz before using this module. See <http://www.graphviz.org/Download.php>.
You are strongly advised to download the stable version of Graphviz, because the development snapshots (click on 'Source code'), are sometimes non-functional.
Install GraphViz as you would for any "Perl" module:
Run:
cpanm GraphViz
Note: cpanm ships in App::cpanminus. See also App::perlbrew.
or run:
sudo cpan GraphViz
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
A (undirected) graph is a collection of nodes linked together with edges.
A directed graph is the same as a graph, but the edges have a direction.
This module is an interface to the GraphViz toolset (http://www.graphviz.org/). The GraphViz tools provide automatic graph layout and drawing. This module simplifies the creation of graphs and hides some of the complexity of the GraphViz module.
Laying out graphs in an aesthetically-pleasing way is a hard problem - there may be multiple ways to lay out the same graph, each with their own quirks. GraphViz luckily takes part of this hard problem and does a pretty good job in a couple of seconds for most graphs.
Observation aids comprehension. That is a fancy way of expressing that popular faux-Chinese proverb: "a picture is worth a thousand words".
Text is not always the best way to represent anything and everything to do with a computer programs. Pictures and images are easier to assimilate than text. The ability to show a particular thing graphically can aid a great deal in comprehending what that thing really represents.
Diagrams are computationally efficient, because information can be indexed by location; they group related information in the same area. They also allow relations to be expressed between elements without labeling the elements.
A friend of mine used this to his advantage when trying to remember important dates in computer history. Instead of sitting down and trying to remember everything, he printed over a hundred posters (each with a date and event) and plastered these throughout his house. His spatial memory is still so good that asked last week (more than a year since the experiment) when Lisp was invented, he replied that it was upstairs, around the corner from the toilet, so must have been around 1958.
Spreadsheets are also a wonderfully simple graphical representation of computational models.
Bundled with this module are several modules to help graph data structures (GraphViz::Data::Dumper), XML (GraphViz::XML), and Parse::RecDescent, Parse::Yapp, and yacc grammars (GraphViz::Parse::RecDescent, GraphViz::Parse::Yapp, and GraphViz::Parse::Yacc).
Note that Marcel Grunauer has released some modules on CPAN to graph various other structures. See GraphViz::DBI and GraphViz::ISA for example.
brian d foy has written an article about Devel::GraphVizProf for Dr. Dobb's Journal: http://www.ddj.com/columns/perl/2001/0104pl002/0104pl002.htm
I presented a paper and talk on "Graphing Perl" using GraphViz at the 3rd German Perl Workshop and received the "Best Knowledge Transfer" prize.
Talk: http://www.astray.com/graphing_perl/graphing_perl.pdf Slides: http://www.astray.com/graphing_perl/
This is the constructor. It accepts several attributes.
my $g = GraphViz->new();
my $g = GraphViz->new(directed => 0);
my $g = GraphViz->new(layout => 'neato', ratio => 'compress');
my $g = GraphViz->new(rankdir => 'BT');
my $g = GraphViz->new(width => 8.5, height => 11);
my $g = GraphViz->new(width => 30, height => 20,
pagewidth => 8.5, pageheight => 11);
The most two important attributes are 'layout' and 'directed'.
Determines if and how node overlaps should be removed.
NOTE: The methods related to "orthoxy" and "orthoyx" are still evolving. The semantics of these may change, or these methods may disappear altogether.
Except for the Voronoi method, all of these transforms preserve the orthogonal ordering of the original layout. That is, if the x coordinates of two nodes are originally the same, they will remain the same, and if the x coordinate of one node is originally less than the x coordinate of another, this relation will still hold in the transformed layout. The similar properties hold for the y coordinates.
my $g = GraphViz->new(node => {shape => 'box'});
A graph consists of at least one node. All nodes have a name attached which uniquely represents that node.
The add_node method creates a new node and optionally assigns it attributes.
The simplest form is used when no attributes are required, in which the string represents the name of the node:
$g->add_node('Paris');
Various attributes are possible: "label" provides a label for the node (the label defaults to the name if none is specified). The label can contain embedded newlines with '\n', as well as '\c', '\l', '\r' for center, left, and right justified lines:
$g->add_node('Paris', label => 'City of\nlurve');
Attributes need not all be specified in the one line: successive declarations of the same node have a cumulative effect, in that any later attributes are just added to the existing ones. For example, the following two lines are equivalent to the one above:
$g->add_node('Paris');
$g->add_node('Paris', label => 'City of\nlurve');
Note that multiple attributes can be specified. Other attributes include:
A colour value may be "h,s,v" (hue, saturation, brightness) floating point numbers between 0 and 1, or an X11 color name such as 'white', 'black', 'red', 'green', 'blue', 'yellow', 'magenta', 'cyan', or 'burlywood'
If you wish to add an anonymous node, that is a node for which you do not wish to generate a name, you may use the following form, where the GraphViz module generates a name and returns it for you. You may then use this name later on to refer to this node:
my $nodename = $g->add_node('label' => 'Roman city');
Nodes can be clustered together with the "cluster" attribute, which is drawn by having a labelled rectangle around all the nodes in a cluster. An empty string means not clustered.
$g->add_node('London', cluster => 'Europe');
$g->add_node('Amsterdam', cluster => 'Europe');
Clusters can also take a hashref so that you can set attributes:
my $eurocluster = {
name =>'Europe',
style =>'filled',
fillcolor =>'lightgray',
fontname =>'arial',
fontsize =>'12',
};
$g->add_node('London', cluster => $eurocluster, @default_attrs);
Nodes can be located in the same rank (that is, at the same level in the graph) with the "rank" attribute. Nodes with the same rank value are ranked together.
$g->add_node('Paris', rank => 'top');
$g->add_node('Boston', rank => 'top');
Also, nodes can consist of multiple parts (known as ports). This is implemented by passing an array reference as the label, and the parts are displayed as a label. GraphViz has a much more complete port system, this is just a simple interface to it. See the 'from_port' and 'to_port' attributes of add_edge:
$g->add_node('London', label => ['Heathrow', 'Gatwick']);
Edges are directed (or undirected) links between nodes. This method creates a new edge between two nodes and optionally assigns it attributes.
The simplest form is when now attributes are required, in which case the nodes from and to which the edge should be are specified. This works well visually in the program code:
$g->add_edge('London' => 'Paris');
Attributes such as 'label' can also be used. This specifies a label for the edge. The label can contain embedded newlines with '\n', as well as '\c', '\l', '\r' for center, left, and right justified lines.
$g->add_edge('London' => 'New York', label => 'Far');
Note that multiple attributes can be specified. Other attributes include:
A colour value may be "h,s,v" (hue, saturation, brightness) floating point numbers between 0 and 1, or an X11 color name such as 'white', 'black', 'red', 'green', 'blue', 'yellow', 'magenta', 'cyan', or 'burlywood'
Additionally, adding edges between ports of a node is done via the 'from_port' and 'to_port' parameters, which currently takes in the offset of the port (ie 0, 1, 2...).
$g->add_edge('London' => 'Paris', from_port => 0);
There are a number of methods which generate input for dot / neato / twopi / circo / fdp or output the graph in a variety of formats.
Note that if you pass a filename, the data is written to that filename. If you pass a filehandle, the data will be streamed to the filehandle. If you pass a scalar reference, then the data will be stored in that scalar. If you pass it a code reference, then it is called with the data (note that the coderef may be called multiple times if the image is large). Otherwise, the data is returned:
Win32 Note: you will probably want to binmode any filehandles you write the output to if you want your application to be portable to Win32.
my $png_image = $g->as_png;
# or
$g->as_png("pretty.png"); # save image
# or
$g->as_png(\*STDOUT); # stream image to a filehandle
# or
#g->as_png(\$text); # save data in a scalar
# or
$g->as_png(sub { $png_image .= shift });
print $g->as_debug;
print $g->as_canon;
# prints out something like:
digraph test {
node [ label = "\N" ];
London [label=London];
Paris [label="City of\nlurve"];
New_York [label="New York"];
London -> Paris;
London -> New_York [label=Far];
Paris -> London;
}
print $g->as_text;
# prints out something like:
digraph test {
node [ label = "\N" ];
graph [bb= "0,0,162,134"];
London [label=London, pos="33,116", width="0.89", height="0.50"];
Paris [label="City of\nlurve", pos="33,23", width="0.92", height="0.62"];
New_York [label="New York", pos="123,23", width="1.08", height="0.50"];
London -> Paris [pos="e,27,45 28,98 26,86 26,70 27,55"];
London -> New_York [label=Far, pos="e,107,40 49,100 63,85 84,63 101,46", lp="99,72"];
Paris -> London [pos="s,38,98 39,92 40,78 40,60 39,45"];
}
print $g->as_ps;
print $g->as_hpgl;
print $g->as_pcl;
print $g->as_mif;
print $g->as_pic;
print $g->as_gd;
print $g->as_gd2;
print $g->as_gif;
print $g->as_jpeg;
print $g->as_png;
$g->as_png("pretty.png"); # save image
print $g->as_wbmp;
print $g->as_cmap;
print $g->as_cmapx;
print $g->as_ismap;
print $g->as_imap;
print $g->as_vdx;
print $g->as_vrml;
print $g->as_vtx;
print $g->as_mp;
print $g->as_fig;
print $g->as_svg;
print $g->as_svgz;
print $g->as_plain;
Error: <stdin>:1: syntax error near line 1
context: digraph >>> Graph <<< {
Graphviz reserves some words as keywords, meaning they can't be used as an ID, e.g. for the name of the graph. So, don't do this:
strict graph graph{...}
strict graph Graph{...}
strict graph strict{...}
etc...
Likewise for non-strict graphs, and digraphs. You can however add double-quotes around such reserved words:
strict graph "graph"{...}
Even better, use a more meaningful name for your graph...
The keywords are: node, edge, graph, digraph, subgraph and strict. Compass points are not keywords.
See keywords <http://www.graphviz.org/content/dot-language> in the discussion of the syntax of DOT for details.
Due to security risks with XXE in XML, Graphviz does not support XML that contains XXE. Thus it automatically prevents external entities being parsed by using the no_xxe option in XML::Twig when calling XML::Twig -> new(). And for this reason also the pre-reqs in Makefile.PL specify XML::Twig V 3.52.
See <https://metacpan.org/pod/release/MIROD/XML-Twig-3.52/Twig.pm#no_xxe>
Older versions of GraphViz used a slightly different syntax for node and edge adding (with hash references). The new format is slightly clearer, although for the moment we support both. Use the new, clear syntax, please.
GraphViz is deprecated in favour of GraphViz2.
The file Changes was converted into Changelog.ini by Module::Metadata::Changes.
<https://github.com/ronsavage/GraphViz>
Leon Brocard: <acme@astray.com>.
Current maintainer: Ron Savage <ron@savage.net.au>.
My homepage: <http://savage.net.au/>.
Copyright (C) 2000-4, Leon Brocard
This module is free software; you can redistribute it or modify it under the Perl License, a copy of which is available at <http://dev.perl.org/licenses/>.
| 2020-07-22 | perl v5.30.3 |