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

NAME

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

Synopsis

9   Sample output
10       Unpack the distro and copy html/*.html and html/*.svg to your web
11       server's doc root directory.
12
13       Then, point your browser at 127.0.0.1/index.html.
14
15       Or, hit the demo page <http://savage.net.au/Perl-
16       modules/html/graphviz2/index.html>.
17
18   Perl code
19       Typical Usage
20
21               #!/usr/bin/env perl
22
23               use strict;
24               use warnings;
25
26               use File::Spec;
27
28               use GraphViz2;
29
30               use Log::Handler;
31
32               # ---------------
33
34               my($logger) = Log::Handler -> new;
35
36               $logger -> add
37                       (
38                        screen =>
39                        {
40                                maxlevel       => 'debug',
41                                message_layout => '%m',
42                                minlevel       => 'error',
43                        }
44                       );
45
46               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
55               $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
59               $graph -> add_edge(from => 'Murrumbeena', to    => 'Carnegie', arrowsize => 2);
60               $graph -> add_edge(from => 'Murrumbeena', to    => 'Oakleigh', color => 'brown');
61
62               $graph -> push_subgraph
63               (
64                name  => 'cluster_1',
65                graph => {label => 'Child'},
66                node  => {color => 'magenta', shape => 'diamond'},
67               );
68
69               $graph -> add_node(name => 'Chadstone', shape => 'hexagon');
70               $graph -> add_node(name => 'Waverley', color => 'orange');
71
72               $graph -> add_edge(from => 'Chadstone', to => 'Waverley');
73
74               $graph -> pop_subgraph;
75
76               $graph -> default_node(color => 'cyan');
77
78               $graph -> add_node(name => 'Malvern');
79               $graph -> add_node(name => 'Prahran', shape => 'trapezium');
80
81               $graph -> add_edge(from => 'Malvern', to => 'Prahran');
82               $graph -> add_edge(from => 'Malvern', to => 'Murrumbeena');
83
84               my($format)      = shift || 'svg';
85               my($output_file) = shift || File::Spec -> catfile('html', "sub.graph.$format");
86
87               $graph -> run(format => $format, output_file => $output_file);
88
89       This program ships as scripts/sub.graph.pl. See "Scripts Shipped with
90       this Module".
91
92       Image Maps Usage
93
94       As of V 2.43, "GraphViz2" supports image maps, both client and server
95       side.
96
97       See "Image Maps" below.
98

Description

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
105       It is called GraphViz2 so that pre-existing code using (the Perl
106       module) GraphViz continues to work.
107
108       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
113       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
118       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
123       To ensure GraphViz2 is a light-weight module, Moo has been used to
124       provide getters and setters, rather than Moose.
125
126       As of V 2.43, "GraphViz2" supports image maps, both client and server
127       side.
128
129       See "Image Maps" below.
130
131   What is a Graph?
132       An undirected graph is a collection of nodes optionally linked together
133       with edges.
134
135       A directed graph is the same, except that the edges have a direction,
136       normally indicated by an arrow head.
137
138       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

Distributions

144       This module is available as a Unix-style distro (*.tgz).
145
146       See <http://savage.net.au/Perl-modules/html/installing-a-module.html>
147       for help on unpacking and installing distros.
148

Installation

150       Of course you need to install AT&T's Graphviz before using this module.
151       See <http://www.graphviz.org/Download.php>.
152
153       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
157       Install GraphViz2 as you would for any "Perl" module:
158
159       Run:
160
161               cpanm GraphViz2
162
163               Note: cpanm ships in App::cpanminus. See also App::perlbrew.
164
165       or run:
166
167               sudo cpan GraphViz2
168
169       or unpack the distro, and then either:
170
171               perl Build.PL
172               ./Build
173               ./Build test
174               sudo ./Build install
175
176       or:
177
178               perl Makefile.PL
179               make (or dmake or nmake)
180               make test
181               make install
182

Constructor and Initialization

184   Calling new()
185       "new()" is called as "my($obj) = GraphViz2 -> new(k1 => v1, k2 => v2,
186       ...)".
187
188       It returns a new object of type "GraphViz2".
189
190       Key-value pairs accepted in the parameter list:
191
192       o edge => $hashref
193           The edge key points to a hashref which is used to set default
194           attributes for edges.
195
196           Hence, allowable keys and values within that hashref are anything
197           supported by Graphviz <http://www.graphviz.org/>.
198
199           The default is {}.
200
201           This key is optional.
202
203       o global => $hashref
204           The global key points to a hashref which is used to set attributes
205           for the output stream.
206
207           Valid keys within this hashref are:
208
209           o directed => $Boolean
210               This option affects the content of the output stream.
211
212               directed => 1 outputs 'digraph name {...}', while directed => 0
213               outputs 'graph name {...}'.
214
215               At the Perl level, directed graphs have edges with arrow heads,
216               such as '->', while undirected graphs have unadorned edges,
217               such as '--'.
218
219               The default is 0.
220
221               This key is optional.
222
223           o driver => $program_name
224               This option specifies which external program to run to process
225               the output stream.
226
227               The default is to use File::Which's which() method to find the
228               'dot' program.
229
230               This key is optional.
231
232           o format => $string
233               This option specifies what type of output file to create.
234
235               The default is 'svg'.
236
237               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
241               This key is optional.
242
243           o label => $string
244               This option specifies what an edge looks like: '->' for
245               directed graphs and '--' for undirected graphs.
246
247               You wouldn't normally need to use this option.
248
249               The default is '->' if directed is 1, and '--' if directed is
250               0.
251
252               This key is optional.
253
254           o name => $string
255               This option affects the content of the output stream.
256
257               name => 'G666' outputs 'digraph G666 {...}'.
258
259               The default is 'Perl' :-).
260
261               This key is optional.
262
263           o record_shape => /^(?:M?record)$/
264               This option affects the shape of records. The value must be
265               'Mrecord' or 'record'.
266
267               Mrecords have nice, rounded corners, whereas plain old records
268               have square corners.
269
270               The default is 'Mrecord'.
271
272               See Record shapes <http://www.graphviz.org/content/node-
273               shapes#record> for details.
274
275           o strict => $Boolean
276               This option affects the content of the output stream.
277
278               strict => 1 outputs 'strict digraph name {...}', while strict
279               => 0 outputs 'digraph name {...}'.
280
281               The default is 0.
282
283               This key is optional.
284
285           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
291               Valid keys within this hashref are:
292
293               o rank => $string
294                   This option affects the content of all subgraphs, unless
295                   overridden later.
296
297                   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
301                   See scripts/rank.sub.graph.[12].pl for sample code.
302
303                   Possible values for $string are: max, min, same, sink and
304                   source.
305
306                   See the Graphviz 'rank' docs
307                   <http://www.graphviz.org/content/attrs#drank> for details.
308
309               The default is {}.
310
311               This key is optional.
312
313           o timeout => $integer
314               This option specifies how long to wait for the external program
315               before exiting with an error.
316
317               The default is 10 (seconds).
318
319               This key is optional.
320
321           This key (global) is optional.
322
323       o graph => $hashref
324           The graph key points to a hashref which is used to set default
325           attributes for graphs.
326
327           Hence, allowable keys and values within that hashref are anything
328           supported by Graphviz <http://www.graphviz.org/>.
329
330           The default is {}.
331
332           This key is optional.
333
334       o logger => $logger_object
335           Provides a logger object so $logger_object -> $level($message) can
336           be called at certain times.
337
338           See "Why such a different approach to logging?" in the </FAQ> for
339           details.
340
341           Retrieve and update the value with the logger() method.
342
343           The default is ''.
344
345           See also the verbose option, which can interact with the logger
346           option.
347
348           This key is optional.
349
350       o node => $hashref
351           The node key points to a hashref which is used to set default
352           attributes for nodes.
353
354           Hence, allowable keys and values within that hashref are anything
355           supported by Graphviz <http://www.graphviz.org/>.
356
357           The default is {}.
358
359           This key is optional.
360
361       o verbose => $Boolean
362           Provides a way to control the amount of output when a logger is not
363           specified.
364
365           Setting verbose to 0 means print nothing.
366
367           Setting verbose to 1 means print the log level and the message to
368           STDOUT, when a logger is not specified.
369
370           Retrieve and update the value with the verbose() method.
371
372           The default is 0.
373
374           See also the logger option, which can interact with the verbose
375           option.
376
377           This key is optional.
378
379   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
385       This mechanism has the effect of hard-coding Graphviz
386       <http://www.graphviz.org/> options in the source code of GraphViz2.
387
388       Nevertheless, the implementation of these lists is handled differently
389       from the way it was done in V 2.
390
391       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
395       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
400       See "Scripts Shipped with this Module" in GraphViz2.
401

Attribute Scope

403   Graph Scope
404       The graphical elements graph, node and edge, have attributes.
405       Attributes can be set when calling new().
406
407       Within new(), the defaults are graph => {}, node => {}, and edge => {}.
408
409       You override these with code such as new(edge => {color => 'red'}).
410
411       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
415       You change the 'current' attributes by calling any of the methods
416       default_edge(%hash), default_graph(%hash) and default_node(%hash).
417
418       See scripts/trivial.pl ("Scripts Shipped with this Module" in
419       GraphViz2) for an example.
420
421   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
426       This module, as with Graphviz <http://www.graphviz.org/>, defaults to
427       using inheritance of attributes.
428
429       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
433       After a single call to push_subgraph(%hash), these 'current' attributes
434       will live a level 1 in the scope stack.
435
436       See scripts/sub.graph.pl ("Scripts Shipped with this Module" in
437       GraphViz2) for an example.
438
439       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
443       Both GraphViz2 and Graphviz <http://www.graphviz.org/> handle this
444       situation properly.
445
446       See scripts/sub.sub.graph.pl ("Scripts Shipped with this Module" in
447       GraphViz2) for an example.
448
449       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
453       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
457       o Frame color
458           When you specify graph => {color => 'red'} at the parent level, the
459           subgraph has a red frame.
460
461           I think a subgraph should control its own frame.
462
463       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
467           This contradicts what happens at the global level, in that
468           specifying color there does not given the whole graph a frame.
469
470       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
475           For sample code, see scripts/sub.graph.frames.pl.
476
477       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
481       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

Image Maps

486       As of V 2.43, "GraphViz2" supports image maps, both client and server
487       side.
488
489   The Default URL
490       See the Graphviz docs for 'cmapx'
491       <http://www.graphviz.org/doc/info/output.html#d:cmapx>.
492
493       Their sample code has a dot file - x.gv - containing this line:
494
495               URL="http://www.research.att.com/base.html";
496
497       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
502       Thus you must do this to set a URL:
503
504               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
513       See maps/demo.3.pl and maps/demo.4.pl for sample code.
514
515   Typical Code
516       Normally you would call "run()" as:
517
518               $graph -> run
519               (
520                   format      => $format,
521                   output_file => $output_file
522               );
523
524       That line was copied from scripts/cluster.pl.
525
526       To trigger image map processing, you must include 2 new parameters:
527
528               $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
536       That line was copied from maps/demo.3.pl, and there is an identical
537       line in maps/demo.4.pl.
538
539   The New Parameters to run()
540       o im_format => $str
541           Expected values: 'imap' (server-side) and 'cmapx' (client-side).
542
543           Default value: 'cmapx'.
544
545       o im_output_file => $file_name
546           The name of the output map file.
547
548           Default: ''.
549
550   Sample Code
551       Various demos are shipped in the new maps/ directory:
552
553       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
558       o demo.1.*
559           This set demonstrates a server-side image map but does not use
560           "GraphViz2".
561
562           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
565           URL: your.domain.name/maps/demo.1.html.
566
567       o demo.2.*
568           This set demonstrates a client-side image map but does not use
569           "GraphViz2".
570
571           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
576           URL: your.domain.name/maps/demo.2.html.
577
578       o demo.3.*
579           This set demonstrates a server-side image map using "GraphViz2" via
580           demo.3.pl.
581
582           Note line 54 of demo.3.pl which sets the default "im_format" to
583           'imap'.
584
585           URL: your.domain.name/maps/demo.3.html.
586
587       o demo.4.*
588           This set demonstrates a client-side image map using "GraphViz2" via
589           demo.4.pl.
590
591           As with demo.2.* there is some manually editing to be done.
592
593           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
597           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
602           URL: your.domain.name/maps/demo.4.html.
603

Methods

605   add_edge(from => $from_node_name, to => $to_node_name, [label => $label,
606       %hash])
607       Adds an edge to the graph.
608
609       Returns $self to allow method chaining.
610
611       Here, [] indicate optional parameters.
612
613       Add a edge from 1 node to another.
614
615       $from_node_name and $to_node_name default to ''.
616
617       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
624       %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
629   add_node(name => $node_name, [%hash])
630       Adds a node to the graph.
631
632       Returns $self to allow method chaining.
633
634       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
638       If you want anonymous nodes, see scripts/anonymous.pl in "Scripts
639       Shipped with this Module" in GraphViz2.
640
641       Here, [] indicates an optional parameter.
642
643       %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
648       The attribute name 'label' may point to a string or an arrayref.
649
650       If it is a string...
651
652       The string is the label.
653
654       The string may contain ports and orientation markers ({}).
655
656       If it is an arrayref of strings...
657
658       o The node is forced to be a record
659           The actual shape, 'record' or 'Mrecord', is set globally, with:
660
661                   my($graph) = GraphViz2 -> new
662                   (
663                           global => {record_shape => 'record'}, # Override default 'Mrecord'.
664                           ...
665                   );
666
667           Or set locally with:
668
669                   $graph -> add_node(name => 'Three', label => ['Good', 'Bad'], shape => 'record');
670
671       o Each element in the array defines a field in the record
672           These fields are combined into a single node
673
674       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
680       If it is an arrayref of hashrefs...
681
682       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
686       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
690       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
694       o Judicious use of '{' and '}' in the label can make this record appear
695       horizontally or vertically, and even nested
696
697       See scripts/html.labels.*.pl and scripts/record.*.pl for sample code.
698
699       See also the FAQ topic "How labels interact with ports".
700
701       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
705   default_edge(%hash)
706       Sets defaults attributes for edges added subsequently.
707
708       Returns $self to allow method chaining.
709
710       %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
715   default_graph(%hash)
716       Sets defaults attributes for the graph.
717
718       Returns $self to allow method chaining.
719
720       %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
725   default_node(%hash)
726       Sets defaults attributes for nodes added subsequently.
727
728       Returns $self to allow method chaining.
729
730       %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
735   default_subgraph(%hash)
736       Sets defaults attributes for clusters and subgraphs.
737
738       Returns $self to allow method chaining.
739
740       %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
745   dot_input()
746       Returns the output stream, formatted nicely, which was passed to the
747       external program (e.g. dot).
748
749       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
753   dot_output()
754       Returns the output from calling the external program (e.g. dot).
755
756       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
760       This output is available even if run() does not write the output to a
761       file.
762
763   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
768       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
772               my($node_hash) = $graph -> node_hash;
773               my($edge_hash) = $graph -> edge_hash;
774
775               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
780                       print "Node: $from\n";
781                       print "\tAttributes: $s\n";
782
783                       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
790                                       print "\tEdge: $from$$edge{from_port} -> $to$$edge{to_port}\n";
791                                       print "\t\tAttributes: $s\n";
792                               }
793                       }
794               }
795
796       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
800       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
803               {
804                       attributes => {},
805                       from_port  => $from_port,
806                       to_port    => $to_port,
807               }
808
809       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
813       See scripts/report.nodes.and.edges.pl (a version of
814       scripts/html.labels.1.pl) for a complete example.
815
816   escape_some_chars($s)
817       Escapes various chars in various circumstances, because some chars are
818       treated specially by Graphviz.
819
820       See the "FAQ" for a discussion of this tricky topic.
821
822   load_valid_attributes()
823       Load various sets of valid attributes from within the source code of
824       this module, using Data::Section::Simple.
825
826       Returns $self to allow method chaining.
827
828       These attributes are used to validate attributes in many situations.
829
830       You wouldn't normally need to use this method.
831
832   log([$level, $message])
833       Logs the message at the given log level.
834
835       Returns $self to allow method chaining.
836
837       Here, [] indicate optional parameters.
838
839       $level defaults to 'debug', and $message defaults to ''.
840
841       If called with $level eq 'error', it dies with $message.
842
843   logger($logger_object)
844       Gets or sets the log object.
845
846       Here, [] indicates an optional parameter.
847
848   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
852               my($node_hash) = $graph -> node_hash;
853
854               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
859                       print "Node: $name\n";
860                       print "\tAttributes: $s\n";
861               }
862
863       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
867       A bit more formally then, $$node_hash{$node_name} is a hashref where
868       each element describes one node, and which defaults to:
869
870               {
871                       attributes => {},
872               }
873
874       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
878   pop_subgraph()
879       Pop off and discard the top element of the scope stack.
880
881       Returns $self to allow method chaining.
882
883   push_subgraph([name => $name, edge => {...}, graph => {...}, node => {...},
884       subgraph => {...}])
885       Sets up a new subgraph environment.
886
887       Returns $self to allow method chaining.
888
889       Here, [] indicate optional parameters.
890
891       name => $name is the name to assign to the subgraph. Name defaults to
892       ''.
893
894       So, without $name, 'subgraph {' is written to the output stream.
895
896       With $name, 'subgraph "$name" {' is written to the output stream.
897
898       Note that subgraph names beginning with 'cluster' are special to
899       Graphviz <http://www.graphviz.org/content/attrs#dclusterrank>.
900
901       See scripts/rank.sub.graph.[1234].pl for the effect of various values
902       for $name.
903
904       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
909       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
914       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
919       subgraph => {..} is for setting attributes applicable to clusters and
920       subgraphs.
921
922       Currently the only subgraph attribute is "rank", but clusters have many
923       attributes available.
924
925       See the second column of the Graphviz attribute docs
926       <http://www.graphviz.org/content/attrs> for details.
927
928       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
932       See scripts/rank.sub.graph.[12].pl and scripts/sub.graph.frames.pl for
933       sample code.
934
935   report_valid_attributes()
936       Prints all attributes known to this module.
937
938       Returns nothing.
939
940       You wouldn't normally need to use this method.
941
942       See scripts/report.valid.attributes.pl. See "Scripts Shipped with this
943       Module" in GraphViz2.
944
945   run([driver => $exe, format => $string, timeout => $integer, output_file =>
946       $output_file])
947       Runs the given program to process the output stream.
948
949       Returns $self to allow method chaining.
950
951       Here, [] indicate optional parameters.
952
953       $driver is the name of the external program to run.
954
955       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
959       $format is the type of output file to write.
960
961       It defaults to the value supplied in the call to new(global => {format
962       => '...'}), which in turn defaults to 'svg'.
963
964       $timeout is the time in seconds to wait while the external program
965       runs, before dieing with an error.
966
967       It defaults to the value supplied in the call to new(global => {timeout
968       => '...'}), which in turn defaults to 10.
969
970       $output_file is the name of the file into which the output from the
971       external program is written.
972
973       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
977       This method performs a series of tasks:
978
979       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
990   stringify_attributes($context, $option)
991       Returns a string suitable to writing to the output stream.
992
993       $context is one of 'edge', 'graph', 'node', or a special string. See
994       the code for details.
995
996       You wouldn't normally need to use this method.
997
998   validate_params($context, %attributes)
999       Validate the given attributes within the given context.
1000
1001       Also, if $context is 'subgraph', attributes are allowed to be in the
1002       'cluster' context.
1003
1004       Returns $self to allow method chaining.
1005
1006       $context is one of 'edge', 'global', 'graph', 'node' or
1007       'output_format'.
1008
1009       You wouldn't normally need to use this method.
1010
1011   verbose([$integer])
1012       Gets or sets the verbosity level, for when a logging object is not
1013       used.
1014
1015       Here, [] indicates an optional parameter.
1016

FAQ

1018   Which version of Graphviz do you use?
1019       GraphViz2 targets V 2.34.0 of Graphviz <http://www.graphviz.org/>.
1020
1021       This affects the list of available attributes per graph item (node,
1022       edge, cluster, etc) available.
1023
1024       See the second column of the Graphviz attribute docs
1025       <http://www.graphviz.org/content/attrs> for details.
1026
1027       See the next item for a discussion of the list of output formats.
1028
1029   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
1034       Starting with V 2.24 it comes from parsing the output of 'dot -T?'. The
1035       problems avoided, and advantages, of this are:
1036
1037       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
1042   Why do I get error messages like the following?
1043               Error: <stdin>:1: syntax error near line 1
1044               context: digraph >>>  Graph <<<  {
1045
1046       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
1049               strict graph graph{...}
1050               strict graph Graph{...}
1051               strict graph strict{...}
1052               etc...
1053
1054       Likewise for non-strict graphs, and digraphs. You can however add
1055       double-quotes around such reserved words:
1056
1057               strict graph "graph"{...}
1058
1059       Even better, use a more meaningful name for your graph...
1060
1061       The keywords are: node, edge, graph, digraph, subgraph and strict.
1062       Compass points are not keywords.
1063
1064       See keywords <http://www.graphviz.org/content/dot-language> in the
1065       discussion of the syntax of DOT for details.
1066
1067   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
1071       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
1074   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
1079   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
1084       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
1087               perl scripts/utf8.2.pl png
1088
1089       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
1092   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
1096   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
1100       Also, the code, and 'dot', both accept newlines embedded within such
1101       labels.
1102
1103       Together, these allow HTML labels to be formatted nicely in the calling
1104       code.
1105
1106       See the Graphviz docs
1107       <https://graphviz.gitlab.io/_pages/doc/info/shapes.html#record> for
1108       their discussion on whitespace.
1109
1110   I'm having trouble with special characters in node names and labels
1111       GraphViz2 escapes these 2 characters in those contexts: [].
1112
1113       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
1118       Double-quotes are escaped when the label is not an HTML label. See
1119       scripts/html.labels.*.pl for sample code.
1120
1121       It would be nice to also escape | and <, but these characters are used
1122       in specifying fields and ports in records.
1123
1124       See the next couple of points for details.
1125
1126   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
1130       The Graphviz <http://www.graphviz.org/> syntax for ports is a bit
1131       unusual:
1132
1133       o This works: "node_name":port5
1134       o This doesn't: "node_name:port5"
1135
1136       Let me repeat - that is Graphviz syntax, not GraphViz2 syntax. In Perl,
1137       you must do this:
1138
1139               $graph -> add_edge(from => 'struct1:f1', to => 'struct2:f0', color => 'blue');
1140
1141       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
1145   How labels interact with ports
1146       You can specify labels with ports in these ways:
1147
1148       o As a string
1149           From scripts/record.1.pl:
1150
1151                   $graph -> add_node(name => 'struct3', label => "hello\nworld |{ b |{c|<here> d|e}| f}| g | h");
1152
1153           Here, the string contains a port (<here>), field markers (|), and
1154           orientation markers ({}).
1155
1156           Clearly, you must specify the field separator character '|'
1157           explicitly. In the next 2 cases, it is implicit.
1158
1159           Then you use $graph -> add_edge(...) to refer to those ports, if
1160           desired. Again, from scripts/record.1.pl:
1161
1162           $graph -> add_edge(from => 'struct1:f2', to => 'struct3:here',
1163           color => 'red');
1164
1165           The same label is specified in the next case.
1166
1167       o As an arrayref of hashrefs
1168           From scripts/record.2.pl:
1169
1170                   $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
1199           Each hashref is a field, and hence you do not specify the field
1200           separator character '|'.
1201
1202           Then you use $graph -> add_edge(...) to refer to those ports, if
1203           desired. Again, from scripts/record.2.pl:
1204
1205           $graph -> add_edge(from => 'struct1:f2', to => 'struct3:here',
1206           color => 'red');
1207
1208           The same label is specified in the previous case.
1209
1210       o As an arrayref of strings
1211           From scripts/html.labels.1.pl:
1212
1213                   $graph -> add_node(name => 'Oakleigh', shape => 'record', color => 'blue',
1214                           label => ['West Oakleigh', 'East Oakleigh']);
1215
1216           Here, again, you do not specify the field separator character '|'.
1217
1218           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
1222           Here's how you refer to those ports, again from
1223           scripts/html.labels.1.pl:
1224
1225                   $graph -> add_edge(from => 'Murrumbeena', to => 'Oakleigh:port2',
1226                           color => 'green', label => '<Drive<br/>Run<br/>Sprint>');
1227
1228       See also the docs for the "add_node(name => $node_name, [%hash])"
1229       method.
1230
1231   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
1235       An example attribute is "pencolor", which is used for clusters but not
1236       for subgraphs:
1237
1238               $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
1246       See scripts/sub.graph.frames.pl.
1247
1248   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
1253   What happened to GraphViz::No?
1254       The default_node(%hash) method in GraphViz2 allows you to make nodes
1255       vanish.
1256
1257       Try: $graph -> default_node(label => '', height => 0, width => 0, style
1258       => 'invis');
1259
1260       Because that line is so simple, I feel it's unnecessary to make a
1261       subclass of GraphViz2.
1262
1263   What happened to GraphViz::Regex?
1264       See GraphViz2::Parse::Regexp.
1265
1266   What happened to GraphViz::Small?
1267       The default_node(%hash) method in GraphViz2 allows you to make nodes
1268       which are small.
1269
1270       Try: $graph -> default_node(label => '', height => 0.2, width => 0.2,
1271       style => 'filled');
1272
1273       Because that line is so simple, I feel it's unnecessary to make a
1274       subclass of GraphViz2.
1275
1276   What happened to GraphViz::XML?
1277       Use GraphViz2::Parse::XML instead, which uses the pure-Perl XML::Tiny.
1278
1279       Alternately, see "Scripts Shipped with this Module" in GraphViz2 for
1280       how to use XML::Bare, GraphViz2 and GraphViz2::Data::Grapher instead.
1281
1282       See "scripts/parse.xml.pp.pl" or "scripts/parse.xml.bare.pl" below.
1283
1284   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
1289       See "scripts/anonymous.pl" for demo code.
1290
1291       If there is some specific requirement which this does not cater for,
1292       let me know and I can change the code.
1293
1294   How do I use image maps?
1295       See "Image Maps" above.
1296
1297   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
1301   Why such a different approach to logging?
1302       As you can see from scripts/*.pl, I always use Log::Handler.
1303
1304       By default (i.e. without a logger object), GraphViz2 prints warning and
1305       debug messages to STDOUT, and dies upon errors.
1306
1307       However, by supplying a log object, you can capture these events.
1308
1309       Not only that, you can change the behaviour of your log object at any
1310       time, by calling "logger($logger_object)".
1311
1312   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
1318   Why did you choose Moo over Moose?
1319       Moo is light-weight.
1320

Scripts Shipped with this Module

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
1326   scripts/anonymous.pl
1327       Demonstrates empty strings for node names and labels.
1328
1329       Outputs to ./html/anonymous.svg by default.
1330
1331   scripts/cluster.pl
1332       Demonstrates building a cluster as a subgraph.
1333
1334       Outputs to ./html/cluster.svg by default.
1335
1336       See also scripts/macro.*.pl below.
1337
1338   copy.config.pl
1339       End users have no need to run this script.
1340
1341   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
1346       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
1350       For details, see
1351       <http://blogs.perl.org/users/ron_savage/2013/03/graphviz2-and-the-dread-musicbrainz-db.html>.
1352
1353       Outputs to ./html/dbi.schema.svg by default.
1354
1355   scripts/dependency.pl
1356       Demonstrates graphing an Algorithm::Dependency source.
1357
1358       Outputs to ./html/dependency.svg by default.
1359
1360       The default for GraphViz2 is to plot from the top to the bottom. This
1361       is the opposite of GraphViz2::Parse::ISA.
1362
1363       See also parse.isa.pl below.
1364
1365   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
1371   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
1377   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
1383   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
1389   find.config.pl
1390       End users have no need to run this script.
1391
1392   scripts/generate.demo.pl
1393       Run by scripts/generate.svg.sh. See next point.
1394
1395   scripts/generate.png.sh
1396       See scripts/generate.svg.sh for details.
1397
1398       Outputs to /tmp by default.
1399
1400       This script is generated by generate.sh.pl.
1401
1402   generate.sh.pl
1403       Generates scripts/generate.png.sh and scripts/generate.svg.sh.
1404
1405   scripts/generate.svg.sh
1406       A bash script to run all the scripts and generate the *.svg and *.log
1407       files, in ./html.
1408
1409       You can them copy html/*.html and html/*.svg to your web server's doc
1410       root, for viewing.
1411
1412       Outputs to /tmp by default.
1413
1414       This script is generated by generate.sh.pl.
1415
1416   scripts/Heawood.pl
1417       Demonstrates the transitive 6-net, also known as Heawood's graph.
1418
1419       Outputs to ./html/Heawood.svg by default.
1420
1421       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
1424   scripts/html.labels.1.pl
1425       Demonstrates a HTML label without a table.
1426
1427       Also demonstrates an arrayref of strings as a label.
1428
1429       See also scripts/record.*.pl for other label techniques.
1430
1431       Outputs to ./html/html.labels.1.svg by default.
1432
1433   scripts/html.labels.2.pl
1434       Demonstrates a HTML label with a table.
1435
1436       Outputs to ./html/html.labels.2.svg by default.
1437
1438   scripts/macro.1.pl
1439       Demonstrates non-cluster subgraphs via a macro.
1440
1441       Outputs to ./html/macro.1.svg by default.
1442
1443   scripts/macro.2.pl
1444       Demonstrates linked non-cluster subgraphs via a macro.
1445
1446       Outputs to ./html/macro.2.svg by default.
1447
1448   scripts/macro.3.pl
1449       Demonstrates cluster subgraphs via a macro.
1450
1451       Outputs to ./html/macro.3.svg by default.
1452
1453   scripts/macro.4.pl
1454       Demonstrates linked cluster subgraphs via a macro.
1455
1456       Outputs to ./html/macro.4.svg by default.
1457
1458   scripts/macro.5.pl
1459       Demonstrates compound cluster subgraphs via a macro.
1460
1461       Outputs to ./html/macro.5.svg by default.
1462
1463   scripts/parse.data.pl
1464       Demonstrates graphing a Perl data structure.
1465
1466       Outputs to ./html/parse.data.svg by default.
1467
1468   scripts/parse.html.pl
1469       Demonstrates using XML::Bare to parse HTML.
1470
1471       Inputs from ./t/sample.html, and outputs to ./html/parse.html.svg by
1472       default.
1473
1474   scripts/parse.isa.pl
1475       Demonstrates combining 2 Perl class hierarchies on the same graph.
1476
1477       Outputs to ./html/parse.isa.svg by default.
1478
1479       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
1482       See also dependency.pl, above.
1483
1484   scripts/parse.recdescent.pl
1485       Demonstrates graphing a Parse::RecDescent-style grammar.
1486
1487       Inputs from t/sample.recdescent.1.dat and outputs to
1488       ./html/parse.recdescent.svg by default.
1489
1490       The input grammar was extracted from t/basics.t in Parse::RecDescent V
1491       1.965001.
1492
1493       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
1497   scripts/parse.regexp.pl
1498       Demonstrates graphing a Perl regular expression.
1499
1500       Outputs to ./html/parse.regexp.svg by default.
1501
1502   scripts/parse.stt.pl
1503       Demonstrates graphing a Set::FA::Element-style state transition table.
1504
1505       Inputs from t/sample.stt.1.dat and outputs to ./html/parse.stt.svg by
1506       default.
1507
1508       The input grammar was extracted from Set::FA::Element.
1509
1510       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
1515   scripts/parse.yacc.pl
1516       Demonstrates graphing a byacc <http://invisible-
1517       island.net/byacc/byacc.html>-style grammar.
1518
1519       Inputs from t/calc3.output, and outputs to ./html/parse.yacc.svg by
1520       default.
1521
1522       The input was copied from test/calc3.y in byacc V 20101229 and process
1523       as below.
1524
1525       Note: The version downloadable via HTTP is 20101127.
1526
1527       I installed byacc like this:
1528
1529               sudo apt-get byacc
1530
1531       Now get a sample file to work with:
1532
1533               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
1543       It's the file calc3.output which ships in the t/ directory.
1544
1545   scripts/parse.yapp.pl
1546       Demonstrates graphing a Parse::Yapp-style grammar.
1547
1548       Inputs from t/calc.output, and outputs to ./html/parse.yapp.svg by
1549       default.
1550
1551       The input was copied from t/calc.t in Parse::Yapp's and processed as
1552       below.
1553
1554       I installed Parse::Yapp (and yapp) like this:
1555
1556               cpanm Parse::Yapp
1557
1558       Now get a sample file to work with:
1559
1560               cd ~/perl.modules/GraphViz2
1561               cp ~/.cpanm/latest-build/Parse-Yapp-1.05/t/calc.t t/calc.input
1562
1563       Edit t/calc.input to delete the code, leaving the grammar after the
1564       __DATA__token.
1565
1566               yapp -v t/calc.input > t/calc.output
1567               rm t/calc.pm
1568
1569       It's the file calc.output which ships in the t/ directory.
1570
1571   scripts/parse.xml.bare.pl
1572       Demonstrates using XML::Bare to parse XML.
1573
1574       Inputs from ./t/sample.xml, and outputs to ./html/parse.xml.bare.svg by
1575       default.
1576
1577   scripts/parse.xml.pp.pl
1578       Demonstrates using XML::Tiny to parse XML.
1579
1580       Inputs from ./t/sample.xml, and outputs to ./html/parse.xml.pp.svg by
1581       default.
1582
1583   scripts/quote.pl
1584       Demonstrates embedded newlines and double-quotes in node names and
1585       labels.
1586
1587       It also demonstrates that the justification escapes, \l and \r, work
1588       too, sometimes.
1589
1590       Outputs to ./html/quote.svg by default.
1591
1592       Tests which run dot directly show this is a bug in Graphviz
1593       <http://www.graphviz.org/> itself.
1594
1595       For example, in this graph, it looks like \r only works after \l (node
1596       d), but not always (nodes b, c).
1597
1598       Call this x.gv:
1599
1600               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
1609       and use the command:
1610
1611               dot -Tsvg x.gv > x.svg
1612
1613       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
1617   scripts/rank.sub.graph.1.pl
1618       Demonstrates a very neat way of controlling the rank attribute of nodes
1619       within subgraphs.
1620
1621       Outputs to ./html/rank.sub.graph.1.svg by default.
1622
1623   scripts/rank.sub.graph.2.pl
1624       Demonstrates a long-winded way of controlling the rank attribute of
1625       nodes within subgraphs.
1626
1627       Outputs to ./html/rank.sub.graph.2.svg by default.
1628
1629   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
1633       Outputs to ./html/rank.sub.graph.3.svg by default.
1634
1635   scripts/record.1.pl
1636       Demonstrates a string as a label, containing both ports and orientation
1637       markers ({}).
1638
1639       Outputs to ./html/record.1.svg by default.
1640
1641       See also scripts/html.labels.2.pl and scripts/record.*.pl for other
1642       label techniques.
1643
1644   scripts/record.2.pl
1645       Demonstrates an arrayref of hashrefs as a label, containing both ports
1646       and orientation markers ({}).
1647
1648       Outputs to ./html/record.2.svg by default.
1649
1650       See also scripts/html.labels.1.pl the other type of HTML labels.
1651
1652   scripts/record.3.pl
1653       Demonstrates a string as a label, containing ports and deeply nested
1654       orientation markers ({}).
1655
1656       Outputs to ./html/record.3.svg by default.
1657
1658       See also scripts/html.labels.*.pl and scripts/record.*.pl for other
1659       label techniques.
1660
1661   scripts/record.4.pl
1662       Demonstrates setting node shapes by default and explicitly.
1663
1664       Outputs to ./html/record.4.svg by default.
1665
1666   scripts/rank.sub.graph.4.pl
1667       Demonstrates the effect of the name of a subgraph, when that name
1668       starts with 'cluster'.
1669
1670       Outputs to ./html/rank.sub.graph.4.svg by default.
1671
1672   scripts/report.nodes.and.edges.pl
1673       Demonstates how to access the data returned by "edge_hash()" and
1674       "node_hash()".
1675
1676       Prints node and edge attributes.
1677
1678       Outputs to STDOUT.
1679
1680   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
1685       Outputs to STDOUT.
1686
1687   scripts/sqlite.foreign.keys.pl
1688       Demonstrates how to find foreign key info by calling SQLite's pragma
1689       foreign_key_list.
1690
1691       Outputs to STDOUT.
1692
1693   scripts/sub.graph.frames.pl
1694       Demonstrates clusters with and without frames.
1695
1696       Outputs to ./html/sub.graph.frames.svg by default.
1697
1698   scripts/sub.graph.pl
1699       Demonstrates a graph combined with a subgraph.
1700
1701       Outputs to ./html/sub.graph.svg by default.
1702
1703   scripts/sub.sub.graph.pl
1704       Demonstrates a graph combined with a subgraph combined with a
1705       subsubgraph.
1706
1707       Outputs to ./html/sub.sub.graph.svg by default.
1708
1709   scripts/trivial.pl
1710       Demonstrates a trivial 3-node graph, with colors, just to get you
1711       started.
1712
1713       Outputs to ./html/trivial.svg by default.
1714
1715   scripts/utf8.1.pl
1716       Demonstrates using utf8 characters in labels.
1717
1718       Outputs to ./html/utf8.1.svg by default.
1719
1720   scripts/utf8.2.pl
1721       Demonstrates using utf8 characters in labels.
1722
1723       Outputs to ./html/utf8.2.svg by default.
1724

TODO

1726       o Does GraphViz2 need to emulate the sort option in GraphViz?
1727           That depends on what that option really does.
1728
1729       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
1733       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

A Extremely Short List of Other Graphing Software

1739       Axis Maps <http://www.axismaps.com/>.
1740
1741       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
1747       Voronoi Applications
1748       <http://www.voronoi.com/wiki/index.php?title=Voronoi_Applications>.
1749

Thanks

1751       Many thanks are due to the people who chose to make Graphviz
1752       <http://www.graphviz.org/> Open Source.
1753
1754       And thanks to Leon Brocard <http://search.cpan.org/~lbrocard/>, who
1755       wrote GraphViz, and kindly gave me co-maint of the module.
1756

Version Numbers

1758       Version numbers < 1.00 represent development versions. From 1.00 up,
1759       they are production versions.
1760

Machine-Readable Change Log

1762       The file Changes was converted into Changelog.ini by
1763       Module::Metadata::Changes.
1764

Repository

1766       <https://github.com/ronsavage/GraphViz2.git>
1767

Support

1769       Email the author, or log a bug on RT:
1770
1771       <https://rt.cpan.org/Public/Dist/Display.html?Name=GraphViz2>.
1772

Author

1774       GraphViz2 was written by Ron Savage <ron@savage.net.au> in 2011.
1775
1776       Home page: <http://savage.net.au/index.html>.
1777
1779       Australian copyright (c) 2011, Ron Savage.
1780
1781               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/
1785
1786
1787
1788perl v5.30.1                      2020-01-30                      GraphViz2(3)
Impressum