1GraphViz2(3)          User Contributed Perl Documentation         GraphViz2(3)
2
3
4

NAME

6       GraphViz2 - A wrapper for AT&T's Graphviz
7

Synopsis

9   Sample output
10       See <https://graphviz-perl.github.io/>.
11
12   Perl code
13       Typical Usage
14
15               use strict;
16               use warnings;
17               use File::Spec;
18               use GraphViz2;
19
20               use Log::Handler;
21               my $logger = Log::Handler->new;
22               $logger->add(screen => {
23                       maxlevel => 'debug', message_layout => '%m', minlevel => 'error'
24               });
25
26               my $graph = GraphViz2->new(
27                       edge   => {color => 'grey'},
28                       global => {directed => 1},
29                       graph  => {label => 'Adult', rankdir => 'TB'},
30                       logger => $logger,
31                       node   => {shape => 'oval'},
32               );
33
34               $graph->add_node(name => 'Carnegie', shape => 'circle');
35               $graph->add_node(name => 'Murrumbeena', shape => 'box', color => 'green');
36               $graph->add_node(name => 'Oakleigh',    color => 'blue');
37               $graph->add_edge(from => 'Murrumbeena', to    => 'Carnegie', arrowsize => 2);
38               $graph->add_edge(from => 'Murrumbeena', to    => 'Oakleigh', color => 'brown');
39
40               $graph->push_subgraph(
41                       name  => 'cluster_1',
42                       graph => {label => 'Child'},
43                       node  => {color => 'magenta', shape => 'diamond'},
44               );
45               $graph->add_node(name => 'Chadstone', shape => 'hexagon');
46               $graph->add_node(name => 'Waverley', color => 'orange');
47               $graph->add_edge(from => 'Chadstone', to => 'Waverley');
48               $graph->pop_subgraph;
49
50               $graph->default_node(color => 'cyan');
51
52               $graph->add_node(name => 'Malvern');
53               $graph->add_node(name => 'Prahran', shape => 'trapezium');
54               $graph->add_edge(from => 'Malvern', to => 'Prahran');
55               $graph->add_edge(from => 'Malvern', to => 'Murrumbeena');
56
57               my $format      = shift || 'svg';
58               my $output_file = shift || File::Spec->catfile('html', "sub.graph.$format");
59               $graph->run(format => $format, output_file => $output_file);
60

Description

62   Overview
63       This module provides a Perl interface to the amazing Graphviz
64       <http://www.graphviz.org/>, an open source graph visualization tool
65       from AT&T.
66
67       It is called GraphViz2 so that pre-existing code using (the Perl
68       module) GraphViz continues to work.
69
70       To avoid confusion, when I use GraphViz2 (note the capital V), I'm
71       referring to this Perl module, and when I use Graphviz
72       <http://www.graphviz.org/> (lower-case v) I'm referring to the
73       underlying tool (which is in fact a set of programs).
74
75       Version 1.00 of GraphViz2 is a complete re-write, by Ron Savage, of
76       GraphViz V 2, which was written by Leon Brocard. The point of the re-
77       write is to provide access to all the latest options available to users
78       of Graphviz <http://www.graphviz.org/>.
79
80       GraphViz2 V 1 is not backwards compatible with GraphViz V 2, despite
81       the considerable similarity. It was not possible to maintain
82       compatibility while extending support to all the latest features of
83       Graphviz <http://www.graphviz.org/>.
84
85       To ensure GraphViz2 is a light-weight module, Moo has been used to
86       provide getters and setters, rather than Moose.
87
88       As of V 2.43, "GraphViz2" supports image maps, both client and server
89       side.
90
91       See "Image Maps" below.
92
93   What is a Graph?
94       An undirected graph is a collection of nodes optionally linked together
95       with edges.
96
97       A directed graph is the same, except that the edges have a direction,
98       normally indicated by an arrow head.
99
100       A quick inspection of Graphviz <http://www.graphviz.org/>'s gallery
101       <http://www.graphviz.org/gallery/> will show better than words just how
102       good Graphviz <http://www.graphviz.org/> is, and will reinforce the
103       point that humans are very visual creatures.
104

Installation

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

Constructor and Initialization

