1GraphViz2(3) User Contributed Perl Documentation GraphViz2(3)
2
6 GraphViz2 - A wrapper for AT&T's Graphviz
7
9 Sample output
10 See <https://graphviz-perl.github.io/>.
11 Perl code
13 Typical Usage
14 use strict;
16 use warnings;
17 use File::Spec;
18 use GraphViz2;
19 use Log::Handler;
21 my $logger = Log::Handler->new;
22 $logger->add(screen => {
23 maxlevel => 'debug', message_layout => '%m', minlevel => 'error'
24 });
25 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 $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 $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 $graph->default_node(color => 'cyan');
51 $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 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
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 It is called GraphViz2 so that pre-existing code using (the Perl
68 module) GraphViz continues to work.
69 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 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 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 To ensure GraphViz2 is a light-weight module, Moo has been used to
86 provide getters and setters, rather than Moose.
87 As of V 2.43, "GraphViz2" supports image maps, both client and server
89 side.
90 See "Image Maps" below.
92 What is a Graph?
94 An undirected graph is a collection of nodes optionally linked together
95 with edges.
96 A directed graph is the same, except that the edges have a direction,
98 normally indicated by an arrow head.
99 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
106 Of course you need to install AT&T's Graphviz before using this module.
107 See <http://www.graphviz.org/download/>.
108
110 Calling new()
111 "new()" is called as "my($obj) = GraphViz2 -> new(k1 => v1, k2 => v2,
112 ...)".
113 It returns a new object of type "GraphViz2".
115 Key-value pairs accepted in the parameter list:
117 edge => $hashref
119 The edge key points to a hashref which is used to set default
121 attributes for edges.
122 Hence, allowable keys and values within that hashref are anything
124 supported by Graphviz <http://www.graphviz.org/>.
125 The default is {}.
127 This key is optional.
129 global => $hashref
131 The global key points to a hashref which is used to set attributes for
133 the output stream.
134 This key is optional.
136 Valid keys within this hashref are:
138 combine_node_and_port
140 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 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 directed => $Boolean
156 This option affects the content of the output stream.
158 directed => 1 outputs 'digraph name {...}', while directed => 0 outputs
160 'graph name {...}'.
161 At the Perl level, directed graphs have edges with arrow heads, such as
163 '->', while undirected graphs have unadorned edges, such as '--'.
164 The default is 0.
166 This key is optional.
168 driver => $program_name
170 This option specifies which external program to run to process the
172 output stream.
173 The default is to use File::Which's which() method to find the 'dot'
175 program.
176 This key is optional.
178 format => $string
180 This option specifies what type of output file to create.
182 The default is 'svg'.
184 Output formats of the form 'png:gd' etc are also supported, but only
186 the component before the first ':' is validated by GraphViz2.
187 This key is optional.
189 label => $string
191 This option specifies what an edge looks like: '->' for directed graphs
193 and '--' for undirected graphs.
194 You wouldn't normally need to use this option.
196 The default is '->' if directed is 1, and '--' if directed is 0.
198 This key is optional.
200 name => $string
202 This option affects the content of the output stream.
204 name => 'G666' outputs 'digraph G666 {...}'.
206 The default is 'Perl' :-).
208 This key is optional.
210 record_shape => /^(?:M?record)$/
212 This option affects the shape of records. The value must be 'Mrecord'
214 or 'record'.
215 Mrecords have nice, rounded corners, whereas plain old records have
217 square corners.
218 The default is 'Mrecord'.
220 See Record shapes <http://www.graphviz.org/doc/info/shapes.html#record>
222 for details.
223 strict => $Boolean
225 This option affects the content of the output stream.
227 strict => 1 outputs 'strict digraph name {...}', while strict => 0
229 outputs 'digraph name {...}'.
230 The default is 0.
232 This key is optional.
234 timeout => $integer
236 This option specifies how long to wait for the external program before
238 exiting with an error.
239 The default is 10 (seconds).
241 This key is optional.
243 graph => $hashref
245 The graph key points to a hashref which is used to set default
247 attributes for graphs.
248 Hence, allowable keys and values within that hashref are anything
250 supported by Graphviz <http://www.graphviz.org/>.
251 The default is {}.
253 This key is optional.
255 logger => $logger_object
257 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 Retrieve and update the value with the logger() method.
264 By default (i.e. without a logger object), GraphViz2 prints warning and
266 debug messages to STDOUT, and dies upon errors.
267 However, by supplying a log object, you can capture these events.
269 Not only that, you can change the behaviour of your log object at any
271 time, by calling "logger($logger_object)".
272 See also the verbose option, which can interact with the logger option.
274 This key is optional.
276 node => $hashref
278 The node key points to a hashref which is used to set default
280 attributes for nodes.
281 Hence, allowable keys and values within that hashref are anything
283 supported by Graphviz <http://www.graphviz.org/>.
284 The default is {}.
286 This key is optional.
288 subgraph => $hashref
290 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 Valid keys within this hashref are:
296 • rank => $string
298 This option affects the content of all subgraphs, unless overridden
300 later.
301 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 See scripts/rank.sub.graph.1.pl for sample code.
307 Possible values for $string are: max, min, same, sink and source.
309 See the Graphviz 'rank' docs
311 <http://www.graphviz.org/doc/info/attrs.html#d:rank> for details.
312 The default is {}.
314 This key is optional.
316 verbose => $Boolean
318 Provides a way to control the amount of output when a logger is not
320 specified.
321 Setting verbose to 0 means print nothing.
323 Setting verbose to 1 means print the log level and the message to
325 STDOUT, when a logger is not specified.
326 Retrieve and update the value with the verbose() method.
328 The default is 0.
330 See also the logger option, which can interact with the verbose option.
332 This key is optional.
334 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 This mechanism has the effect of hard-coding Graphviz
342 <http://www.graphviz.org/> options in the source code of GraphViz2.
343 Nevertheless, the implementation of these lists is handled differently
345 from the way it was done in V 2.
346 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 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 See "Scripts Shipped with this Module" in GraphViz2.
357 Alternate constructor and object method
359 from_graph
360 my $gv = GraphViz2->from_graph($g);
362 # alternatively
364 my $gv = GraphViz2->new;
365 $gv->from_graph($g);
366 # for handy debugging of arbitrary graphs:
368 GraphViz2->from_graph($g)->run(format => 'svg', output_file => 'output.svg');
369 Takes a Graph object. This module will figure out various defaults from
371 it, including whether it is directed or not.
372 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 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 For a "multiedged" graph, will create one edge per multi-edge.
383 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 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 • attributes
393 Hash-ref of arguments to supply to "push_subgraph" for this
395 subgraph.
396 • nodes
398 Array-ref of node names to put in this subgraph.
400 Example:
402 $g->set_graph_attribute(graphviz => {
404 groups => [
405 {nodes => [1, 2], attributes => {subgraph=>{rank => 'same'}}},
406 ],
407 # other graph-level attributes...
408 });
409
411 Graph Scope
412 The graphical elements graph, node and edge, have attributes.
413 Attributes can be set when calling new().
414 Within new(), the defaults are graph => {}, node => {}, and edge => {}.
416 You override these with code such as new(edge => {color => 'red'}).
418 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 You change the 'current' attributes by calling any of the methods
424 default_edge(%hash), default_graph(%hash) and default_node(%hash).
425 See scripts/trivial.pl ("Scripts Shipped with this Module" in
427 GraphViz2) for an example.
428 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 This module, as with Graphviz <http://www.graphviz.org/>, defaults to
435 using inheritance of attributes.
436 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 After a single call to push_subgraph(%hash), these 'current' attributes
442 will live a level 1 in the scope stack.
443 See scripts/sub.graph.pl ("Scripts Shipped with this Module" in
445 GraphViz2) for an example.
446 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 Both GraphViz2 and Graphviz <http://www.graphviz.org/> handle this
452 situation properly.
453 See scripts/sub.sub.graph.pl ("Scripts Shipped with this Module" in
455 GraphViz2) for an example.
456 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 • A global frame
462 I can't see how to make the graph as a whole (at level 0 in the
464 scope stack) have a frame.
465 • Frame color
467 When you specify graph => {color => 'red'} at the parent level, the
469 subgraph has a red frame.
470 I think a subgraph should control its own frame.
472 • Parent and child frames
474 When you specify graph => {color => 'red'} at the subgraph level,
476 both that subgraph and it children have red frames.
477 This contradicts what happens at the global level, in that
479 specifying color there does not given the whole graph a frame.
480 • Frame visibility
482 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 For sample code, see scripts/sub.graph.frames.pl.
488 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 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
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 The Default URL
504 See the Graphviz docs for 'cmapx'
505 <http://www.graphviz.org/doc/info/output.html#d:cmapx>.
506 Their sample code has a dot file - x.gv - containing this line:
508 URL="http://www.research.att.com/base.html";
510 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 Thus you must do this to set a URL:
517 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 See maps/demo.3.pl and maps/demo.4.pl for sample code.
528 Typical Code
530 Normally you would call "run()" as:
531 $graph -> run
533 (
534 format => $format,
535 output_file => $output_file
536 );
537 That line was copied from scripts/cluster.pl.
539 To trigger image map processing, you must include 2 new parameters:
541 $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 That line was copied from maps/demo.3.pl, and there is an identical
551 line in maps/demo.4.pl.
552 The New Parameters to run()
554 • im_format => $str
555 Expected values: 'imap' (server-side) and 'cmapx' (client-side).
557 Default value: 'cmapx'.
559 • im_output_file => $file_name
561 The name of the output map file.
563 Default: ''.
565 If you do not set it to anything, the new image maps code is
567 ignored.
568 Sample Code
570 Various demos are shipped in the new maps/ directory:
571 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 • demo.1.*
578 This set demonstrates a server-side image map but does not use
580 "GraphViz2".
581 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 URL: your.domain.name/maps/demo.1.html.
586 • demo.2.*
588 This set demonstrates a client-side image map but does not use
590 "GraphViz2".
591 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 URL: your.domain.name/maps/demo.2.html.
598 • demo.3.*
600 This set demonstrates a server-side image map using "GraphViz2" via
602 demo.3.pl.
603 Note line 54 of demo.3.pl which sets the default "im_format" to
605 'imap'.
606 URL: your.domain.name/maps/demo.3.html.
608 • demo.4.*
610 This set demonstrates a client-side image map using "GraphViz2" via
612 demo.4.pl.
613 As with demo.2.* there is some manually editing to be done.
615 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 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 URL: your.domain.name/maps/demo.4.html.
626
628 add_edge(from => $from_node_name, to => $to_node_name, [label => $label,
629 %hash])
630 Adds an edge to the graph.
631 Returns $self to allow method chaining.
633 Here, [] indicate optional parameters.
635 Add a edge from 1 node to another.
637 $from_node_name and $to_node_name default to ''.
639 %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 To make the edge start or finish on a port, see
646 "combine_node_and_port".
647 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 Adds a node to the graph.
666 Returns $self to allow method chaining.
668 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 If you want anonymous nodes, see scripts/anonymous.pl in "Scripts
674 Shipped with this Module" in GraphViz2.
675 Here, [] indicates an optional parameter.
677 %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 The attribute name 'label' may point to a string or an arrayref.
684 If it is a string...
686 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 For records, the cells start horizontal. Each additional layer of
693 structure will switch the orientation between horizontal and vertical.
694 If it is an arrayref of strings...
696 • The node is forced to be a record
698 The actual shape, 'record' or 'Mrecord', is set globally, with:
700 my($graph) = GraphViz2 -> new
702 (
703 global => {record_shape => 'record'}, # Override default 'Mrecord'.
704 ...
705 );
706 Or set locally with:
708 $graph -> add_node(name => 'Three', label => ['Good', 'Bad'], shape => 'record');
710 • Each element in the array defines a field in the record
712 These fields are combined into a single node
714 • Each element is treated as a label
716 • Each label is given a port name (1 .. N) of the form
718 "port$port_count"
719 • Judicious use of '{' and '}' in the label can make this record
721 appear horizontally or vertically, and even nested
722 If it is an arrayref of hashrefs...
724 • The node is forced to be a record
726 The actual shape, 'record' or 'Mrecord', can be set globally or
728 locally, as explained just above.
729 • Each element in the array defines a field in the record
731 • Each element is treated as a hashref with keys 'text' and 'port'
733 The 'port' key is optional.
735 • The value of the 'text' key is the label
737 • The value of the 'port' key is the port
739 • Judicious use of '{' and '}' in the label can make this record
741 appear horizontally or vertically, and even nested
742 See scripts/html.labels.*.pl and scripts/record.*.pl for sample code.
744 See also "How labels interact with ports".
746 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 default_edge(%hash)
752 Sets defaults attributes for edges added subsequently.
753 Returns $self to allow method chaining.
755 %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 default_graph(%hash)
762 Sets defaults attributes for the graph.
763 Returns $self to allow method chaining.
765 %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 default_node(%hash)
772 Sets defaults attributes for nodes added subsequently.
773 Returns $self to allow method chaining.
775 %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 default_subgraph(%hash)
782 Sets defaults attributes for clusters and subgraphs.
783 Returns $self to allow method chaining.
785 %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 dot_input()
792 Returns the output stream, formatted nicely, to be passed to the
793 external program (e.g. dot).
794 dot_output()
796 Returns the output from calling the external program (e.g. dot).
797 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 This output is available even if run() does not write the output to a
803 file.
804 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 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 my($node_hash) = $graph -> node_hash;
815 my($edge_hash) = $graph -> edge_hash;
816 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 print "Node: $from\n";
823 print "\tAttributes: $s\n";
824 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 print "\tEdge: $from$$edge{from_port} -> $to$$edge{to_port}\n";
833 print "\t\tAttributes: $s\n";
834 }
835 }
836 }
837 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 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 {
846 attributes => {},
847 from_port => $from_port,
848 to_port => $to_port,
849 }
850 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 See scripts/report.nodes.and.edges.pl (a version of
856 scripts/html.labels.1.pl) for a complete example.
857 log([$level, $message])
859 Logs the message at the given log level.
860 Returns $self to allow method chaining.
862 Here, [] indicate optional parameters.
864 $level defaults to 'debug', and $message defaults to ''.
866 If called with $level eq 'error', it dies with $message.
868 logger($logger_object)
870 Gets or sets the log object.
871 Here, [] indicates an optional parameter.
873 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 my($node_hash) = $graph -> node_hash;
879 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 print "Node: $name\n";
886 print "\tAttributes: $s\n";
887 }
888 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 A bit more formally then, $$node_hash{$node_name} is a hashref where
894 each element describes one node, and which defaults to:
895 {
897 attributes => {},
898 }
899 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 pop_subgraph()
905 Pop off and discard the top element of the scope stack.
906 Returns $self to allow method chaining.
908 push_subgraph([name => $name, edge => {...}, graph => {...}, node => {...},
910 subgraph => {...}])
911 Sets up a new subgraph environment.
912 Returns $self to allow method chaining.
914 Here, [] indicate optional parameters.
916 name => $name is the name to assign to the subgraph. Name defaults to
918 ''.
919 So, without $name, 'subgraph {' is written to the output stream.
921 With $name, 'subgraph "$name" {' is written to the output stream.
923 Note that subgraph names beginning with 'cluster' are special to
925 Graphviz <http://www.graphviz.org/doc/info/attrs.html#d:clusterrank>.
926 See scripts/rank.sub.graph.[1234].pl for the effect of various values
928 for $name.
929 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 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 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 subgraph => {..} is for setting attributes applicable to clusters and
946 subgraphs.
947 Currently the only subgraph attribute is "rank", but clusters have many
949 attributes available.
950 See the second column of the Graphviz attribute docs
952 <https://www.graphviz.org/doc/info/attrs.html> for details.
953 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 See scripts/rank.sub.graph.[12].pl and scripts/sub.graph.frames.pl for
959 sample code.
960 valid_attributes()
962 Returns a hashref of all attributes known to this module, keyed by type
963 to hashrefs to true values.
964 Stored in this module, using Data::Section::Simple.
966 These attributes are used to validate attributes in many situations.
968 You wouldn't normally need to use this method.
970 See scripts/report.valid.attributes.pl. See "Scripts Shipped with this
972 Module" in GraphViz2.
973 run([driver => $exe, format => $string, timeout => $integer, output_file =>
975 $output_file])
976 Runs the given program to process the output stream.
977 Returns $self to allow method chaining.
979 Here, [] indicate optional parameters.
981 $driver is the name of the external program to run.
983 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 $format is the type of output file to write.
989 It defaults to the value supplied in the call to new(global => {format
991 => '...'}), which in turn defaults to 'svg'.
992 $timeout is the time in seconds to wait while the external program
994 runs, before dieing with an error.
995 It defaults to the value supplied in the call to new(global => {timeout
997 => '...'}), which in turn defaults to 10.
998 $output_file is the name of the file into which the output from the
1000 external program is written.
1001 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 This method performs a series of tasks:
1007 • Run the chosen external program on the "dot_input"
1009 • Capture STDOUT and STDERR from that program
1011 • Die if STDERR contains anything
1013 • Copies STDOUT to the buffer controlled by the dot_output() method
1015 • Write the captured contents of STDOUT to $output_file, if
1017 $output_file has a value
1018 stringify_attributes($context, $option)
1020 Returns a string suitable to writing to the output stream.
1021 $context is one of 'edge', 'graph', 'node', or a special string. See
1023 the code for details.
1024 You wouldn't normally need to use this method.
1026 validate_params($context, \%attributes)
1028 Validate the given attributes within the given context.
1029 Also, if $context is 'subgraph', attributes are allowed to be in the
1031 'cluster' context.
1032 Returns $self to allow method chaining.
1034 $context is one of 'edge', 'global', 'graph', or 'node'.
1036 You wouldn't normally need to use this method.
1038 verbose([$integer])
1040 Gets or sets the verbosity level, for when a logging object is not
1041 used.
1042 Here, [] indicates an optional parameter.
1044
1046 Graphviz version supported
1047 GraphViz2 targets V 2.34.0 of Graphviz <http://www.graphviz.org/>.
1048 This affects the list of available attributes per graph item (node,
1050 edge, cluster, etc) available.
1051 See the second column of the Graphviz attribute docs
1053 <https://www.graphviz.org/doc/info/attrs.html> for details.
1054 Supported file formats
1056 Parses the output of "dot -T?", so depends on local installation.
1057 Special characters in node names and labels
1059 GraphViz2 escapes these 2 characters in those contexts: [].
1060 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 It would be nice to also escape | and <, but these characters are used
1066 in specifying fields and ports in records.
1067 See the next couple of points for details.
1069 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 The Graphviz <http://www.graphviz.org/> syntax for ports is a bit
1075 unusual:
1076 • This works: "node_name":port5
1078 • This doesn't: "node_name:port5"
1080 Let me repeat - that is Graphviz syntax, not GraphViz2 syntax. In Perl,
1082 you must do this:
1083 $graph -> add_edge(from => 'struct1:f1', to => 'struct2:f0', color => 'blue');
1085 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 How labels interact with ports
1091 You can specify labels with ports in these ways:
1092 • As a string
1094 $graph -> add_node(name => 'struct3', label => "hello\nworld |{ b |{c|<here> d|e}| f}| g | h");
1096 Here, the string contains a port (<here>), field markers (|), and
1098 orientation markers ({}).
1099 Clearly, you must specify the field separator character '|'
1101 explicitly. In the next 2 cases, it is implicit.
1102 Then you use $graph -> add_edge(...) to refer to those ports, if
1104 desired:
1105 $graph -> add_edge(from => 'struct1:f2', to => 'struct3:here', color => 'red');
1107 The same label is specified in the next case.
1109 • As an arrayref of hashrefs
1111 From scripts/record.2.pl:
1113 $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 Each hashref is a field, and hence you do not specify the field
1144 separator character '|'.
1145 Then you use $graph -> add_edge(...) to refer to those ports, if
1147 desired. Again, from scripts/record.2.pl:
1148 $graph -> add_edge(from => 'struct1:f2', to => 'struct3:here', color => 'red');
1150 The same label is specified in the previous case.
1152 • As an arrayref of strings
1154 From scripts/html.labels.1.pl:
1156 $graph -> add_node(name => 'Oakleigh', shape => 'record', color => 'blue',
1158 label => ['West Oakleigh', 'East Oakleigh']);
1159 Here, again, you do not specify the field separator character '|'.
1161 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 Here's how you refer to those ports, again from
1167 scripts/html.labels.1.pl:
1168 $graph -> add_edge(from => 'Murrumbeena', to => 'Oakleigh:port2',
1170 color => 'green', label => '<Drive<br/>Run<br/>Sprint>');
1171 See also the docs for the "add_node(name => $node_name, [%hash])"
1173 method.
1174 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 An example attribute is "pencolor", which is used for clusters but not
1180 for subgraphs:
1181 $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
1192 • Handle edges such as 1 -> 2 -> {A B}, as seen in Graphviz
1193 <http://www.graphviz.org/>'s graphs/directed/switch.gv
1194 But how?
1196 • Validate parameters more carefully, e.g. to reject non-hashref
1198 arguments where appropriate
1199 Some method parameter lists take keys whose value must be a
1201 hashref.
1202
1204 Axis Maps <http://www.axismaps.com/>.
1205 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 Voronoi Applications
1213 <http://www.voronoi.com/wiki/index.php?title=Voronoi_Applications>.
1214
1216 Many thanks are due to the people who chose to make Graphviz
1217 <http://www.graphviz.org/> Open Source.
1218 And thanks to Leon Brocard <http://search.cpan.org/~lbrocard/>, who
1220 wrote GraphViz, and kindly gave me co-maint of the module.
1221
1223 Version numbers < 1.00 represent development versions. From 1.00 up,
1224 they are production versions.
1225
1227 <https://github.com/ronsavage/GraphViz2.git>
1228
1230 GraphViz2 was written by Ron Savage <ron@savage.net.au> in 2011.
1231 Home page: <http://savage.net.au/index.html>.
1233
1235 Australian copyright (c) 2011, Ron Savage.
1236 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/
1241perl v5.32.1 2021-01-27 GraphViz2(3)