Crate dot_parser

This crate is a parser for DOT/Graphviz files. The parser strictly sticks to the grammar specified here. Notice that the official implementation of Graphviz tools does not strictly follows this grammar. However all graphs following the grammar are accepted by official tools.

The crate contains two modules: ast and canonical. Both contain a Graph structure that represent a DOT graph. In the ast module, the Graph structure matches the abstract syntax tree of a given DOT graph. However, in practice, such graph is not easy to work with. Therefore, the Graph structure in the canonical module aims to provide a canonic representation of the graph, much easier to work with.

canonical::Graph

Unless you have a good reason to use ast::Graph, I would recommend using canonical::Graph. For instance, since ast::Graph follows closely the Graphviz grammar, iterating over all edges is quite complex: one has to take into account chained edges (e.g. A -> B -> C is a single ast::EdgeStmt, but it represents two edges: A -> B and A -> C), as well as subgraphs (e.g. A -> subgraph {B C} contains two edges: A -> B and A -> C, and subgraph can be nested). On the other hand, canonical::Graph flattens all those edges for you, which makes iterating over the edges extremelly trivial:

use dot_parser::*;
let graph = canonical::Graph::from(
    ast::Graph::try_from("graph { A -> subgraph { B C } }").unwrap()
    );
for edge in graph.edges.set {
    println!("{} -> {}", edge.from, edge.to);
}

ast::Graph

The main structure of this module is ast::Graph. It implements TryFrom<&str>, which allows one to parse a &str. It also provides a function from_file to read a graph directly from a file. The fields (and subfields) of the structure coincide with rules of the grammar.

Feature flags

This crate offers the following feature flags (all disable by default):

• display: if enabled, most structures implement Display, as long as the attribute type implements Display. Graphs can be printed (following the DOT/Graphviz syntax).
• petgraph: if enabled, Graph can be converted into petgraphs’ graphs. Essentially, enabling this flag provides the following implementation:

impl<A> From<Graph<A>> for PetGraph<Node<A>, AList<A>> { ... }

• to_tokens: if enabled, Graphs implement quote’s ToTokens trait, allowing one to easily generate graphs in macros. This is mainly used in dot_parser_macros.

Modules

ast

This module implements an Abstract Syntax Tree for Dot graphs. The main structure is Graph, which corresponds to the graph non-terminal in the grammar.

canonical

This modules implement “Canonical graphs”. This is motivated by the fact that graphs parsed naively may be difficult to work with, from a programming viewpoint: typically, attr_list in the grammar are defined as “[ID = ID, …][ID = ID, …]”. Therefore, we may want to flatten such structures. This is done in the canonical module.