110   Calling new()
111       "new()" is called as "my($obj) = GraphViz2 -> new(k1 => v1, k2 => v2,
112       ...)".
113
114       It returns a new object of type "GraphViz2".
115
116       Key-value pairs accepted in the parameter list:
117
118       edge => $hashref
119
120       The edge key points to a hashref which is used to set default
121       attributes for edges.
122
123       Hence, allowable keys and values within that hashref are anything
124       supported by Graphviz <http://www.graphviz.org/>.
125
126       The default is {}.
127
128       This key is optional.
129
130       global => $hashref
131
132       The global key points to a hashref which is used to set attributes for
133       the output stream.
134
135       This key is optional.
136
137       Valid keys within this hashref are:
138
139       combine_node_and_port
140
141       New in 2.58. It defaults to true, but in due course (currently planned
142       May 2021) it will default to false. When true, "add_node" and
143       "add_edge" will escape only some characters in the label and names, and
144       in particular the "from" and "to" parameters on edges will combine the
145       node name and port in one string, with a ":" in the middle (except for
146       special treatment of double-colons).
147
148       When the option is false, any name may be given to nodes, and edges can
149       be created between them. To specify ports, give the additional
150       parameter of "tailport" or "headport". To specify a compass point in
151       addition, give array-refs with two values for these parameters. Also,
152       "add_node"'s treatment of labels is more DWIM, with "{" etc being
153       transparently quoted.
154
155       directed => $Boolean
156
157       This option affects the content of the output stream.
158
159       directed => 1 outputs 'digraph name {...}', while directed => 0 outputs
160       'graph name {...}'.
161
162       At the Perl level, directed graphs have edges with arrow heads, such as
163       '->', while undirected graphs have unadorned edges, such as '--'.
164
165       The default is 0.
166
167       This key is optional.
168
169       driver => $program_name
170
171       This option specifies which external program to run to process the
172       output stream.
173
174       The default is to use File::Which's which() method to find the 'dot'
175       program.
176
177       This key is optional.
178
179       format => $string
180
181       This option specifies what type of output file to create.
182
183       The default is 'svg'.
184
185       Output formats of the form 'png:gd' etc are also supported, but only
186       the component before the first ':' is validated by GraphViz2.
187
188       This key is optional.
189
190       label => $string
191
192       This option specifies what an edge looks like: '->' for directed graphs
193       and '--' for undirected graphs.
194
195       You wouldn't normally need to use this option.
196
197       The default is '->' if directed is 1, and '--' if directed is 0.
198
199       This key is optional.
200
201       name => $string
202
203       This option affects the content of the output stream.
204
205       name => 'G666' outputs 'digraph G666 {...}'.
206
207       The default is 'Perl' :-).
208
209       This key is optional.
210
211       record_shape => /^(?:M?record)$/
212
213       This option affects the shape of records. The value must be 'Mrecord'
214       or 'record'.
215
216       Mrecords have nice, rounded corners, whereas plain old records have
217       square corners.
218
219       The default is 'Mrecord'.
220
221       See Record shapes <http://www.graphviz.org/doc/info/shapes.html#record>
222       for details.
223
224       strict => $Boolean
225
226       This option affects the content of the output stream.
227
228       strict => 1 outputs 'strict digraph name {...}', while strict => 0
229       outputs 'digraph name {...}'.
230
231       The default is 0.
232
233       This key is optional.
234
235       timeout => $integer
236
237       This option specifies how long to wait for the external program before
238       exiting with an error.
239
240       The default is 10 (seconds).
241
242       This key is optional.
243
244       graph => $hashref
245
246       The graph key points to a hashref which is used to set default
247       attributes for graphs.
248
249       Hence, allowable keys and values within that hashref are anything
250       supported by Graphviz <http://www.graphviz.org/>.
251
252       The default is {}.
253
254       This key is optional.
255
256       logger => $logger_object
257
258       Provides a logger object so $logger_object -> $level($message) can be
259       called at certain times. Any object with "debug" and "error" methods
260       will do, since these are the only levels emitted by this module.  One
261       option is a Log::Handler object.
262
263       Retrieve and update the value with the logger() method.
264
265       By default (i.e. without a logger object), GraphViz2 prints warning and
266       debug messages to STDOUT, and dies upon errors.
267
268       However, by supplying a log object, you can capture these events.
269
270       Not only that, you can change the behaviour of your log object at any
271       time, by calling "logger($logger_object)".
272
273       See also the verbose option, which can interact with the logger option.
274
275       This key is optional.
276
277       node => $hashref
278
279       The node key points to a hashref which is used to set default
280       attributes for nodes.
281
282       Hence, allowable keys and values within that hashref are anything
283       supported by Graphviz <http://www.graphviz.org/>.
284
285       The default is {}.
286
287       This key is optional.
288
289       subgraph => $hashref
290
291       The subgraph key points to a hashref which is used to set attributes
292       for all subgraphs, unless overridden for specific subgraphs in a call
293       of the form push_subgraph(subgraph => {$attribute => $string}).
294
295       Valid keys within this hashref are:
296
297       •   rank => $string
298
299           This option affects the content of all subgraphs, unless overridden
300           later.
301
302           A typical usage would be new(subgraph => {rank => 'same'}) so that
303           all nodes mentioned within each subgraph are constrained to be
304           horizontally aligned.
305
306           See scripts/rank.sub.graph.1.pl for sample code.
307
308           Possible values for $string are: max, min, same, sink and source.
309
310           See the Graphviz 'rank' docs
311           <http://www.graphviz.org/doc/info/attrs.html#d:rank> for details.
312
313       The default is {}.
314
315       This key is optional.
316
317       verbose => $Boolean
318
319       Provides a way to control the amount of output when a logger is not
320       specified.
321
322       Setting verbose to 0 means print nothing.
323
324       Setting verbose to 1 means print the log level and the message to
325       STDOUT, when a logger is not specified.
326
327       Retrieve and update the value with the verbose() method.
328
329       The default is 0.
330
331       See also the logger option, which can interact with the verbose option.
332
333       This key is optional.
334
335   Validating Parameters
336       The secondary keys (under the primary keys 'edge|graph|node') are
337       checked against lists of valid attributes (stored at the end of this
338       module, after the __DATA__ token, and made available using
339       Data::Section::Simple).
340
341       This mechanism has the effect of hard-coding Graphviz
342       <http://www.graphviz.org/> options in the source code of GraphViz2.
343
344       Nevertheless, the implementation of these lists is handled differently
345       from the way it was done in V 2.
346
347       V 2 ships with a set of scripts, scripts/extract.*.pl, which retrieve
348       pages from the Graphviz <http://www.graphviz.org/> web site and extract
349       the current lists of valid attributes.
350
351       These are then copied manually into the source code of GraphViz2,
352       meaning any time those lists change on the Graphviz
353       <http://www.graphviz.org/> web site, it's a trivial matter to update
354       the lists stored within this module.
355
356       See "Scripts Shipped with this Module" in GraphViz2.
357
358   Alternate constructor and object method
359       from_graph
360
361               my $gv = GraphViz2->from_graph($g);
362
363               # alternatively
364               my $gv = GraphViz2->new;
365               $gv->from_graph($g);
366
367               # for handy debugging of arbitrary graphs:
368               GraphViz2->from_graph($g)->run(format => 'svg', output_file => 'output.svg');
369
370       Takes a Graph object. This module will figure out various defaults from
371       it, including whether it is directed or not.
372
373       Will also use any node-, edge-, and graph-level attributes named
374       "graphviz" as a hash-ref for setting attributes on the corresponding
375       entities in the constructed GraphViz2 object. These will override the
376       figured-out defaults referred to above.
377
378       For a "multivertexed" graph, will only create one node per vertex, but
379       will search all the multi-IDs for a "graphviz" attribute, taking the
380       first one it finds (sorted alphabetically).
381
382       For a "multiedged" graph, will create one edge per multi-edge.
383
384       Will only set the "global" attribute if called as a constructor. This
385       will be dropped from any passed-in graph-level "graphviz" attribute
386       when called as an object method.
387
388       A special graph-level attribute (under "graphviz") called "groups" will
389       be given further special meaning: it is an array-ref of hash-refs.
390       Those will have keys, used to create subgraphs:
391
392       •   attributes
393
394           Hash-ref of arguments to supply to "push_subgraph" for this
395           subgraph.
396
397       •   nodes
398
399           Array-ref of node names to put in this subgraph.
400
401       Example:
402
403               $g->set_graph_attribute(graphviz => {
404                       groups => [
405                               {nodes => [1, 2], attributes => {subgraph=>{rank => 'same'}}},
406                       ],
407                       # other graph-level attributes...
408               });
409

