#graph #dot #graphviz #parser #dotfile #reading-file

dot-parser

This library provides a parser for the DOT/Graphviz graph description language, as well as useful functions to transform those graphs

6 releases

0.2.1 May 28, 2024
0.2.0 May 26, 2024
0.1.3 Sep 8, 2022
0.1.0 Nov 17, 2021

#297 in Parser implementations

Download history 16/week @ 2024-02-26 10/week @ 2024-03-04 7/week @ 2024-03-11 24/week @ 2024-04-01 4/week @ 2024-04-08 92/week @ 2024-05-20 231/week @ 2024-05-27 21/week @ 2024-06-03

344 downloads per month
Used in 3 crates

GPL-2.0-or-later

79KB
2K SLoC

dot-parser

This crate provides a parser for dot files, also known as Graphviz. The implementation sticks closely to the formal grammar given by Graphviz. In addition, we provide transformation functions (i.e. an equivalent of flat_map for lists) in order to manipulate graphs, as well as a canonical representation of graphs, which flattens subgraphs and replaces edge statements with multiple right-hand sides with simple edge statements.

Usage

In Cargo.toml:

dot-parser = "*"

In your Rust source file (to be adapted depending on your needs):

use dot_parser::*;

Then, a file can be parsed using the from_file method of dot_parser::ast::Graph. Parsing a file can fail if there is an issue with opening and reading the file, or if the content of the file is not a valid Graphviz graph.

fn main() {
	let res = ast::Graph::from_file("/path/to/graph.dot");
	match res {
		Ok(graph) =>
			println!("{:#?}", graph),
		Err(e) => 
			println!("{}", e),
	}
}

Dealing with dot_parser::ast::Graphs is quite unconvenient, as the representation sticks closely to the Graphviz grammar. For instance, we have to consider subgraphs or lists of list of attributes, etc. Instead, dot_parser::canonical::Graphs are easier to work with.

fn main() {
	let res = ast::Graph::from_file("/path/to/graph.dot").unwrap();
    let canonical = canonical::Graph::from(res);
    println!("{:#?}", canonical);
}

Features

Outputting a dot graph

With the display feature, canonical graphs can be displayed (following the Graphviz grammar), as long as the type of attributes implements Display.

fn main() {
	let res = ast::Graph::from_file("/path/to/graph.dot").unwrap();
    let canonical = canonical::Graph::from(res).filter_map::<String>(&|s| None);
    println!("{}", canonical);
}

Petgraph compatibility

Canonical graphs can be converted into Petgraph's graphs with the petgraph feature.

fn main() {
	let res = ast::Graph::from_file("/path/to/graph.dot").unwrap();
    let canonical = canonical::Graph::from(res);
    let petgraph: petgraph::graph::Graph<_, _> = canonical.into();
    println!("{:#?}", canonical);
}

Compile time import

Graphs can be imported at compile time using dot_parser_macros:

use dot_parser_macros::*;
use dot_parser::ast::Graph;

fn main() {
    let graph = from_dot!("/tmp/graph.dot");
    println!("{:#?}", graph);
}

Acknowledgement

This crate was written by Martin Vassor, member of the Mobility Reading Group at the University of Oxford (formerly at Imperial College, London).

Initial development of this work (up to v0.1.3) was supported by EPSRC EP/T006544/1, EP/K011715/1, EP/K034413/1, EP/L00058X/1, EP/N027833/1, EP/N028201/1, EP/T014709/1, EP/V000462/1, and NCSS/EPSRC VeTSS.

Dependencies

~2.2–3.5MB
~65K SLoC