dot_parser/
lib.rs

1#![warn(missing_docs)]
2
3//! This crate is a parser for [DOT/Graphviz](https://www.graphviz.org) files.
4//! The parser strictly sticks to the grammar specified
5//! [here](https://www.graphviz.org/doc/info/lang.html). Notice that the
6//! official implementation of Graphviz tools *does not* strictly follows this
7//! grammar. However all graphs following the grammar are accepted by official
8//! tools.
9//!
10//! The crate contains two modules: [`ast`] and [`canonical`]. Both contain a
11//! `Graph` structure that represent a DOT graph. In the [`ast`] module, the
12//! [`Graph`][ast::Graph] structure matches the abstract syntax tree of a given
13//! DOT graph. However, in practice, such graph is not easy to work with.
14//! Therefore, the [`Graph`][canonical::Graph] structure in the [`canonical`]
15//! module aims to provide a canonic representation of the graph, much easier to
16//! work with.
17//!
18//! ## [canonical::Graph]
19//!
20//! Unless you have a good reason to use [ast::Graph], I would recommend using
21//! [canonical::Graph]. For instance, since [ast::Graph] follows closely the
22//! [Graphviz grammar](https://www.graphviz.org/doc/info/lang.html), iterating
23//! over all edges is quite complex: one has to take into account chained edges
24//! (e.g. `A -> B -> C` is a single [ast::EdgeStmt], but it represents two
25//! edges: `A -> B` and `A -> C`), as well as subgraphs (e.g. `A -> subgraph {B
26//! C}` contains two edges: `A -> B` and `A -> C`, and subgraph can be nested).
27//! On the other hand, [canonical::Graph] flattens all those edges for you,
28//! which makes iterating over the edges extremelly trivial: 
29//!
30//! ```
31//! use dot_parser::*;
32//! let graph = canonical::Graph::from(
33//!     ast::Graph::try_from("graph { A -> subgraph { B C } }").unwrap()
34//!     );
35//! for edge in graph.edges.set {
36//!     println!("{} -> {}", edge.from, edge.to);
37//! }
38//! ```
39//!
40//! ## [ast::Graph]
41//! The main structure of this module is [`ast::Graph`]. It implements
42//! `TryFrom<&str>`, which allows one to parse a [`&str`]. It also provides a
43//! function [`from_file`][ast::Graph::from_file] to read a graph directly from
44//! a file. The fields (and subfields) of the structure coincide with rules of
45//! the grammar.
46//!
47//! ## Feature flags
48//!
49//! This crate offers the following feature flags (all disable by default):
50//!  - display: if enabled, most structures implement
51//!  [Display][std::fmt::Display], as long as the attribute type implements
52//!  [Display][std::fmt::Display]. Graphs can be printed (following the
53//!  DOT/Graphviz syntax).
54//!  - petgraph: if enabled, [Graph][canonical::Graph] can be converted into
55//!  [petgraphs'
56//!  graphs](https://docs.rs/petgraph/latest/petgraph/graph/struct.Graph.html).
57//!  Essentially, enabling this flag provides the following implementation: 
58//!  ```no_compile
59//! impl<A> From<Graph<A>> for PetGraph<Node<A>, AList<A>> { ... }
60//!  ```
61//!  - to_tokens: if enabled, [Graph][ast::Graph]s implement quote's
62//!  [ToTokens](https://docs.rs/quote/latest/quote/trait.ToTokens.html) trait,
63//!  allowing one to easily generate graphs in macros. This is mainly used in
64//!  [dot_parser_macros](https://docs.rs/dot-parser-macros/0.2.0/dot_parser_macros/).
65
66pub mod ast;
67pub mod canonical;
68mod subgraph_free;
dot_parser/lib.rs

dot_parser/
lib.rs