Attribute Scope

411   Graph Scope
412       The graphical elements graph, node and edge, have attributes.
413       Attributes can be set when calling new().
414
415       Within new(), the defaults are graph => {}, node => {}, and edge => {}.
416
417       You override these with code such as new(edge => {color => 'red'}).
418
419       These attributes are pushed onto a scope stack during new()'s
420       processing of its parameters, and they apply thereafter until changed.
421       They are the 'current' attributes. They live at scope level 0 (zero).
422
423       You change the 'current' attributes by calling any of the methods
424       default_edge(%hash), default_graph(%hash) and default_node(%hash).
425
426       See scripts/trivial.pl ("Scripts Shipped with this Module" in
427       GraphViz2) for an example.
428
429   Subgraph Scope
430       When you wish to create a subgraph, you call push_subgraph(%hash). The
431       word push emphasises that you are moving into a new scope, and that the
432       default attributes for the new scope are pushed onto the scope stack.
433
434       This module, as with Graphviz <http://www.graphviz.org/>, defaults to
435       using inheritance of attributes.
436
437       That means the parent's 'current' attributes are combined with the
438       parameters to push_subgraph(%hash) to generate a new set of 'current'
439       attributes for each of the graphical elements, graph, node and edge.
440
441       After a single call to push_subgraph(%hash), these 'current' attributes
442       will live a level 1 in the scope stack.
443
444       See scripts/sub.graph.pl ("Scripts Shipped with this Module" in
445       GraphViz2) for an example.
446
447       Another call to push_subgraph(%hash), without an intervening call to
448       pop_subgraph(), will repeat the process, leaving you with a set of
449       attributes at level 2 in the scope stack.
450
451       Both GraphViz2 and Graphviz <http://www.graphviz.org/> handle this
452       situation properly.
453
454       See scripts/sub.sub.graph.pl ("Scripts Shipped with this Module" in
455       GraphViz2) for an example.
456
457       At the moment, due to design defects (IMHO) in the underlying Graphviz
458       <http://www.graphviz.org/> logic, there are some tiny problems with
459       this:
460
461       •   A global frame
462
463           I can't see how to make the graph as a whole (at level 0 in the
464           scope stack) have a frame.
465
466       •   Frame color
467
468           When you specify graph => {color => 'red'} at the parent level, the
469           subgraph has a red frame.
470
471           I think a subgraph should control its own frame.
472
473       •   Parent and child frames
474
475           When you specify graph => {color => 'red'} at the subgraph level,
476           both that subgraph and it children have red frames.
477
478           This contradicts what happens at the global level, in that
479           specifying color there does not given the whole graph a frame.
480
481       •   Frame visibility
482
483           A subgraph whose name starts with 'cluster' is currently forced to
484           have a frame, unless you rig it by specifying a color the same as
485           the background.
486
487           For sample code, see scripts/sub.graph.frames.pl.
488
489       Also, check the pencolor docs
490       <http://www.graphviz.org/doc/info/attrs.html#d:pencolor> for how the
491       color of the frame is chosen by cascading thru a set of options.
492
493       I've posted an email to the Graphviz <http://www.graphviz.org/> mailing
494       list suggesting a new option, framecolor, so deal with this issue,
495       including a special color of 'invisible'.
496

