"GraphViz::Data::Structure::Debug"

  # Turn on GraphViz::Data::Structure debugging.
  $GraphViz::Data::Structure::Debug = 1;

"new()"

  # Graph a data structure, creating a GraphViz object.
  # The new GraphViz:Data::Structure object, the name of
  # the top node in the structure, and the "in" port are returned.
  my ($gvds, $top_name, @port) =
   GraphViz::Data::Structure->new($structure);
  print $gvds->graph()->as_png("my.png");

If you so desire, you can use the returned information to join other graphs up to the top of the graph contained in this object by callling "graph()" to extract the "GraphViz" object and calling other "GraphViz" primitives on that object. Most of the time you'll only care about the "GraphViz::Data::Structure" object and not the additional info.

Optional parameters

You can specify any, none, or all of the following optional keyword parameters:

"GraphViz"

You can specify your own "GraphViz" object, in which the graph will be built. "GraphViz::Data::Structure" nodes all start with the string "gvds"; if you avoid using nodes with similar names, you should not have any nodename collisions.

  # Create a graph of a data structure, using your own GraphViz object
  my ($gvds, $top_name, @port) =
    GraphViz::Data::Structure->new($structure,
                                   GraphViz => GraphViz->new());
  $gvds->graph()->as_png("my.png");
    

"Depth"

If the "Depth" parameter is supplied, "GraphViz::Data::Structure" stops at the designated level. If any references are found at this level, plaintext "..." nodes are constructed for them. The default limit is no limit.

  # Stop after reaching level 7.
  my ($gvds, $top_name, @port) =
    GraphViz::Data::Structure->new($structure,
                                   Level => 7);
  $gvds->graph()->as_png("my.png");
    

This can be useful if you have a very large data structure, but showing just the upper levels is sufficient for your purposes.

"Fuzz"

If your data structure has large pieces of text in it, you will probably want to limit the size of the text displayed to keep "GraphViz" from creating huge unwieldy nodes. "Fuzz" allows you to specify the maximum length of any text to be inserted into blocks; the default value is 40 characters.

  # Trim any text to 20 characters or less.
  my ($gvds, $top_name, @port) =
    GraphViz::Data::Structure->new($structure,
                                   Fuzz => 20);
  $gvds->graph()->as_png("my.png");
    

Be aware: large values for "Fuzz" will result in long character strings being passed to "dot", which will eventually segfault if the strings are long enough.

"Orientation"

You can choose to have your records laid out so that arrays and hashes are either laid out horizontally, with class labels at the top, or vertically, with class labels on the left. Default is "horizontal".

  # Stack items vertically.
  my ($gvds, $top_name, @port) =
    GraphViz::Data::Structure->new($structure,
                                   Orientation => 'vertical');
  $gvds->graph()->as_png("my.png");
    

You cannot mix horizontal and vertical layouts in the same graph.

Other parameters

"GraphViz" supports a number of other parameters at the graph level; any parameters that "GraphViz::Data::Structure" doesn't understand itself will be passed on to "GraphViz".

  # Add a title and change the default font:
  my ($gvds, $top_name, @port) =
    GraphViz::Data::Structure->new($structure,
                                   graph => {label    => 'My graph',
                                             fontname => 'Helvetica'}
                                  );
    

"add()"

  # Create a graph (replicates the new() call). Parameters default.
  my ($gvds, $top_name, @ports) =
    GraphViz::Data::Structure->add($structure);

"graph()"

Methods include "as_ps", "as_hpgl", "as_pcl", "as_mif", "as_pic", "as_gd", "as_gd2", "as_gif", "as_jpeg", "as_png", "as_wbmp", "as_ismap", "as_imap", "as_vrml", "as_vtx", "as_mp", "as_fig", "as_svg". See the "GraphViz" documentation for more information. The most common methods are:

  # Print out a PNG-format file
  print $gvds->graph->as_png();

  # Print out a PostScript-format file
  print $gvds->graph->as_ps();

  # Print out a dot file, in "canonical" form:
  print $gvds->graph->as_canon();

"was_null"

"was_null" forces a "dot" run to get the "canonical" form of the graph back, which can be computationally expensive; avoid it if possible.

"add()"

You can specify the "Fuzz", "Label", and "Depth" arguments, just as you would for "new()". You cannot specify "GraphViz", "Orientation", or any of the "GraphViz" parameters that are used to create a "GraphViz" object; "add()" uses the pre-existing "GraphViz" object in the "GraphViz::Data::Structure" object to add new nodes.

  # Create a graph (replicates the new() call).
  my ($gvds, $top_name, @ports) =
    GraphViz::Data::Structure->add($structure);

  # Add a second structure; nodes will be merged as necessary.
  my ($gvds, $top_name, @ports) =  $gvds->add($structure);

