1GraphViz2(3) User Contributed Perl Documentation GraphViz2(3)
2
6 GraphViz2 - A wrapper for AT&T's Graphviz
7
9 Sample output
10 Unpack the distro and copy html/*.html and html/*.svg to your web
11 server's doc root directory.
12 Then, point your browser at 127.0.0.1/index.html.
14 Or, hit the demo page <http://savage.net.au/Perl-
16 modules/html/graphviz2/index.html>.
17 Perl code
19 Typical Usage
20 #!/usr/bin/env perl
22 use strict;
24 use warnings;
25 use File::Spec;
27 use GraphViz2;
29 use Log::Handler;
31 # ---------------
33 my($logger) = Log::Handler -> new;
35 $logger -> add
37 (
38 screen =>
39 {
40 maxlevel => 'debug',
41 message_layout => '%m',
42 minlevel => 'error',
43 }
44 );
45 my($graph) = GraphViz2 -> new
47 (
48 edge => {color => 'grey'},
49 global => {directed => 1},
50 graph => {label => 'Adult', rankdir => 'TB'},
51 logger => $logger,
52 node => {shape => 'oval'},
53 );
54 $graph -> add_node(name => 'Carnegie', shape => 'circle');
56 $graph -> add_node(name => 'Murrumbeena', shape => 'box', color => 'green');
57 $graph -> add_node(name => 'Oakleigh', color => 'blue');
58 $graph -> add_edge(from => 'Murrumbeena', to => 'Carnegie', arrowsize => 2);
60 $graph -> add_edge(from => 'Murrumbeena', to => 'Oakleigh', color => 'brown');
61 $graph -> push_subgraph
63 (
64 name => 'cluster_1',
65 graph => {label => 'Child'},
66 node => {color => 'magenta', shape => 'diamond'},
67 );
68 $graph -> add_node(name => 'Chadstone', shape => 'hexagon');
70 $graph -> add_node(name => 'Waverley', color => 'orange');
71 $graph -> add_edge(from => 'Chadstone', to => 'Waverley');
73 $graph -> pop_subgraph;
75 $graph -> default_node(color => 'cyan');
77 $graph -> add_node(name => 'Malvern');
79 $graph -> add_node(name => 'Prahran', shape => 'trapezium');
80 $graph -> add_edge(from => 'Malvern', to => 'Prahran');
82 $graph -> add_edge(from => 'Malvern', to => 'Murrumbeena');
83 my($format) = shift || 'svg';
85 my($output_file) = shift || File::Spec -> catfile('html', "sub.graph.$format");
86 $graph -> run(format => $format, output_file => $output_file);
88 This program ships as scripts/sub.graph.pl. See "Scripts Shipped with
90 this Module".
91 Image Maps Usage
93 As of V 2.43, "GraphViz2" supports image maps, both client and server
95 side.
96 See "Image Maps" below.
98
100 Overview
101 This module provides a Perl interface to the amazing Graphviz
102 <http://www.graphviz.org/>, an open source graph visualization tool
103 from AT&T.
104 It is called GraphViz2 so that pre-existing code using (the Perl
106 module) GraphViz continues to work.
107 To avoid confusion, when I use GraphViz2 (note the capital V), I'm
109 referring to this Perl module, and when I use Graphviz
110 <http://www.graphviz.org/> (lower-case v) I'm referring to the
111 underlying tool (which is in fact a set of programs).
112 Version 1.00 of GraphViz2 is a complete re-write, by Ron Savage, of
114 GraphViz V 2, which was written by Leon Brocard. The point of the re-
115 write is to provide access to all the latest options available to users
116 of Graphviz <http://www.graphviz.org/>.
117 GraphViz2 V 1 is not backwards compatible with GraphViz V 2, despite
119 the considerable similarity. It was not possible to maintain
120 compatibility while extending support to all the latest features of
121 Graphviz <http://www.graphviz.org/>.
122 To ensure GraphViz2 is a light-weight module, Moo has been used to
124 provide getters and setters, rather than Moose.
125 As of V 2.43, "GraphViz2" supports image maps, both client and server
127 side.
128 See "Image Maps" below.
130 What is a Graph?
132 An undirected graph is a collection of nodes optionally linked together
133 with edges.
134 A directed graph is the same, except that the edges have a direction,
136 normally indicated by an arrow head.
137 A quick inspection of Graphviz <http://www.graphviz.org/>'s gallery
139 <http://www.graphviz.org/Gallery.php> will show better than words just
140 how good Graphviz <http://www.graphviz.org/> is, and will reinforce the
141 point that humans are very visual creatures.
142
144 This module is available as a Unix-style distro (*.tgz).
145 See <http://savage.net.au/Perl-modules/html/installing-a-module.html>
147 for help on unpacking and installing distros.
148
150 Of course you need to install AT&T's Graphviz before using this module.
151 See <http://www.graphviz.org/Download.php>.
152 You are strongly advised to download the stable version of Graphviz,
154 because the development snapshots (click on 'Source code'), are
155 sometimes non-functional.
156 Install GraphViz2 as you would for any "Perl" module:
158 Run:
160 cpanm GraphViz2
162 Note: cpanm ships in App::cpanminus. See also App::perlbrew.
164 or run:
166 sudo cpan GraphViz2
168 or unpack the distro, and then either:
170 perl Build.PL
172 ./Build
173 ./Build test
174 sudo ./Build install
175 or:
177 perl Makefile.PL
179 make (or dmake or nmake)
180 make test
181 make install
182
184 Calling new()
185 "new()" is called as "my($obj) = GraphViz2 -> new(k1 => v1, k2 => v2,
186 ...)".
187 It returns a new object of type "GraphViz2".
189 Key-value pairs accepted in the parameter list:
191 o edge => $hashref
193 The edge key points to a hashref which is used to set default
194 attributes for edges.
195 Hence, allowable keys and values within that hashref are anything
197 supported by Graphviz <http://www.graphviz.org/>.
198 The default is {}.
200 This key is optional.
202 o global => $hashref
204 The global key points to a hashref which is used to set attributes
205 for the output stream.
206 Valid keys within this hashref are:
208 o directed => $Boolean
210 This option affects the content of the output stream.
211 directed => 1 outputs 'digraph name {...}', while directed => 0
213 outputs 'graph name {...}'.
214 At the Perl level, directed graphs have edges with arrow heads,
216 such as '->', while undirected graphs have unadorned edges,
217 such as '--'.
218 The default is 0.
220 This key is optional.
222 o driver => $program_name
224 This option specifies which external program to run to process
225 the output stream.
226 The default is to use File::Which's which() method to find the
228 'dot' program.
229 This key is optional.
231 o format => $string
233 This option specifies what type of output file to create.
234 The default is 'svg'.
236 Output formats of the form 'png:gd' etc are also supported, but
238 only the component before the first ':' is validated by
239 GraphViz2.
240 This key is optional.
242 o label => $string
244 This option specifies what an edge looks like: '->' for
245 directed graphs and '--' for undirected graphs.
246 You wouldn't normally need to use this option.
248 The default is '->' if directed is 1, and '--' if directed is
250 0.
251 This key is optional.
253 o name => $string
255 This option affects the content of the output stream.
256 name => 'G666' outputs 'digraph G666 {...}'.
258 The default is 'Perl' :-).
260 This key is optional.
262 o record_shape => /^(?:M?record)$/
264 This option affects the shape of records. The value must be
265 'Mrecord' or 'record'.
266 Mrecords have nice, rounded corners, whereas plain old records
268 have square corners.
269 The default is 'Mrecord'.
271 See Record shapes <http://www.graphviz.org/content/node-
273 shapes#record> for details.
274 o strict => $Boolean
276 This option affects the content of the output stream.
277 strict => 1 outputs 'strict digraph name {...}', while strict
279 => 0 outputs 'digraph name {...}'.
280 The default is 0.
282 This key is optional.
284 o subgraph => $hashref
286 The subgraph key points to a hashref which is used to set
287 attributes for all subgraphs, unless overridden for specific
288 subgraphs in a call of the form push_subgraph(subgraph =>
289 {$attribute => $string}).
290 Valid keys within this hashref are:
292 o rank => $string
294 This option affects the content of all subgraphs, unless
295 overridden later.
296 A typical usage would be new(subgraph => {rank => 'same'})
298 so that all nodes mentioned within each subgraph are
299 constrained to be horizontally aligned.
300 See scripts/rank.sub.graph.[12].pl for sample code.
302 Possible values for $string are: max, min, same, sink and
304 source.
305 See the Graphviz 'rank' docs
307 <http://www.graphviz.org/content/attrs#drank> for details.
308 The default is {}.
310 This key is optional.
312 o timeout => $integer
314 This option specifies how long to wait for the external program
315 before exiting with an error.
316 The default is 10 (seconds).
318 This key is optional.
320 This key (global) is optional.
322 o graph => $hashref
324 The graph key points to a hashref which is used to set default
325 attributes for graphs.
326 Hence, allowable keys and values within that hashref are anything
328 supported by Graphviz <http://www.graphviz.org/>.
329 The default is {}.
331 This key is optional.
333 o logger => $logger_object
335 Provides a logger object so $logger_object -> $level($message) can
336 be called at certain times.
337 See "Why such a different approach to logging?" in the </FAQ> for
339 details.
340 Retrieve and update the value with the logger() method.
342 The default is ''.
344 See also the verbose option, which can interact with the logger
346 option.
347 This key is optional.
349 o node => $hashref
351 The node key points to a hashref which is used to set default
352 attributes for nodes.
353 Hence, allowable keys and values within that hashref are anything
355 supported by Graphviz <http://www.graphviz.org/>.
356 The default is {}.
358 This key is optional.
360 o verbose => $Boolean
362 Provides a way to control the amount of output when a logger is not
363 specified.
364 Setting verbose to 0 means print nothing.
366 Setting verbose to 1 means print the log level and the message to
368 STDOUT, when a logger is not specified.
369 Retrieve and update the value with the verbose() method.
371 The default is 0.
373 See also the logger option, which can interact with the verbose
375 option.
376 This key is optional.
378 Validating Parameters
380 The secondary keys (under the primary keys 'edge|graph|node') are
381 checked against lists of valid attributes (stored at the end of this
382 module, after the __DATA__ token, and made available using
383 Data::Section::Simple).
384 This mechanism has the effect of hard-coding Graphviz
386 <http://www.graphviz.org/> options in the source code of GraphViz2.
387 Nevertheless, the implementation of these lists is handled differently
389 from the way it was done in V 2.
390 V 2 ships with a set of scripts, scripts/extract.*.pl, which retrieve
392 pages from the Graphviz <http://www.graphviz.org/> web site and extract
393 the current lists of valid attributes.
394 These are then copied manually into the source code of GraphViz2,
396 meaning any time those lists change on the Graphviz
397 <http://www.graphviz.org/> web site, it's a trivial matter to update
398 the lists stored within this module.
399 See "Scripts Shipped with this Module" in GraphViz2.
401
403 Graph Scope
404 The graphical elements graph, node and edge, have attributes.
405 Attributes can be set when calling new().
406 Within new(), the defaults are graph => {}, node => {}, and edge => {}.
408 You override these with code such as new(edge => {color => 'red'}).
410 These attributes are pushed onto a scope stack during new()'s
412 processing of its parameters, and they apply thereafter until changed.
413 They are the 'current' attributes. They live at scope level 0 (zero).
414 You change the 'current' attributes by calling any of the methods
416 default_edge(%hash), default_graph(%hash) and default_node(%hash).
417 See scripts/trivial.pl ("Scripts Shipped with this Module" in
419 GraphViz2) for an example.
420 Subgraph Scope
422 When you wish to create a subgraph, you call push_subgraph(%hash). The
423 word push emphasises that you are moving into a new scope, and that the
424 default attributes for the new scope are pushed onto the scope stack.
425 This module, as with Graphviz <http://www.graphviz.org/>, defaults to
427 using inheritance of attributes.
428 That means the parent's 'current' attributes are combined with the
430 parameters to push_subgraph(%hash) to generate a new set of 'current'
431 attributes for each of the graphical elements, graph, node and edge.
432 After a single call to push_subgraph(%hash), these 'current' attributes
434 will live a level 1 in the scope stack.
435 See scripts/sub.graph.pl ("Scripts Shipped with this Module" in
437 GraphViz2) for an example.
438 Another call to push_subgraph(%hash), without an intervening call to
440 pop_subgraph(), will repeat the process, leaving you with a set of
441 attributes at level 2 in the scope stack.
442 Both GraphViz2 and Graphviz <http://www.graphviz.org/> handle this
444 situation properly.
445 See scripts/sub.sub.graph.pl ("Scripts Shipped with this Module" in
447 GraphViz2) for an example.
448 At the moment, due to design defects (IMHO) in the underlying Graphviz
450 <http://www.graphviz.org/> logic, there are some tiny problems with
451 this:
452 o A global frame
454 I can't see how to make the graph as a whole (at level 0 in the
455 scope stack) have a frame.
456 o Frame color
458 When you specify graph => {color => 'red'} at the parent level, the
459 subgraph has a red frame.
460 I think a subgraph should control its own frame.
462 o Parent and child frames
464 When you specify graph => {color => 'red'} at the subgraph level,
465 both that subgraph and it children have red frames.
466 This contradicts what happens at the global level, in that
468 specifying color there does not given the whole graph a frame.
469 o Frame visibility
471 A subgraph whose name starts with 'cluster' is currently forced to
472 have a frame, unless you rig it by specifying a color the same as
473 the background.
474 For sample code, see scripts/sub.graph.frames.pl.
476 Also, check the pencolor docs
478 <http://www.graphviz.org/content/attrs#dpencolor> for how the color of
479 the frame is chosen by cascading thru a set of options.
480 I've posted an email to the Graphviz <http://www.graphviz.org/> mailing
482 list suggesting a new option, framecolor, so deal with this issue,
483 including a special color of 'invisible'.
484
486 As of V 2.43, "GraphViz2" supports image maps, both client and server
487 side.
488 The Default URL
490 See the Graphviz docs for 'cmapx'
491 <http://www.graphviz.org/doc/info/output.html#d:cmapx>.
492 Their sample code has a dot file - x.gv - containing this line:
494 URL="http://www.research.att.com/base.html";
496 The way you set such a url in "GraphViz2" is via a new parameter to
498 "new()". This parameter is called "im_meta" and it takes a hashref as a
499 value. Currently the only key used within that hashref is the case-
500 sensitive "URL".
501 Thus you must do this to set a URL:
503 my($graph) = GraphViz2 -> new
505 (
506 ...
507 im_meta =>
508 {
509 URL => 'http://savage.net.au/maps/demo.3.1.html', # Note: URL must be in caps.
510 },
511 );
512 See maps/demo.3.pl and maps/demo.4.pl for sample code.
514 Typical Code
516 Normally you would call "run()" as:
517 $graph -> run
519 (
520 format => $format,
521 output_file => $output_file
522 );
523 That line was copied from scripts/cluster.pl.
525 To trigger image map processing, you must include 2 new parameters:
527 $graph -> run
529 (
530 format => $format,
531 output_file => $output_file,
532 im_format => $im_format,
533 im_output_file => $im_output_file
534 );
535 That line was copied from maps/demo.3.pl, and there is an identical
537 line in maps/demo.4.pl.
538 The New Parameters to run()
540 o im_format => $str
541 Expected values: 'imap' (server-side) and 'cmapx' (client-side).
542 Default value: 'cmapx'.
544 o im_output_file => $file_name
546 The name of the output map file.
547 Default: ''.
549 Sample Code
551 Various demos are shipped in the new maps/ directory:
552 Each demo, when FTPed to your web server displays some text with an
554 image in the middle. In each case you can click on the upper oval to
555 jump to one page, or click on the lower oval to jump to a different
556 page, or click anywhere else in the image to jump to a third page.
557 o demo.1.*
559 This set demonstrates a server-side image map but does not use
560 "GraphViz2".
561 You have to run demo.1.sh which generates demo.1.map, and then you
563 FTP the whole dir maps/ to your web server.
564 URL: your.domain.name/maps/demo.1.html.
566 o demo.2.*
568 This set demonstrates a client-side image map but does not use
569 "GraphViz2".
570 You have to run demo.2.sh which generates demo.2.map, and then you
572 manually copy demo.2.map into demo.2.html, replacing any version of
573 the map already present. After that you FTP the whole dir maps/ to
574 your web server.
575 URL: your.domain.name/maps/demo.2.html.
577 o demo.3.*
579 This set demonstrates a server-side image map using "GraphViz2" via
580 demo.3.pl.
581 Note line 54 of demo.3.pl which sets the default "im_format" to
583 'imap'.
584 URL: your.domain.name/maps/demo.3.html.
586 o demo.4.*
588 This set demonstrates a client-side image map using "GraphViz2" via
589 demo.4.pl.
590 As with demo.2.* there is some manually editing to be done.
592 Note line 54 of demo.4.pl which sets the default "im_format" to
594 'cmapx'. This is the only important difference between this demo
595 and the previous one.
596 There are other minor differences, in that one uses 'svg' and the
598 other 'png'. And of course the urls of the web pages embedded in
599 the code and in those web pages differs, just to demonstate that
600 the maps do indeed lead to different pages.
601 URL: your.domain.name/maps/demo.4.html.
603
605 add_edge(from => $from_node_name, to => $to_node_name, [label => $label,
606 %hash])
607 Adds an edge to the graph.
608 Returns $self to allow method chaining.
610 Here, [] indicate optional parameters.
612 Add a edge from 1 node to another.
614 $from_node_name and $to_node_name default to ''.
616 If either of these node names is unknown, add_node(name => $node_name)
618 is called automatically. The lack of attributes in this call means such
619 nodes are created with the default set of attributes, and that may not
620 be what you want. To avoid this, you have to call add_node(...)
621 yourself, with the appropriate attributes, before calling
622 add_edge(...).
623 %hash is any edge attributes accepted as Graphviz attributes
625 <http://www.graphviz.org/content/attrs>. These are validated in exactly
626 the same way as the edge parameters in the calls to
627 default_edge(%hash), new(edge => {}) and push_subgraph(edge => {}).
628 add_node(name => $node_name, [%hash])
630 Adds a node to the graph.
631 Returns $self to allow method chaining.
633 If you want to embed newlines or double-quotes in node names or labels,
635 see scripts/quote.pl in "Scripts Shipped with this Module" in
636 GraphViz2.
637 If you want anonymous nodes, see scripts/anonymous.pl in "Scripts
639 Shipped with this Module" in GraphViz2.
640 Here, [] indicates an optional parameter.
642 %hash is any node attributes accepted as Graphviz attributes
644 <http://www.graphviz.org/content/attrs>. These are validated in exactly
645 the same way as the node parameters in the calls to
646 default_node(%hash), new(node => {}) and push_subgraph(node => {}).
647 The attribute name 'label' may point to a string or an arrayref.
649 If it is a string...
651 The string is the label.
653 The string may contain ports and orientation markers ({}).
655 If it is an arrayref of strings...
657 o The node is forced to be a record
659 The actual shape, 'record' or 'Mrecord', is set globally, with:
660 my($graph) = GraphViz2 -> new
662 (
663 global => {record_shape => 'record'}, # Override default 'Mrecord'.
664 ...
665 );
666 Or set locally with:
668 $graph -> add_node(name => 'Three', label => ['Good', 'Bad'], shape => 'record');
670 o Each element in the array defines a field in the record
672 These fields are combined into a single node
673 o Each element is treated as a label
675 o Each label is given a port name (1 .. N) of the form
676 "port<$port_count>"
677 o Judicious use of '{' and '}' in the label can make this record appear
678 horizontally or vertically, and even nested
679 If it is an arrayref of hashrefs...
681 o The node is forced to be a record
683 The actual shape, 'record' or 'Mrecord', can be set globally or
684 locally, as explained just above.
685 o Each element in the array defines a field in the record
687 o Each element is treated as a hashref with keys 'text' and 'port'
688 The 'port' key is optional.
689 o The value of the 'text' key is the label
691 o The value of the 'port' key is the port
692 The format is "<$port_name>".
693 o Judicious use of '{' and '}' in the label can make this record appear
695 horizontally or vertically, and even nested
696 See scripts/html.labels.*.pl and scripts/record.*.pl for sample code.
698 See also the FAQ topic "How labels interact with ports".
700 For more details on this complex topic, see Records
702 <http://www.graphviz.org/content/node-shapes#record> and Ports
703 <http://www.graphviz.org/content/attrs#kportPos>.
704 default_edge(%hash)
706 Sets defaults attributes for edges added subsequently.
707 Returns $self to allow method chaining.
709 %hash is any edge attributes accepted as Graphviz attributes
711 <http://www.graphviz.org/content/attrs>. These are validated in exactly
712 the same way as the edge parameters in the calls to new(edge => {}) and
713 push_subgraph(edge => {}).
714 default_graph(%hash)
716 Sets defaults attributes for the graph.
717 Returns $self to allow method chaining.
719 %hash is any graph attributes accepted as Graphviz attributes
721 <http://www.graphviz.org/content/attrs>. These are validated in exactly
722 the same way as the graph parameter in the calls to new(graph => {})
723 and push_subgraph(graph => {}).
724 default_node(%hash)
726 Sets defaults attributes for nodes added subsequently.
727 Returns $self to allow method chaining.
729 %hash is any node attributes accepted as Graphviz attributes
731 <http://www.graphviz.org/content/attrs>. These are validated in exactly
732 the same way as the node parameters in the calls to new(node => {}) and
733 push_subgraph(node => {}).
734 default_subgraph(%hash)
736 Sets defaults attributes for clusters and subgraphs.
737 Returns $self to allow method chaining.
739 %hash is any cluster or subgraph attribute accepted as Graphviz
741 attributes <http://www.graphviz.org/content/attrs>. These are validated
742 in exactly the same way as the subgraph parameter in the calls to
743 new(subgraph => {}) and push_subgraph(subgraph => {}).
744 dot_input()
746 Returns the output stream, formatted nicely, which was passed to the
747 external program (e.g. dot).
748 You must call run() before calling dot_input(), since it is only during
750 the call to run() that the output stream is stored in the buffer
751 controlled by dot_input().
752 dot_output()
754 Returns the output from calling the external program (e.g. dot).
755 You must call run() before calling dot_output(), since it is only
757 during the call to run() that the output of the external program is
758 stored in the buffer controlled by dot_output().
759 This output is available even if run() does not write the output to a
761 file.
762 edge_hash()
764 Returns, at the end of the run, a hashref keyed by node name,
765 specifically the node at the arrowtail end of the hash, i.e. where the
766 edge starts from.
767 Use this to get a list of all nodes and the edges which leave those
769 nodes, the corresponding destination nodes, and the attributes of each
770 edge.
771 my($node_hash) = $graph -> node_hash;
773 my($edge_hash) = $graph -> edge_hash;
774 for my $from (sort keys %$node_hash)
776 {
777 my($attr) = $$node_hash{$from}{attributes};
778 my($s) = join(', ', map{"$_ => $$attr{$_}"} sort keys %$attr);
779 print "Node: $from\n";
781 print "\tAttributes: $s\n";
782 for my $to (sort keys %{$$edge_hash{$from} })
784 {
785 for my $edge (@{$$edge_hash{$from}{$to} })
786 {
787 $attr = $$edge{attributes};
788 $s = join(', ', map{"$_ => $$attr{$_}"} sort keys %$attr);
789 print "\tEdge: $from$$edge{from_port} -> $to$$edge{to_port}\n";
791 print "\t\tAttributes: $s\n";
792 }
793 }
794 }
795 If the caller adds the same edge two (or more) times, the attributes
797 from each call are not coalesced (unlike "node_hash()"), but rather the
798 attributes from each call are stored separately in an arrayref.
799 A bit more formally then, $$edge_hash{$from_node}{$to_node} is an
801 arrayref where each element describes one edge, and which defaults to:
802 {
804 attributes => {},
805 from_port => $from_port,
806 to_port => $to_port,
807 }
808 If from_port is not provided by the caller, it defaults to '' (the
810 empty string). If it is provided, it contains a leading ':'. Likewise
811 for to_port.
812 See scripts/report.nodes.and.edges.pl (a version of
814 scripts/html.labels.1.pl) for a complete example.
815 escape_some_chars($s)
817 Escapes various chars in various circumstances, because some chars are
818 treated specially by Graphviz.
819 See the "FAQ" for a discussion of this tricky topic.
821 load_valid_attributes()
823 Load various sets of valid attributes from within the source code of
824 this module, using Data::Section::Simple.
825 Returns $self to allow method chaining.
827 These attributes are used to validate attributes in many situations.
829 You wouldn't normally need to use this method.
831 log([$level, $message])
833 Logs the message at the given log level.
834 Returns $self to allow method chaining.
836 Here, [] indicate optional parameters.
838 $level defaults to 'debug', and $message defaults to ''.
840 If called with $level eq 'error', it dies with $message.
842 logger($logger_object)
844 Gets or sets the log object.
845 Here, [] indicates an optional parameter.
847 node_hash()
849 Returns, at the end of the run, a hashref keyed by node name. Use this
850 to get a list of all nodes and their attributes.
851 my($node_hash) = $graph -> node_hash;
853 for my $name (sort keys %$node_hash)
855 {
856 my($attr) = $$node_hash{$name}{attributes};
857 my($s) = join(', ', map{"$_ => $$attr{$_}"} sort keys %$attr);
858 print "Node: $name\n";
860 print "\tAttributes: $s\n";
861 }
862 If the caller adds the same node two (or more) times, the attributes
864 from each call are coalesced (unlike "edge_hash()"), meaning all
865 attributes from all calls are combined under the attributes sub-key.
866 A bit more formally then, $$node_hash{$node_name} is a hashref where
868 each element describes one node, and which defaults to:
869 {
871 attributes => {},
872 }
873 See scripts/report.nodes.and.edges.pl (a version of
875 scripts/html.labels.1.pl) for a complete example, including usage of
876 the corresponding "edge_hash()" method.
877 pop_subgraph()
879 Pop off and discard the top element of the scope stack.
880 Returns $self to allow method chaining.
882 push_subgraph([name => $name, edge => {...}, graph => {...}, node => {...},
884 subgraph => {...}])
885 Sets up a new subgraph environment.
886 Returns $self to allow method chaining.
888 Here, [] indicate optional parameters.
890 name => $name is the name to assign to the subgraph. Name defaults to
892 ''.
893 So, without $name, 'subgraph {' is written to the output stream.
895 With $name, 'subgraph "$name" {' is written to the output stream.
897 Note that subgraph names beginning with 'cluster' are special to
899 Graphviz <http://www.graphviz.org/content/attrs#dclusterrank>.
900 See scripts/rank.sub.graph.[1234].pl for the effect of various values
902 for $name.
903 edge => {...} is any edge attributes accepted as Graphviz attributes
905 <http://www.graphviz.org/content/attrs>. These are validated in exactly
906 the same way as the edge parameters in the calls to
907 default_edge(%hash), new(edge => {}) and push_subgraph(edge => {}).
908 graph => {...} is any graph attributes accepted as Graphviz attributes
910 <http://www.graphviz.org/content/attrs>. These are validated in exactly
911 the same way as the graph parameters in the calls to
912 default_graph(%hash), new(graph => {}) and push_subgraph(graph => {}).
913 node => {...} is any node attributes accepted as Graphviz attributes
915 <http://www.graphviz.org/content/attrs>. These are validated in exactly
916 the same way as the node parameters in the calls to
917 default_node(%hash), new(node => {}) and push_subgraph(node => {}).
918 subgraph => {..} is for setting attributes applicable to clusters and
920 subgraphs.
921 Currently the only subgraph attribute is "rank", but clusters have many
923 attributes available.
924 See the second column of the Graphviz attribute docs
926 <http://www.graphviz.org/content/attrs> for details.
927 A typical usage would be push_subgraph(subgraph => {rank => 'same'}) so
929 that all nodes mentioned within the subgraph are constrained to be
930 horizontally aligned.
931 See scripts/rank.sub.graph.[12].pl and scripts/sub.graph.frames.pl for
933 sample code.
934 report_valid_attributes()
936 Prints all attributes known to this module.
937 Returns nothing.
939 You wouldn't normally need to use this method.
941 See scripts/report.valid.attributes.pl. See "Scripts Shipped with this
943 Module" in GraphViz2.
944 run([driver => $exe, format => $string, timeout => $integer, output_file =>
946 $output_file])
947 Runs the given program to process the output stream.
948 Returns $self to allow method chaining.
950 Here, [] indicate optional parameters.
952 $driver is the name of the external program to run.
954 It defaults to the value supplied in the call to new(global => {driver
956 => '...'}), which in turn defaults to File::Which's which('dot') return
957 value.
958 $format is the type of output file to write.
960 It defaults to the value supplied in the call to new(global => {format
962 => '...'}), which in turn defaults to 'svg'.
963 $timeout is the time in seconds to wait while the external program
965 runs, before dieing with an error.
966 It defaults to the value supplied in the call to new(global => {timeout
968 => '...'}), which in turn defaults to 10.
969 $output_file is the name of the file into which the output from the
971 external program is written.
972 There is no default value for $output_file. If a value is not supplied
974 for $output_file, the only way to recover the output of the external
975 program is to call dot_output().
976 This method performs a series of tasks:
978 o Formats the output stream
980 o Stores the formatted output in a buffer controlled by the dot_input()
981 method
982 o Output the output stream to a file
983 o Run the chosen external program on that file
984 o Capture STDOUT and STDERR from that program
985 o Die if STDERR contains anything
986 o Copies STDOUT to the buffer controlled by the dot_output() method
987 o Write the captured contents of STDOUT to $output_file, if
988 $output_file has a value
989 stringify_attributes($context, $option)
991 Returns a string suitable to writing to the output stream.
992 $context is one of 'edge', 'graph', 'node', or a special string. See
994 the code for details.
995 You wouldn't normally need to use this method.
997 validate_params($context, %attributes)
999 Validate the given attributes within the given context.
1000 Also, if $context is 'subgraph', attributes are allowed to be in the
1002 'cluster' context.
1003 Returns $self to allow method chaining.
1005 $context is one of 'edge', 'global', 'graph', 'node' or
1007 'output_format'.
1008 You wouldn't normally need to use this method.
1010 verbose([$integer])
1012 Gets or sets the verbosity level, for when a logging object is not
1013 used.
1014 Here, [] indicates an optional parameter.
1016
1018 Which version of Graphviz do you use?
1019 GraphViz2 targets V 2.34.0 of Graphviz <http://www.graphviz.org/>.
1020 This affects the list of available attributes per graph item (node,
1022 edge, cluster, etc) available.
1023 See the second column of the Graphviz attribute docs
1025 <http://www.graphviz.org/content/attrs> for details.
1026 See the next item for a discussion of the list of output formats.
1028 Where does the list of valid output formats come from?
1030 Up to V 2.23, it came from downloading and parsing
1031 http://www.graphviz.org/content/output-formats. This was done by
1032 scripts/extract.output.formats.pl.
1033 Starting with V 2.24 it comes from parsing the output of 'dot -T?'. The
1035 problems avoided, and advantages, of this are:
1036 o I might forget to run the script after Graphviz is updated
1038 o The on-line docs might be out-of-date
1039 o dot output includes the formats supported by locally-installed
1040 plugins
1041 Why do I get error messages like the following?
1043 Error: <stdin>:1: syntax error near line 1
1044 context: digraph >>> Graph <<< {
1045 Graphviz reserves some words as keywords, meaning they can't be used as
1047 an ID, e.g. for the name of the graph. So, don't do this:
1048 strict graph graph{...}
1050 strict graph Graph{...}
1051 strict graph strict{...}
1052 etc...
1053 Likewise for non-strict graphs, and digraphs. You can however add
1055 double-quotes around such reserved words:
1056 strict graph "graph"{...}
1058 Even better, use a more meaningful name for your graph...
1060 The keywords are: node, edge, graph, digraph, subgraph and strict.
1062 Compass points are not keywords.
1063 See keywords <http://www.graphviz.org/content/dot-language> in the
1065 discussion of the syntax of DOT for details.
1066 How do I include utf8 characters in labels?
1068 Since V 2.00, GraphViz2 incorporates a sample which produce graphs such
1069 as this <http://savage.net.au/Perl-modules/html/graphviz2/utf8.1.svg>.
1070 scripts/utf8.1.pl contains 'use utf8;' because of the utf8 characters
1072 embedded in the source code. You will need to do this.
1073 Why did you remove 'use utf8' from this file (in V 2.26)?
1075 Because it is global, i.e. it applies to all code in your program, not
1076 just within this module. Some modules you are using may not expect
1077 that. If you need it, just use it in your *.pl script.
1078 Why do I get 'Wide character in print...' when outputting to PNG but not
1080 SVG?
1081 As of V 2.02, you should not get this from GraphViz2. So, I suggest you
1082 study your own code very, very carefully :-(.
1083 Examine the output from scripts/utf8.2.pl, i.e. html/utf8.2.svg and
1085 you'll see it's correct. Then run:
1086 perl scripts/utf8.2.pl png
1088 and examine html/utf8.2.png and you'll see it matches html/utf8.2.svg
1090 in showing 5 deltas. So, I think it's all working.
1091 How do I print output files?
1093 Under Unix, output as PDF, and then try: lp -o fitplot
1094 html/parse.stt.pdf (or whatever).
1095 Can I include spaces and newlines in HTML labels?
1097 Yes. The code removes leading and trailing whitespace on HTML labels
1098 before calling 'dot'.
1099 Also, the code, and 'dot', both accept newlines embedded within such
1101 labels.
1102 Together, these allow HTML labels to be formatted nicely in the calling
1104 code.
1105 See the Graphviz docs
1107 <https://graphviz.gitlab.io/_pages/doc/info/shapes.html#record> for
1108 their discussion on whitespace.
1109 I'm having trouble with special characters in node names and labels
1111 GraphViz2 escapes these 2 characters in those contexts: [].
1112 Escaping the 2 chars [] started with V 2.10. Previously, all of []{}
1114 were escaped, but {} are used in records to control the orientation of
1115 fields, so they should not have been escaped in the first place. See
1116 scripts/record.1.pl.
1117 Double-quotes are escaped when the label is not an HTML label. See
1119 scripts/html.labels.*.pl for sample code.
1120 It would be nice to also escape | and <, but these characters are used
1122 in specifying fields and ports in records.
1123 See the next couple of points for details.
1125 A warning about Graphviz <http://www.graphviz.org/> and ports
1127 Ports are what Graphviz <http://www.graphviz.org/> calls those places
1128 on the outline of a node where edges leave and terminate.
1129 The Graphviz <http://www.graphviz.org/> syntax for ports is a bit
1131 unusual:
1132 o This works: "node_name":port5
1134 o This doesn't: "node_name:port5"
1135 Let me repeat - that is Graphviz syntax, not GraphViz2 syntax. In Perl,
1137 you must do this:
1138 $graph -> add_edge(from => 'struct1:f1', to => 'struct2:f0', color => 'blue');
1140 You don't have to quote all node names in Graphviz
1142 <http://www.graphviz.org/>, but some, such as digits, must be quoted,
1143 so I've decided to quote them all.
1144 How labels interact with ports
1146 You can specify labels with ports in these ways:
1147 o As a string
1149 From scripts/record.1.pl:
1150 $graph -> add_node(name => 'struct3', label => "hello\nworld |{ b |{c|<here> d|e}| f}| g | h");
1152 Here, the string contains a port (<here>), field markers (|), and
1154 orientation markers ({}).
1155 Clearly, you must specify the field separator character '|'
1157 explicitly. In the next 2 cases, it is implicit.
1158 Then you use $graph -> add_edge(...) to refer to those ports, if
1160 desired. Again, from scripts/record.1.pl:
1161 $graph -> add_edge(from => 'struct1:f2', to => 'struct3:here',
1163 color => 'red');
1164 The same label is specified in the next case.
1166 o As an arrayref of hashrefs
1168 From scripts/record.2.pl:
1169 $graph -> add_node(name => 'struct3', label =>
1171 [
1172 {
1173 text => "hello\nworld",
1174 },
1175 {
1176 text => '{b',
1177 },
1178 {
1179 text => '{c',
1180 },
1181 {
1182 port => '<here>',
1183 text => 'd',
1184 },
1185 {
1186 text => 'e}',
1187 },
1188 {
1189 text => 'f}',
1190 },
1191 {
1192 text => 'g',
1193 },
1194 {
1195 text => 'h',
1196 },
1197 ]);
1198 Each hashref is a field, and hence you do not specify the field
1200 separator character '|'.
1201 Then you use $graph -> add_edge(...) to refer to those ports, if
1203 desired. Again, from scripts/record.2.pl:
1204 $graph -> add_edge(from => 'struct1:f2', to => 'struct3:here',
1206 color => 'red');
1207 The same label is specified in the previous case.
1209 o As an arrayref of strings
1211 From scripts/html.labels.1.pl:
1212 $graph -> add_node(name => 'Oakleigh', shape => 'record', color => 'blue',
1214 label => ['West Oakleigh', 'East Oakleigh']);
1215 Here, again, you do not specify the field separator character '|'.
1217 What happens is that each string is taken to be the label of a
1219 field, and each field is given an auto-generated port name of the
1220 form "<port$n>", where $n starts from 1.
1221 Here's how you refer to those ports, again from
1223 scripts/html.labels.1.pl:
1224 $graph -> add_edge(from => 'Murrumbeena', to => 'Oakleigh:port2',
1226 color => 'green', label => '<Drive<br/>Run<br/>Sprint>');
1227 See also the docs for the "add_node(name => $node_name, [%hash])"
1229 method.
1230 How do I specify attributes for clusters?
1232 Just use subgraph => {...}, because the code (as of V 2.22) accepts
1233 attributes belonging to either clusters or subgraphs.
1234 An example attribute is "pencolor", which is used for clusters but not
1236 for subgraphs:
1237 $graph -> push_subgraph
1239 (
1240 graph => {label => 'Child the Second'},
1241 name => 'cluster Second subgraph',
1242 node => {color => 'magenta', shape => 'diamond'},
1243 subgraph => {pencolor => 'white'}, # White hides the cluster's frame.
1244 );
1245 See scripts/sub.graph.frames.pl.
1247 Why does GraphViz plot top-to-bottom but GraphViz2::Parse::ISA plot bottom-
1249 to-top?
1250 Because the latter knows the data is a class structure. The former
1251 makes no assumptions about the nature of the data.
1252 What happened to GraphViz::No?
1254 The default_node(%hash) method in GraphViz2 allows you to make nodes
1255 vanish.
1256 Try: $graph -> default_node(label => '', height => 0, width => 0, style
1258 => 'invis');
1259 Because that line is so simple, I feel it's unnecessary to make a
1261 subclass of GraphViz2.
1262 What happened to GraphViz::Regex?
1264 See GraphViz2::Parse::Regexp.
1265 What happened to GraphViz::Small?
1267 The default_node(%hash) method in GraphViz2 allows you to make nodes
1268 which are small.
1269 Try: $graph -> default_node(label => '', height => 0.2, width => 0.2,
1271 style => 'filled');
1272 Because that line is so simple, I feel it's unnecessary to make a
1274 subclass of GraphViz2.
1275 What happened to GraphViz::XML?
1277 Use GraphViz2::Parse::XML instead, which uses the pure-Perl XML::Tiny.
1278 Alternately, see "Scripts Shipped with this Module" in GraphViz2 for
1280 how to use XML::Bare, GraphViz2 and GraphViz2::Data::Grapher instead.
1281 See "scripts/parse.xml.pp.pl" or "scripts/parse.xml.bare.pl" below.
1283 GraphViz returned a node name from add_node() when given an anonymous node.
1285 What does GraphViz2 do?
1286 You can give the node a name, and an empty string for a label, to
1287 suppress plotting the name.
1288 See "scripts/anonymous.pl" for demo code.
1290 If there is some specific requirement which this does not cater for,
1292 let me know and I can change the code.
1293 How do I use image maps?
1295 See "Image Maps" above.
1296 I'm trying to use image maps but the non-image map code runs instead!
1298 The default value of "im_output_file" is '', so if you do not set it to
1299 anything, the new image maps code is ignored.
1300 Why such a different approach to logging?
1302 As you can see from scripts/*.pl, I always use Log::Handler.
1303 By default (i.e. without a logger object), GraphViz2 prints warning and
1305 debug messages to STDOUT, and dies upon errors.
1306 However, by supplying a log object, you can capture these events.
1308 Not only that, you can change the behaviour of your log object at any
1310 time, by calling "logger($logger_object)".
1311 A Note about XML Containers
1313 The 2 demo programs "scripts/parse.html.pl" and
1314 "scripts/parse.xml.bare.pl", which both use XML::Bare, assume your XML
1315 has a single parent container for all other containers. The programs
1316 use this container to provide a name for the root node of the graph.
1317 Why did you choose Moo over Moose?
1319 Moo is light-weight.
1320
1322 See the demo page <http://savage.net.au/Perl-
1323 modules/html/graphviz2/index.html>, which displays the output of each
1324 program listed below.
1325 scripts/anonymous.pl
1327 Demonstrates empty strings for node names and labels.
1328 Outputs to ./html/anonymous.svg by default.
1330 scripts/cluster.pl
1332 Demonstrates building a cluster as a subgraph.
1333 Outputs to ./html/cluster.svg by default.
1335 See also scripts/macro.*.pl below.
1337 copy.config.pl
1339 End users have no need to run this script.
1340 scripts/dbi.schema.pl
1342 If the environment vaiables DBI_DSN, DBI_USER and DBI_PASS are set (the
1343 latter 2 are optional [e.g. for SQLite]), then this demonstrates
1344 building a graph from a database schema.
1345 Also, for Postgres, you can set $ENV{DBI_SCHEMA} to a comma-separated
1347 list of schemas, e.g. when processing the MusicBrainz database. See
1348 scripts/dbi.schema.pl.
1349 For details, see
1351 <http://blogs.perl.org/users/ron_savage/2013/03/graphviz2-and-the-dread-musicbrainz-db.html>.
1352 Outputs to ./html/dbi.schema.svg by default.
1354 scripts/dependency.pl
1356 Demonstrates graphing an Algorithm::Dependency source.
1357 Outputs to ./html/dependency.svg by default.
1359 The default for GraphViz2 is to plot from the top to the bottom. This
1361 is the opposite of GraphViz2::Parse::ISA.
1362 See also parse.isa.pl below.
1364 scripts/extract.arrow.shapes.pl
1366 Downloads the arrow shapes from Graphviz's Arrow Shapes
1367 <http://www.graphviz.org/content/arrow-shapes> and outputs them to
1368 ./data/arrow.shapes.html. Then it extracts the reserved words into
1369 ./data/arrow.shapes.dat.
1370 scripts/extract.attributes.pl
1372 Downloads the attributes from Graphviz's Attributes
1373 <http://www.graphviz.org/content/attrs> and outputs them to
1374 ./data/attributes.html. Then it extracts the reserved words into
1375 ./data/attributes.dat.
1376 scripts/extract.node.shapes.pl
1378 Downloads the node shapes from Graphviz's Node Shapes
1379 <http://www.graphviz.org/content/node-shapes> and outputs them to
1380 ./data/node.shapes.html. Then it extracts the reserved words into
1381 ./data/node.shapes.dat.
1382 scripts/extract.output.formats.pl
1384 Downloads the output formats from Graphviz's Output Formats
1385 <http://www.graphviz.org/content/output-formats> and outputs them to
1386 ./data/output.formats.html. Then it extracts the reserved words into
1387 ./data/output.formats.dat.
1388 find.config.pl
1390 End users have no need to run this script.
1391 scripts/generate.demo.pl
1393 Run by scripts/generate.svg.sh. See next point.
1394 scripts/generate.png.sh
1396 See scripts/generate.svg.sh for details.
1397 Outputs to /tmp by default.
1399 This script is generated by generate.sh.pl.
1401 generate.sh.pl
1403 Generates scripts/generate.png.sh and scripts/generate.svg.sh.
1404 scripts/generate.svg.sh
1406 A bash script to run all the scripts and generate the *.svg and *.log
1407 files, in ./html.
1408 You can them copy html/*.html and html/*.svg to your web server's doc
1410 root, for viewing.
1411 Outputs to /tmp by default.
1413 This script is generated by generate.sh.pl.
1415 scripts/Heawood.pl
1417 Demonstrates the transitive 6-net, also known as Heawood's graph.
1418 Outputs to ./html/Heawood.svg by default.
1420 This program was reverse-engineered from graphs/undirected/Heawood.gv
1422 in the distro for Graphviz <http://www.graphviz.org/> V 2.26.3.
1423 scripts/html.labels.1.pl
1425 Demonstrates a HTML label without a table.
1426 Also demonstrates an arrayref of strings as a label.
1428 See also scripts/record.*.pl for other label techniques.
1430 Outputs to ./html/html.labels.1.svg by default.
1432 scripts/html.labels.2.pl
1434 Demonstrates a HTML label with a table.
1435 Outputs to ./html/html.labels.2.svg by default.
1437 scripts/macro.1.pl
1439 Demonstrates non-cluster subgraphs via a macro.
1440 Outputs to ./html/macro.1.svg by default.
1442 scripts/macro.2.pl
1444 Demonstrates linked non-cluster subgraphs via a macro.
1445 Outputs to ./html/macro.2.svg by default.
1447 scripts/macro.3.pl
1449 Demonstrates cluster subgraphs via a macro.
1450 Outputs to ./html/macro.3.svg by default.
1452 scripts/macro.4.pl
1454 Demonstrates linked cluster subgraphs via a macro.
1455 Outputs to ./html/macro.4.svg by default.
1457 scripts/macro.5.pl
1459 Demonstrates compound cluster subgraphs via a macro.
1460 Outputs to ./html/macro.5.svg by default.
1462 scripts/parse.data.pl
1464 Demonstrates graphing a Perl data structure.
1465 Outputs to ./html/parse.data.svg by default.
1467 scripts/parse.html.pl
1469 Demonstrates using XML::Bare to parse HTML.
1470 Inputs from ./t/sample.html, and outputs to ./html/parse.html.svg by
1472 default.
1473 scripts/parse.isa.pl
1475 Demonstrates combining 2 Perl class hierarchies on the same graph.
1476 Outputs to ./html/parse.isa.svg by default.
1478 The default for GraphViz2::Parse::ISA is to plot from the bottom to the
1480 top (Grandchild to Parent). This is the opposite of GraphViz2.
1481 See also dependency.pl, above.
1483 scripts/parse.recdescent.pl
1485 Demonstrates graphing a Parse::RecDescent-style grammar.
1486 Inputs from t/sample.recdescent.1.dat and outputs to
1488 ./html/parse.recdescent.svg by default.
1489 The input grammar was extracted from t/basics.t in Parse::RecDescent V
1491 1.965001.
1492 You can patch the *.pl to read from t/sample.recdescent.2.dat, which
1494 was copied from a V 2 bug report
1495 <https://rt.cpan.org/Ticket/Display.html?id=36057>.
1496 scripts/parse.regexp.pl
1498 Demonstrates graphing a Perl regular expression.
1499 Outputs to ./html/parse.regexp.svg by default.
1501 scripts/parse.stt.pl
1503 Demonstrates graphing a Set::FA::Element-style state transition table.
1504 Inputs from t/sample.stt.1.dat and outputs to ./html/parse.stt.svg by
1506 default.
1507 The input grammar was extracted from Set::FA::Element.
1509 You can patch the scripts/parse.stt.pl to read from t/sample.stt.2.dat
1511 instead of t/sample.stt.1.dat. t/sample.stt.2.dat was extracted from a
1512 obsolete version of Graph::Easy::Marpa, i.e. V 1.*. The Marpa-based
1513 parts of the latter module were completely rewritten for V 2.*.
1514 scripts/parse.yacc.pl
1516 Demonstrates graphing a byacc <http://invisible-
1517 island.net/byacc/byacc.html>-style grammar.
1518 Inputs from t/calc3.output, and outputs to ./html/parse.yacc.svg by
1520 default.
1521 The input was copied from test/calc3.y in byacc V 20101229 and process
1523 as below.
1524 Note: The version downloadable via HTTP is 20101127.
1526 I installed byacc like this:
1528 sudo apt-get byacc
1530 Now get a sample file to work with:
1532 cd ~/Downloads
1534 curl ftp://invisible-island.net/byacc/byacc.tar.gz > byacc.tar.gz
1535 tar xvzf byacc.tar.gz
1536 cd ~/perl.modules/GraphViz2
1537 cp ~/Downloads/byacc-20101229/test/calc3.y t
1538 byacc -v t/calc3.y
1539 mv y.output t/calc3.output
1540 diff ~/Downloads/byacc-20101229/test/calc3.output t/calc3.output
1541 rm y.tab.c
1542 It's the file calc3.output which ships in the t/ directory.
1544 scripts/parse.yapp.pl
1546 Demonstrates graphing a Parse::Yapp-style grammar.
1547 Inputs from t/calc.output, and outputs to ./html/parse.yapp.svg by
1549 default.
1550 The input was copied from t/calc.t in Parse::Yapp's and processed as
1552 below.
1553 I installed Parse::Yapp (and yapp) like this:
1555 cpanm Parse::Yapp
1557 Now get a sample file to work with:
1559 cd ~/perl.modules/GraphViz2
1561 cp ~/.cpanm/latest-build/Parse-Yapp-1.05/t/calc.t t/calc.input
1562 Edit t/calc.input to delete the code, leaving the grammar after the
1564 __DATA__token.
1565 yapp -v t/calc.input > t/calc.output
1567 rm t/calc.pm
1568 It's the file calc.output which ships in the t/ directory.
1570 scripts/parse.xml.bare.pl
1572 Demonstrates using XML::Bare to parse XML.
1573 Inputs from ./t/sample.xml, and outputs to ./html/parse.xml.bare.svg by
1575 default.
1576 scripts/parse.xml.pp.pl
1578 Demonstrates using XML::Tiny to parse XML.
1579 Inputs from ./t/sample.xml, and outputs to ./html/parse.xml.pp.svg by
1581 default.
1582 scripts/quote.pl
1584 Demonstrates embedded newlines and double-quotes in node names and
1585 labels.
1586 It also demonstrates that the justification escapes, \l and \r, work
1588 too, sometimes.
1589 Outputs to ./html/quote.svg by default.
1591 Tests which run dot directly show this is a bug in Graphviz
1593 <http://www.graphviz.org/> itself.
1594 For example, in this graph, it looks like \r only works after \l (node
1596 d), but not always (nodes b, c).
1597 Call this x.gv:
1599 digraph G {
1601 rankdir=LR;
1602 node [shape=oval];
1603 a [ label ="a: Far, far, Left\rRight"];
1604 b [ label ="\lb: Far, far, Left\rRight"];
1605 c [ label ="XXX\lc: Far, far, Left\rRight"];
1606 d [ label ="d: Far, far, Left\lRight\rRight"];
1607 }
1608 and use the command:
1610 dot -Tsvg x.gv > x.svg
1612 See the Graphviz docs
1614 <http://www.graphviz.org/content/attrs#kescString> for escString, where
1615 they write 'l to mean \l, for some reason.
1616 scripts/rank.sub.graph.1.pl
1618 Demonstrates a very neat way of controlling the rank attribute of nodes
1619 within subgraphs.
1620 Outputs to ./html/rank.sub.graph.1.svg by default.
1622 scripts/rank.sub.graph.2.pl
1624 Demonstrates a long-winded way of controlling the rank attribute of
1625 nodes within subgraphs.
1626 Outputs to ./html/rank.sub.graph.2.svg by default.
1628 scripts/rank.sub.graph.3.pl
1630 Demonstrates the effect of the name of a subgraph, when that name does
1631 not start with 'cluster'.
1632 Outputs to ./html/rank.sub.graph.3.svg by default.
1634 scripts/record.1.pl
1636 Demonstrates a string as a label, containing both ports and orientation
1637 markers ({}).
1638 Outputs to ./html/record.1.svg by default.
1640 See also scripts/html.labels.2.pl and scripts/record.*.pl for other
1642 label techniques.
1643 scripts/record.2.pl
1645 Demonstrates an arrayref of hashrefs as a label, containing both ports
1646 and orientation markers ({}).
1647 Outputs to ./html/record.2.svg by default.
1649 See also scripts/html.labels.1.pl the other type of HTML labels.
1651 scripts/record.3.pl
1653 Demonstrates a string as a label, containing ports and deeply nested
1654 orientation markers ({}).
1655 Outputs to ./html/record.3.svg by default.
1657 See also scripts/html.labels.*.pl and scripts/record.*.pl for other
1659 label techniques.
1660 scripts/record.4.pl
1662 Demonstrates setting node shapes by default and explicitly.
1663 Outputs to ./html/record.4.svg by default.
1665 scripts/rank.sub.graph.4.pl
1667 Demonstrates the effect of the name of a subgraph, when that name
1668 starts with 'cluster'.
1669 Outputs to ./html/rank.sub.graph.4.svg by default.
1671 scripts/report.nodes.and.edges.pl
1673 Demonstates how to access the data returned by "edge_hash()" and
1674 "node_hash()".
1675 Prints node and edge attributes.
1677 Outputs to STDOUT.
1679 scripts/report.valid.attributes.pl
1681 Prints all current Graphviz <http://www.graphviz.org/> attributes,
1682 along with a few global ones I've invented for the purpose of writing
1683 this module.
1684 Outputs to STDOUT.
1686 scripts/sqlite.foreign.keys.pl
1688 Demonstrates how to find foreign key info by calling SQLite's pragma
1689 foreign_key_list.
1690 Outputs to STDOUT.
1692 scripts/sub.graph.frames.pl
1694 Demonstrates clusters with and without frames.
1695 Outputs to ./html/sub.graph.frames.svg by default.
1697 scripts/sub.graph.pl
1699 Demonstrates a graph combined with a subgraph.
1700 Outputs to ./html/sub.graph.svg by default.
1702 scripts/sub.sub.graph.pl
1704 Demonstrates a graph combined with a subgraph combined with a
1705 subsubgraph.
1706 Outputs to ./html/sub.sub.graph.svg by default.
1708 scripts/trivial.pl
1710 Demonstrates a trivial 3-node graph, with colors, just to get you
1711 started.
1712 Outputs to ./html/trivial.svg by default.
1714 scripts/utf8.1.pl
1716 Demonstrates using utf8 characters in labels.
1717 Outputs to ./html/utf8.1.svg by default.
1719 scripts/utf8.2.pl
1721 Demonstrates using utf8 characters in labels.
1722 Outputs to ./html/utf8.2.svg by default.
1724
1726 o Does GraphViz2 need to emulate the sort option in GraphViz?
1727 That depends on what that option really does.
1728 o Handle edges such as 1 -> 2 -> {A B}, as seen in Graphviz
1730 <http://www.graphviz.org/>'s graphs/directed/switch.gv
1731 But how?
1732 o Validate parameters more carefully, e.g. to reject non-hashref
1734 arguments where appropriate
1735 Some method parameter lists take keys whose value must be a
1736 hashref.
1737
1739 Axis Maps <http://www.axismaps.com/>.
1740 Polygon Map Generation <http://www-cs-
1742 students.stanford.edu/~amitp/game-programming/polygon-map-generation/>.
1743 Read more on that here
1744 <http://blogs.perl.org/users/max_maischein/2011/06/display-your-
1745 data---randompoissondisc.html>.
1746 Voronoi Applications
1748 <http://www.voronoi.com/wiki/index.php?title=Voronoi_Applications>.
1749
1751 Many thanks are due to the people who chose to make Graphviz
1752 <http://www.graphviz.org/> Open Source.
1753 And thanks to Leon Brocard <http://search.cpan.org/~lbrocard/>, who
1755 wrote GraphViz, and kindly gave me co-maint of the module.
1756
1758 Version numbers < 1.00 represent development versions. From 1.00 up,
1759 they are production versions.
1760
1762 The file Changes was converted into Changelog.ini by
1763 Module::Metadata::Changes.
1764
1766 <https://github.com/ronsavage/GraphViz2.git>
1767
1769 Email the author, or log a bug on RT:
1770 <https://rt.cpan.org/Public/Dist/Display.html?Name=GraphViz2>.
1772
1774 GraphViz2 was written by Ron Savage <ron@savage.net.au> in 2011.
1775 Home page: <http://savage.net.au/index.html>.
1777
1779 Australian copyright (c) 2011, Ron Savage.
1780 All Programs of mine are 'OSI Certified Open Source Software';
1782 you can redistribute them and/or modify them under the terms of
1783 The Perl License, a copy of which is available at:
1784 http://dev.perl.org/licenses/
1785perl v5.28.0 2018-02-23 GraphViz2(3)