Image Maps

498       As of V 2.43, "GraphViz2" supports image maps, both client and server
499       side.  For web use, note that these options also take effect when
500       generating SVGs, for a much lighter-weight solution to hyperlinking
501       graph nodes and edges.
502
503   The Default URL
504       See the Graphviz docs for 'cmapx'
505       <http://www.graphviz.org/doc/info/output.html#d:cmapx>.
506
507       Their sample code has a dot file - x.gv - containing this line:
508
509               URL="http://www.research.att.com/base.html";
510
511       The way you set such a url in "GraphViz2" is via a new parameter to
512       "new()". This parameter is called "im_meta" and it takes a hashref as a
513       value. Currently the only key used within that hashref is the case-
514       sensitive "URL".
515
516       Thus you must do this to set a URL:
517
518               my($graph) = GraphViz2 -> new
519                            (
520                               ...
521                               im_meta =>
522                               {
523                                   URL => 'http://savage.net.au/maps/demo.3.1.html', # Note: URL must be in caps.
524                               },
525                            );
526
527       See maps/demo.3.pl and maps/demo.4.pl for sample code.
528
529   Typical Code
530       Normally you would call "run()" as:
531
532               $graph -> run
533               (
534                   format      => $format,
535                   output_file => $output_file
536               );
537
538       That line was copied from scripts/cluster.pl.
539
540       To trigger image map processing, you must include 2 new parameters:
541
542               $graph -> run
543               (
544                   format         => $format,
545                   output_file    => $output_file,
546                   im_format      => $im_format,
547                   im_output_file => $im_output_file
548               );
549
550       That line was copied from maps/demo.3.pl, and there is an identical
551       line in maps/demo.4.pl.
552
553   The New Parameters to run()
554       •   im_format => $str
555
556           Expected values: 'imap' (server-side) and 'cmapx' (client-side).
557
558           Default value: 'cmapx'.
559
560       •   im_output_file => $file_name
561
562           The name of the output map file.
563
564           Default: ''.
565
566           If you do not set it to anything, the new image maps code is
567           ignored.
568
569   Sample Code
570       Various demos are shipped in the new maps/ directory:
571
572       Each demo, when FTPed to your web server displays some text with an
573       image in the middle. In each case you can click on the upper oval to
574       jump to one page, or click on the lower oval to jump to a different
575       page, or click anywhere else in the image to jump to a third page.
576
577       •   demo.1.*
578
579           This set demonstrates a server-side image map but does not use
580           "GraphViz2".
581
582           You have to run demo.1.sh which generates demo.1.map, and then you
583           FTP the whole dir maps/ to your web server.
584
585           URL: your.domain.name/maps/demo.1.html.
586
587       •   demo.2.*
588
589           This set demonstrates a client-side image map but does not use
590           "GraphViz2".
591
592           You have to run demo.2.sh which generates demo.2.map, and then you
593           manually copy demo.2.map into demo.2.html, replacing any version of
594           the map already present. After that you FTP the whole dir maps/ to
595           your web server.
596
597           URL: your.domain.name/maps/demo.2.html.
598
599       •   demo.3.*
600
601           This set demonstrates a server-side image map using "GraphViz2" via
602           demo.3.pl.
603
604           Note line 54 of demo.3.pl which sets the default "im_format" to
605           'imap'.
606
607           URL: your.domain.name/maps/demo.3.html.
608
609       •   demo.4.*
610
611           This set demonstrates a client-side image map using "GraphViz2" via
612           demo.4.pl.
613
614           As with demo.2.* there is some manually editing to be done.
615
616           Note line 54 of demo.4.pl which sets the default "im_format" to
617           'cmapx'. This is the only important difference between this demo
618           and the previous one.
619
620           There are other minor differences, in that one uses 'svg' and the
621           other 'png'. And of course the urls of the web pages embedded in
622           the code and in those web pages differs, just to demonstate that
623           the maps do indeed lead to different pages.
624
625           URL: your.domain.name/maps/demo.4.html.
626

Methods