SCALARS

If a scalar's value is a reference, we add a record-style node and link it to the value. If the scalar is blessed, we put the class name and the scalar's value both in the same node by constructing a multi-line string with the class name on top, tagged appropriately, and the value on the bottom.

ARRAYS

Unblessed, laid out vertically

Unblessed, laid out horizontally

Blessed, laid out vertically

Blessed, laid out horizontally

Unblessed arrays should (ideally) simply be rows of boxes, with either values or edges each box. We can set up port strings for this fairly easily:

   # Array assumed to contain (1,\$x,"s").
   $ports = "<port1>1|<port2>|<port3>s";

This gives a nice row of boxes, with all the cells lined up nicely in either horizontal or vertical orientations. We don't need extra fiddling with the port string to get them to look right.

Things become a bit mode complex for blessed arrays, though, because we want to include the class name as well in the record. We want to make sure that the class name itself isn't confused with any of the data items, so it needs to be off in a box by itself, parallel to the boxes defining the array. This means laying out a box the length of the whole array above the boxes defining the array in a horizontal layout, and a box the height of the whole array to the left of the boxes defining the array in a vertical layout.

Fortunately (again), the same basic port string works in both orientations.

   # Object is an array blessed into class "Foo", containing (1,\$x,"s").
   # Horizontal:
   $ports = "{<port0>Foo|{{<port1>1}|{<port2>}|{<port2>s}}}";

Note that we use the alernating braced items to get the array to lay out at 90 degrees from the box containing the class name. This particular string was arrived at after a fair amount of twiddling in "dotty" and seems to be the simplest port layout that works.

Empty arrays, if they're unblessed, are just shown as a "[]" plaintext node. If they're blessed, we set up a record that looks sort of like a two-element array, but contains the classname, notes that it's an array, and shows that it's empty explicitly.

HASHES

Unblessed, laid out vertically (key to right of value)

Unblessed, laid out horizontally (key above value)

Blessed, laid out vertically (key below value)

Blessed, laid out horizontally (key to right of value)

Unblessed hashes should (ideally) simply be pairs of rows of boxes - one for key, one for value - with either values or edges in each "key" box. Setting up port strings for this is a bit more difficult.

   # Hash assumed to contain (A=>1,B=>\$x,C=>"s").
   # Horizontal:
   $hports = "{<port1>A|<port2>1}|{<port3>B|<port4>}|{<port5>C|<port6>s}";

   # Vertical:
   $vports = "{<port1>A|<port3>B|<port5>C}|{<port2>1|<port4>|<port6>s}";

Switching from horizontal to vertical requires us to separate the keys from the values.

Adding a class name presents some problems. "dot" is not absolutely symmetric when it comes to parsing complex port strings; in some cases, it carefully lines up all the edges of boxes internal to a record; other times it doesn't. Rather than continue to try to kludge around this, it seemed the better part of valor to simply accept what it would do prettily and ignore the rest. In laying out blessed hashes (and following our self-imposed standard), we can either have

a single box on the left containing the class name for hashes laid out vertically

a single box the top containing the class name for hashes laid out horizontally

Anything else both significantly increases the complexity of the interface ("let's see, arrays should be horizontal, and hashes should be horizontal with names on top, so I code ... uh ...") and, well, doesn't work very well. So we stick with these two basic layouts and keep it pretty and simple.

   # Object is an hash blessed into class "Foo".
   # Hash assumed to contain (A=>1,B=>\$x,C=>"s").
   # Horizontal, name on top:
   $hports =
   "{<port0>Foo|{{<port1>A|<port2>1}|{<port3>B|<port4>}|{<port5>C|<port6>s}}}";

   # Vertical, name on left:
   $vports =
   "<port0>Foo|{<port1>A|<port3>B|<port5>C}|{<port2>1|<port4>|<port6>s}";

Note that we also have to change how we add the braces to the keys and values when switching where the name is, in addition to separating or associating the keys and values as needed.

The good thing is that once this is all worked out, no one else has to care anymore. It just works and looks nice.

GLOBS

In the interest of coding as little as possible, we just reuse the hash code. We construct a tiny pair of wrapper methods which add the necessary information to the parameter list and then call the common module.

CODE references

HANDING TEXT TO DOT

It is necessary to clean up and shorten any text that "dot" will be expected to put into a node. The "_dot_escape" method is used to do this.

Note that the limit on strings is actually not very large; setting a really big "Fuzz" will probably make "dot" segfault when it tries to draw your graph.