Modules

Accepts a Graphviz graph definition and builds a corresponding data structure representing the parsed graph. It can pass that data to the default renderer, GraphViz2::Marpa::Renderer::Graphviz, which can then render it to a text file ready to be input to dot. Such 'round-tripping', as it's called, is the best way to test a renderer.

And yes, the graph ID, if any, is under the graph node. The reason for this is that for every subgraph within the graph, the same structure applies: First the (sub)graph ID, then a literal '{', then that (sub)graph's details, and finally a literal '}'.

o The 'graph' sub-tree

The graph node is the root of a sub-tree holding everything about the graph, including the graph's ID, if any.

The node is called graph, and its hashref of attributes is {type => "graph_literal", uid => "2", value => "graph"}.

The graph node has as many daughters, with their own daughters, as is necessary to hold the output of parsing the remainder of the input.

In particular, if the input graph has an ID, i.e. the input is of the form 'digraph my_id ...' (or various versions thereof) then the 1st daughter will be called node_id, and its attributes will be {type => "node_id", uid => "5", value => "my_id"}.

Futher, the 2nd daughter will be called literal, and its attributes will be {ype => "open_brace", uid => "6", value => "{"}. A subsequent daughter will eventually (for a syntax-free input file, of course) also be called literal, and its attributes will be {type => "close_brace", uid => "#", value => "}"}.

Naturally, if the graph has no ID (i.e. input lacks the 'my_id' token) then the uids will differ slightly.

As mentioned, this pattern of optional (sub)graph id followed by a matching pair of '{', '}' nodes, is used for all graphs and subgraphs.

In the case the input contains an explicit subgraph, then just before the node representing 'my_id' or '{', there will be another node representing the subgraph token.

It's name will be literal, and its attributes will be {type => "subgraph_literal", uid => "#", value => "subgraph"}.

How many different names can these nodes have?

The list of possible node names follows. You should always examine the type and value keys of the node's attributes to determine the exact nature of the node.

o attribute

In this case, the node's attributes contain a hashref like {type => "arrowhead", uid => "33", value => "odiamond"}, meaning the type field holds the type (i.e. name) of the attribute, and the 'value' field holds the value of the attribute.

o class

This is used when any of edge, graph, or node appear at the start of the (sub)graph, and is the mother of the attributes attached to the class. The value of the attribute will be edge, graph, or node.

The 1st and last daughters will be literals whose attribute values are '[' and ']' respectively, and the middle daughter(s) will be nodes of type attribute (as just discussed).

o edge_id

The value of the attribute will be either '--' or '->'.

Thus the tail of the edge will be the previous daughter (node or subgraph), and the head of the edge will be the next.

Samples are:

n1 -> n2
n1 -> {n2}
{n1} -> n2

In a daisy chain of nodes, the last node in the chain may have daughters that are the attributes of each edge in the chain. This is how Graphviz syntax attaches edge attributes to a path. The class edge can also be used to provide attributes for the edge.

o graph

There is only ever 1 node called graph. This tree node is always present.

o graph_id

There is only ever 1 node called graph_id.

If present, it's mother must be the tree node called graph, in which case it will be the first daughter of graph.

But, it will be absent if the graph is unnamed, as in strict digraph /* no name */ {...}.

o literal

literal is the name of some nodes, with the value key in the attributes having one of these values:

o {

Indicates the start of a (sub)graph.

o }

Indicates the end of a (sub)graph.

o [

This indicates the start of a set of attributes for a specific class, edge or node, or the edge attributes at the end of a path.

The 1st and last daughters will be literals whose attribute value keys are '[' and ']' respectively.

Between these 2 nodes will be 1 node for each attribute, as seen above with edge ["color" = "green",].

Note: Graphviz allows an abbreviated syntax for setting the attributes of a (sub)graph. So, instead of needing:

graph [rankdir = LR]

You can just use:

rankdir = LR

In such cases, these attributes are not surrounded by '[' and ']'.

o ]

See the previous point.

o digraph_literal

o graph_literal

o strict_literal

o subgraph_literal

o node_id

The value of the attributes is the name of the graph, a node, or a subgraph.

Note: A node name can appear more than once in succession, either as a declaration of the node's existence and then as the tail of an edge, or, as in this fragment of data/56.gv:

How are HTML-like labels handled

The main grammar (See $self -> bnf in the source) is used to hold the definitions of strings (See strict_literal). Thus Marpa, via the main parser $self -> recce, is used to identify all types of strings.

Then, if the string starts with '>', _process_html() is called, and has a separate grammar (See bnf4html). This in turn uses a separate grammar object (grammar4html) and a separate parser (recce4html). _process_html() traps any apparent parsing errors, found when lexemes (text) follows the HTML, and saves the label's value. This method also sets $pos to the first char after the HTML, so when control returns to the main parser, and the main grammar, the main parser is not aware of the existence of the HTML, and just keeps on parsing from where the HTML parser finished.

How are comments stored in the tree?

They aren't stored, they are discarded. And this in turn means rendered dot files can't ever contain them.

Thanks

And thanks to rns (Ruslan Shvedov) for writing the grammar for double-quoted strings used in MarpaX::Demo::SampleScripts's scripts/quoted.strings.02.pl. I adapted it to HTML (see scripts/quoted.strings.05.pl in that module), and then incorporated the grammar into this module. For details, search for bnf4html, grammar4html and recce4html in the source of the current module.

Author

Copyright

Australian copyright (c) 2012, Ron Savage.

All Programs of mine are 'OSI Certified Open Source Software';
you can redistribute them and/or modify them under the terms of
The Perl License, a copy of which is available at:
http://dev.perl.org/licenses/

Module Install Instructions

To install GraphViz2::Marpa, simply copy and paste either of the commands in to your terminal