628   add_edge(from => $from_node_name, to => $to_node_name, [label => $label,
629       %hash])
630       Adds an edge to the graph.
631
632       Returns $self to allow method chaining.
633
634       Here, [] indicate optional parameters.
635
636       Add a edge from 1 node to another.
637
638       $from_node_name and $to_node_name default to ''.
639
640       %hash is any edge attributes accepted as Graphviz attributes
641       <https://www.graphviz.org/doc/info/attrs.html>.  These are validated in
642       exactly the same way as the edge parameters in the calls to
643       default_edge(%hash), new(edge => {}) and push_subgraph(edge => {}).
644
645       To make the edge start or finish on a port, see
646       "combine_node_and_port".
647
648   add_node(name => $node_name, [%hash])
649               my $graph = GraphViz2->new(global => {combine_node_and_port => 0});
650               $graph->add_node(name => 'struct3', shape => 'record', label => [
651                       { text => "hello\\nworld" },
652                       [
653                               { text => 'b' },
654                               [
655                                       { text => 'c{}' }, # reproduced literally
656                                       { text => 'd', port => 'here' },
657                                       { text => 'e' },
658                               ]
659                               { text => 'f' },
660                       ],
661                       { text => 'g' },
662                       { text => 'h' },
663               ]);
664
665       Adds a node to the graph.
666
667       Returns $self to allow method chaining.
668
669       If you want to embed newlines or double-quotes in node names or labels,
670       see scripts/quote.pl in "Scripts Shipped with this Module" in
671       GraphViz2.
672
673       If you want anonymous nodes, see scripts/anonymous.pl in "Scripts
674       Shipped with this Module" in GraphViz2.
675
676       Here, [] indicates an optional parameter.
677
678       %hash is any node attributes accepted as Graphviz attributes
679       <https://www.graphviz.org/doc/info/attrs.html>.  These are validated in
680       exactly the same way as the node parameters in the calls to
681       default_node(%hash), new(node => {}) and push_subgraph(node => {}).
682
683       The attribute name 'label' may point to a string or an arrayref.
684
685       If it is a string...
686
687       The string is the label. If the "shape" is a record, you can give any
688       text and it will be passed for interpretation by Graphviz. This means
689       you will need to quote < and > (port specifiers), "|" (cell separator)
690       and "{" "}" (structure depth) with "\" to make them appear literally.
691
692       For records, the cells start horizontal. Each additional layer of
693       structure will switch the orientation between horizontal and vertical.
694
695       If it is an arrayref of strings...
696
697       •   The node is forced to be a record
698
699           The actual shape, 'record' or 'Mrecord', is set globally, with:
700
701                   my($graph) = GraphViz2 -> new
702                   (
703                           global => {record_shape => 'record'}, # Override default 'Mrecord'.
704                           ...
705                   );
706
707           Or set locally with:
708
709                   $graph -> add_node(name => 'Three', label => ['Good', 'Bad'], shape => 'record');
710
711       •   Each element in the array defines a field in the record
712
713           These fields are combined into a single node
714
715       •   Each element is treated as a label
716
717       •   Each label is given a port name (1 .. N) of the form
718           "port$port_count"
719
720       •   Judicious use of '{' and '}' in the label can make this record
721           appear horizontally or vertically, and even nested
722
723       If it is an arrayref of hashrefs...
724
725       •   The node is forced to be a record
726
727           The actual shape, 'record' or 'Mrecord', can be set globally or
728           locally, as explained just above.
729
730       •   Each element in the array defines a field in the record
731
732       •   Each element is treated as a hashref with keys 'text' and 'port'
733
734           The 'port' key is optional.
735
736       •   The value of the 'text' key is the label
737
738       •   The value of the 'port' key is the port
739
740       •   Judicious use of '{' and '}' in the label can make this record
741           appear horizontally or vertically, and even nested
742
743       See scripts/html.labels.*.pl and scripts/record.*.pl for sample code.
744
745       See also "How labels interact with ports".
746
747       For more details on this complex topic, see Records
748       <http://www.graphviz.org/doc/info/shapes.html#record> and Ports
749       <http://www.graphviz.org/doc/info/attrs.html#k:portPos>.
750
751   default_edge(%hash)
752       Sets defaults attributes for edges added subsequently.
753
754       Returns $self to allow method chaining.
755
756       %hash is any edge attributes accepted as Graphviz attributes
757       <https://www.graphviz.org/doc/info/attrs.html>.  These are validated in
758       exactly the same way as the edge parameters in the calls to new(edge =>
759       {}) and push_subgraph(edge => {}).
760
761   default_graph(%hash)
762       Sets defaults attributes for the graph.
763
764       Returns $self to allow method chaining.
765
766       %hash is any graph attributes accepted as Graphviz attributes
767       <https://www.graphviz.org/doc/info/attrs.html>.  These are validated in
768       exactly the same way as the graph parameter in the calls to new(graph
769       => {}) and push_subgraph(graph => {}).
770
771   default_node(%hash)
772       Sets defaults attributes for nodes added subsequently.
773
774       Returns $self to allow method chaining.
775
776       %hash is any node attributes accepted as Graphviz attributes
777       <https://www.graphviz.org/doc/info/attrs.html>.  These are validated in
778       exactly the same way as the node parameters in the calls to new(node =>
779       {}) and push_subgraph(node => {}).
780
781   default_subgraph(%hash)
782       Sets defaults attributes for clusters and subgraphs.
783
784       Returns $self to allow method chaining.
785
786       %hash is any cluster or subgraph attribute accepted as Graphviz
787       attributes <https://www.graphviz.org/doc/info/attrs.html>.  These are
788       validated in exactly the same way as the subgraph parameter in the
789       calls to new(subgraph => {}) and push_subgraph(subgraph => {}).
790
791   dot_input()
792       Returns the output stream, formatted nicely, to be passed to the
793       external program (e.g. dot).
794
795   dot_output()
796       Returns the output from calling the external program (e.g. dot).
797
798       You must call run() before calling dot_output(), since it is only
799       during the call to run() that the output of the external program is
800       stored in the buffer controlled by dot_output().
801
802       This output is available even if run() does not write the output to a
803       file.
804
805   edge_hash()
806       Returns, at the end of the run, a hashref keyed by node name,
807       specifically the node at the arrowtail end of the hash, i.e. where the
808       edge starts from.
809
810       Use this to get a list of all nodes and the edges which leave those
811       nodes, the corresponding destination nodes, and the attributes of each
812       edge.
813
814               my($node_hash) = $graph -> node_hash;
815               my($edge_hash) = $graph -> edge_hash;
816
817               for my $from (sort keys %$node_hash)
818               {
819                       my($attr) = $$node_hash{$from}{attributes};
820                       my($s)    = join(', ', map{"$_ => $$attr{$_}"} sort keys %$attr);
821
822                       print "Node: $from\n";
823                       print "\tAttributes: $s\n";
824
825                       for my $to (sort keys %{$$edge_hash{$from} })
826                       {
827                               for my $edge (@{$$edge_hash{$from}{$to} })
828                               {
829                                       $attr = $$edge{attributes};
830                                       $s    = join(', ', map{"$_ => $$attr{$_}"} sort keys %$attr);
831
832                                       print "\tEdge: $from$$edge{from_port} -> $to$$edge{to_port}\n";
833                                       print "\t\tAttributes: $s\n";
834                               }
835                       }
836               }
837
838       If the caller adds the same edge two (or more) times, the attributes
839       from each call are not coalesced (unlike "node_hash()"), but rather the
840       attributes from each call are stored separately in an arrayref.
841
842       A bit more formally then, $$edge_hash{$from_node}{$to_node} is an
843       arrayref where each element describes one edge, and which defaults to:
844
845               {
846                       attributes => {},
847                       from_port  => $from_port,
848                       to_port    => $to_port,
849               }
850
851       If from_port is not provided by the caller, it defaults to '' (the
852       empty string). If it is provided, it contains a leading ':'. Likewise
853       for to_port.
854
855       See scripts/report.nodes.and.edges.pl (a version of
856       scripts/html.labels.1.pl) for a complete example.
857
858   log([$level, $message])
859       Logs the message at the given log level.
860
861       Returns $self to allow method chaining.
862
863       Here, [] indicate optional parameters.
864
865       $level defaults to 'debug', and $message defaults to ''.
866
867       If called with $level eq 'error', it dies with $message.
868
869   logger($logger_object)
870       Gets or sets the log object.
871
872       Here, [] indicates an optional parameter.
873
874   node_hash()
875       Returns, at the end of the run, a hashref keyed by node name. Use this
876       to get a list of all nodes and their attributes.
877
878               my($node_hash) = $graph -> node_hash;
879
880               for my $name (sort keys %$node_hash)
881               {
882                       my($attr) = $$node_hash{$name}{attributes};
883                       my($s)    = join(', ', map{"$_ => $$attr{$_}"} sort keys %$attr);
884
885                       print "Node: $name\n";
886                       print "\tAttributes: $s\n";
887               }
888
889       If the caller adds the same node two (or more) times, the attributes
890       from each call are coalesced (unlike "edge_hash()"), meaning all
891       attributes from all calls are combined under the attributes sub-key.
892
893       A bit more formally then, $$node_hash{$node_name} is a hashref where
894       each element describes one node, and which defaults to:
895
896               {
897                       attributes => {},
898               }
899
900       See scripts/report.nodes.and.edges.pl (a version of
901       scripts/html.labels.1.pl) for a complete example, including usage of
902       the corresponding "edge_hash()" method.
903
904   pop_subgraph()
905       Pop off and discard the top element of the scope stack.
906
907       Returns $self to allow method chaining.
908
909   push_subgraph([name => $name, edge => {...}, graph => {...}, node => {...},
910       subgraph => {...}])
911       Sets up a new subgraph environment.
912
913       Returns $self to allow method chaining.
914
915       Here, [] indicate optional parameters.
916
917       name => $name is the name to assign to the subgraph. Name defaults to
918       ''.
919
920       So, without $name, 'subgraph {' is written to the output stream.
921
922       With $name, 'subgraph "$name" {' is written to the output stream.
923
924       Note that subgraph names beginning with 'cluster' are special to
925       Graphviz <http://www.graphviz.org/doc/info/attrs.html#d:clusterrank>.
926
927       See scripts/rank.sub.graph.[1234].pl for the effect of various values
928       for $name.
929
930       edge => {...} is any edge attributes accepted as Graphviz attributes
931       <https://www.graphviz.org/doc/info/attrs.html>.  These are validated in
932       exactly the same way as the edge parameters in the calls to
933       default_edge(%hash), new(edge => {}) and push_subgraph(edge => {}).
934
935       graph => {...} is any graph attributes accepted as Graphviz attributes
936       <https://www.graphviz.org/doc/info/attrs.html>.  These are validated in
937       exactly the same way as the graph parameters in the calls to
938       default_graph(%hash), new(graph => {}) and push_subgraph(graph => {}).
939
940       node => {...} is any node attributes accepted as Graphviz attributes
941       <https://www.graphviz.org/doc/info/attrs.html>.  These are validated in
942       exactly the same way as the node parameters in the calls to
943       default_node(%hash), new(node => {}) and push_subgraph(node => {}).
944
945       subgraph => {..} is for setting attributes applicable to clusters and
946       subgraphs.
947
948       Currently the only subgraph attribute is "rank", but clusters have many
949       attributes available.
950
951       See the second column of the Graphviz attribute docs
952       <https://www.graphviz.org/doc/info/attrs.html> for details.
953
954       A typical usage would be push_subgraph(subgraph => {rank => 'same'}) so
955       that all nodes mentioned within the subgraph are constrained to be
956       horizontally aligned.
957
958       See scripts/rank.sub.graph.[12].pl and scripts/sub.graph.frames.pl for
959       sample code.
960
961   valid_attributes()
962       Returns a hashref of all attributes known to this module, keyed by type
963       to hashrefs to true values.
964
965       Stored in this module, using Data::Section::Simple.
966
967       These attributes are used to validate attributes in many situations.
968
969       You wouldn't normally need to use this method.
970
971       See scripts/report.valid.attributes.pl. See "Scripts Shipped with this
972       Module" in GraphViz2.
973
974   run([driver => $exe, format => $string, timeout => $integer, output_file =>
975       $output_file])
976       Runs the given program to process the output stream.
977
978       Returns $self to allow method chaining.
979
980       Here, [] indicate optional parameters.
981
982       $driver is the name of the external program to run.
983
984       It defaults to the value supplied in the call to new(global => {driver
985       => '...'}), which in turn defaults to File::Which's which('dot') return
986       value.
987
988       $format is the type of output file to write.
989
990       It defaults to the value supplied in the call to new(global => {format
991       => '...'}), which in turn defaults to 'svg'.
992
993       $timeout is the time in seconds to wait while the external program
994       runs, before dieing with an error.
995
996       It defaults to the value supplied in the call to new(global => {timeout
997       => '...'}), which in turn defaults to 10.
998
999       $output_file is the name of the file into which the output from the
1000       external program is written.
1001
1002       There is no default value for $output_file. If a value is not supplied
1003       for $output_file, the only way to recover the output of the external
1004       program is to call dot_output().
1005
1006       This method performs a series of tasks:
1007
1008       •   Run the chosen external program on the "dot_input"
1009
1010       •   Capture STDOUT and STDERR from that program
1011
1012       •   Die if STDERR contains anything
1013
1014       •   Copies STDOUT to the buffer controlled by the dot_output() method
1015
1016       •   Write the captured contents of STDOUT to $output_file, if
1017           $output_file has a value
1018
1019   stringify_attributes($context, $option)
1020       Returns a string suitable to writing to the output stream.
1021
1022       $context is one of 'edge', 'graph', 'node', or a special string. See
1023       the code for details.
1024
1025       You wouldn't normally need to use this method.
1026
1027   validate_params($context, \%attributes)
1028       Validate the given attributes within the given context.
1029
1030       Also, if $context is 'subgraph', attributes are allowed to be in the
1031       'cluster' context.
1032
1033       Returns $self to allow method chaining.
1034
1035       $context is one of 'edge', 'global', 'graph', or 'node'.
1036
1037       You wouldn't normally need to use this method.
1038
1039   verbose([$integer])
1040       Gets or sets the verbosity level, for when a logging object is not
1041       used.
1042
1043       Here, [] indicates an optional parameter.
1044

MISC

1046   Graphviz version supported
1047       GraphViz2 targets V 2.34.0 of Graphviz <http://www.graphviz.org/>.
1048
1049       This affects the list of available attributes per graph item (node,
1050       edge, cluster, etc) available.
1051
1052       See the second column of the Graphviz attribute docs
1053       <https://www.graphviz.org/doc/info/attrs.html> for details.
1054
1055   Supported file formats
1056       Parses the output of "dot -T?", so depends on local installation.
1057
1058   Special characters in node names and labels
1059       GraphViz2 escapes these 2 characters in those contexts: [].
1060
1061       Escaping the 2 chars [] started with V 2.10. Previously, all of []{}
1062       were escaped, but {} are used in records to control the orientation of
1063       fields, so they should not have been escaped in the first place.
1064
1065       It would be nice to also escape | and <, but these characters are used
1066       in specifying fields and ports in records.
1067
1068       See the next couple of points for details.
1069
1070   Ports
1071       Ports are what Graphviz <http://www.graphviz.org/> calls those places
1072       on the outline of a node where edges leave and terminate.
1073
1074       The Graphviz <http://www.graphviz.org/> syntax for ports is a bit
1075       unusual:
1076
1077       •   This works: "node_name":port5
1078
1079       •   This doesn't: "node_name:port5"
1080
1081       Let me repeat - that is Graphviz syntax, not GraphViz2 syntax. In Perl,
1082       you must do this:
1083
1084               $graph -> add_edge(from => 'struct1:f1', to => 'struct2:f0', color => 'blue');
1085
1086       You don't have to quote all node names in Graphviz
1087       <http://www.graphviz.org/>, but some, such as digits, must be quoted,
1088       so I've decided to quote them all.
1089
1090   How labels interact with ports
1091       You can specify labels with ports in these ways:
1092
1093       •   As a string
1094
1095                   $graph -> add_node(name => 'struct3', label => "hello\nworld |{ b |{c|<here> d|e}| f}| g | h");
1096
1097           Here, the string contains a port (<here>), field markers (|), and
1098           orientation markers ({}).
1099
1100           Clearly, you must specify the field separator character '|'
1101           explicitly. In the next 2 cases, it is implicit.
1102
1103           Then you use $graph -> add_edge(...) to refer to those ports, if
1104           desired:
1105
1106                   $graph -> add_edge(from => 'struct1:f2', to => 'struct3:here', color => 'red');
1107
1108           The same label is specified in the next case.
1109
1110       •   As an arrayref of hashrefs
1111
1112           From scripts/record.2.pl:
1113
1114                   $graph -> add_node(name => 'struct3', label =>
1115                   [
1116                           {
1117                                   text => "hello\nworld",
1118                           },
1119                           {
1120                                   text => '{b',
1121                           },
1122                           {
1123                                   text => '{c',
1124                           },
1125                           {
1126                                   port => '<here>',
1127                                   text => 'd',
1128                           },
1129                           {
1130                                   text => 'e}',
1131                           },
1132                           {
1133                                   text => 'f}',
1134                           },
1135                           {
1136                                   text => 'g',
1137                           },
1138                           {
1139                                   text => 'h',
1140                           },
1141                   ]);
1142
1143           Each hashref is a field, and hence you do not specify the field
1144           separator character '|'.
1145
1146           Then you use $graph -> add_edge(...) to refer to those ports, if
1147           desired. Again, from scripts/record.2.pl:
1148
1149                   $graph -> add_edge(from => 'struct1:f2', to => 'struct3:here', color => 'red');
1150
1151           The same label is specified in the previous case.
1152
1153       •   As an arrayref of strings
1154
1155           From scripts/html.labels.1.pl:
1156
1157                   $graph -> add_node(name => 'Oakleigh', shape => 'record', color => 'blue',
1158                           label => ['West Oakleigh', 'East Oakleigh']);
1159
1160           Here, again, you do not specify the field separator character '|'.
1161
1162           What happens is that each string is taken to be the label of a
1163           field, and each field is given an auto-generated port name of the
1164           form "<port$n>", where $n starts from 1.
1165
1166           Here's how you refer to those ports, again from
1167           scripts/html.labels.1.pl:
1168
1169                   $graph -> add_edge(from => 'Murrumbeena', to => 'Oakleigh:port2',
1170                           color => 'green', label => '<Drive<br/>Run<br/>Sprint>');
1171
1172       See also the docs for the "add_node(name => $node_name, [%hash])"
1173       method.
1174
1175   Attributes for clusters
1176       Just use subgraph => {...}, because the code (as of V 2.22) accepts
1177       attributes belonging to either clusters or subgraphs.
1178
1179       An example attribute is "pencolor", which is used for clusters but not
1180       for subgraphs:
1181
1182               $graph->push_subgraph(
1183                       graph    => {label => 'Child the Second'},
1184                       name     => 'cluster Second subgraph',
1185                       node     => {color => 'magenta', shape => 'diamond'},
1186                       subgraph => {pencolor => 'white'}, # White hides the cluster's frame.
1187               );
1188               # other nodes or edges can be added within it...
1189               $graph->pop_subgraph;
1190

TODO

1192       •   Handle edges such as 1 -> 2 -> {A B}, as seen in Graphviz
1193           <http://www.graphviz.org/>'s graphs/directed/switch.gv
1194
1195           But how?
1196
1197       •   Validate parameters more carefully, e.g. to reject non-hashref
1198           arguments where appropriate
1199
1200           Some method parameter lists take keys whose value must be a
1201           hashref.
1202

A Extremely Short List of Other Graphing Software

1204       Axis Maps <http://www.axismaps.com/>.
1205
1206       Polygon Map Generation <http://www-cs-
1207       students.stanford.edu/~amitp/game-programming/polygon-map-generation/>.
1208       Read more on that here
1209       <http://blogs.perl.org/users/max_maischein/2011/06/display-your-
1210       data---randompoissondisc.html>.
1211
1212       Voronoi Applications
1213       <http://www.voronoi.com/wiki/index.php?title=Voronoi_Applications>.
1214

Thanks

1216       Many thanks are due to the people who chose to make Graphviz
1217       <http://www.graphviz.org/> Open Source.
1218
1219       And thanks to Leon Brocard <http://search.cpan.org/~lbrocard/>, who
1220       wrote GraphViz, and kindly gave me co-maint of the module.
1221

Version Numbers

1223       Version numbers < 1.00 represent development versions. From 1.00 up,
1224       they are production versions.
1225

Repository

1227       <https://github.com/ronsavage/GraphViz2.git>
1228

Author

1230       GraphViz2 was written by Ron Savage <ron@savage.net.au> in 2011.
1231
1232       Home page: <http://savage.net.au/index.html>.
1233
1235       Australian copyright (c) 2011, Ron Savage.
1236
1237               All Programs of mine are 'OSI Certified Open Source Software';
1238               you can redistribute them and/or modify them under the terms of
1239               The Perl License, a copy of which is available at:
1240               http://dev.perl.org/licenses/
1241
1242
1243
1244perl v5.32.1                      2021-01-27                      GraphViz2(3)
Impressum