Crate dot

Expand description

Generate files suitable for use with Graphviz

The render function generates output (e.g. an output.dot file) for use with Graphviz by walking a labelled graph. (Graphviz can then automatically lay out the nodes and edges of the graph, and also optionally render the graph as an image or other output formats, such as SVG.)

Rather than impose some particular graph data structure on clients, this library exposes two traits that clients can implement on their own structs before handing them over to the rendering function.

Note: This library does not yet provide access to the full expressiveness of the DOT language. For example, there are many attributes related to providing layout hints (e.g. left-to-right versus top-down, which algorithm to use, etc). The current intention of this library is to emit a human-readable .dot file with very regular structure suitable for easy post-processing.

Examples

The first example uses a very simple graph representation: a list of pairs of ints, representing the edges (the node set is implicit). Each node label is derived directly from the int representing the node, while the edge labels are all empty strings.

This example also illustrates how to use Cow<[T]> to return an owned vector or a borrowed slice as appropriate: we construct the node vector from scratch, but borrow the edge list (rather than constructing a copy of all the edges from scratch).

The output from this example renders five nodes, with the first four forming a diamond-shaped acyclic graph and then pointing to the fifth which is cyclic.

use std::borrow::Cow;
use std::io::Write;

type Nd = isize;
type Ed = (isize,isize);
struct Edges(Vec<Ed>);

pub fn render_to<W: Write>(output: &mut W) {
    let edges = Edges(vec!((0,1), (0,2), (1,3), (2,3), (3,4), (4,4)));
    dot::render(&edges, output).unwrap()
}

impl<'a> dot::Labeller<'a, Nd, Ed> for Edges {
    fn graph_id(&'a self) -> dot::Id<'a> { dot::Id::new("example1").unwrap() }

    fn node_id(&'a self, n: &Nd) -> dot::Id<'a> {
        dot::Id::new(format!("N{}", *n)).unwrap()
    }
}

impl<'a> dot::GraphWalk<'a, Nd, Ed> for Edges {
    fn nodes(&self) -> dot::Nodes<'a,Nd> {
        // (assumes that |N| \approxeq |E|)
        let &Edges(ref v) = self;
        let mut nodes = Vec::with_capacity(v.len());
        for &(s,t) in v {
            nodes.push(s); nodes.push(t);
        }
        nodes.sort();
        nodes.dedup();
        Cow::Owned(nodes)
    }

    fn edges(&'a self) -> dot::Edges<'a,Ed> {
        let &Edges(ref edges) = self;
        Cow::Borrowed(&edges[..])
    }

    fn source(&self, e: &Ed) -> Nd { e.0 }

    fn target(&self, e: &Ed) -> Nd { e.1 }
}

pub fn main() {
    use std::fs::File;
    let mut f = File::create("example1.dot").unwrap();
    render_to(&mut f)
}

Output from first example (in example1.dot):

digraph example1 {
    N0[label="N0"];
    N1[label="N1"];
    N2[label="N2"];
    N3[label="N3"];
    N4[label="N4"];
    N0 -> N1[label=""];
    N0 -> N2[label=""];
    N1 -> N3[label=""];
    N2 -> N3[label=""];
    N3 -> N4[label=""];
    N4 -> N4[label=""];
}

The second example illustrates using node_label and edge_label to add labels to the nodes and edges in the rendered graph. The graph here carries both nodes (the label text to use for rendering a particular node), and edges (again a list of (source,target) indices).

This example also illustrates how to use a type (in this case the edge type) that shares substructure with the graph: the edge type here is a direct reference to the (source,target) pair stored in the graph’s internal vector (rather than passing around a copy of the pair itself). Note that this implies that fn edges(&'a self) must construct a fresh Vec<&'a (usize,usize)> from the Vec<(usize,usize)> edges stored in self.

Since both the set of nodes and the set of edges are always constructed from scratch via iterators, we use the collect() method from the Iterator trait to collect the nodes and edges into freshly constructed growable Vec values (rather use the into from the IntoCow trait as was used in the first example above).

The output from this example renders four nodes that make up the Hasse-diagram for the subsets of the set {x, y}. Each edge is labelled with the ⊆ character (specified using the HTML character entity &sube).

use std::io::Write;

type Nd = usize;
type Ed<'a> = &'a (usize, usize);
struct Graph { nodes: Vec<&'static str>, edges: Vec<(usize,usize)> }

pub fn render_to<W: Write>(output: &mut W) {
    let nodes = vec!("{x,y}","{x}","{y}","{}");
    let edges = vec!((0,1), (0,2), (1,3), (2,3));
    let graph = Graph { nodes: nodes, edges: edges };

    dot::render(&graph, output).unwrap()
}

impl<'a> dot::Labeller<'a, Nd, Ed<'a>> for Graph {
    fn graph_id(&'a self) -> dot::Id<'a> { dot::Id::new("example2").unwrap() }
    fn node_id(&'a self, n: &Nd) -> dot::Id<'a> {
        dot::Id::new(format!("N{}", n)).unwrap()
    }
    fn node_label<'b>(&'b self, n: &Nd) -> dot::LabelText<'b> {
        dot::LabelText::LabelStr(self.nodes[*n].into())
    }
    fn edge_label<'b>(&'b self, _: &Ed) -> dot::LabelText<'b> {
        dot::LabelText::LabelStr("&sube;".into())
    }
}

impl<'a> dot::GraphWalk<'a, Nd, Ed<'a>> for Graph {
    fn nodes(&self) -> dot::Nodes<'a,Nd> { (0..self.nodes.len()).collect() }
    fn edges(&'a self) -> dot::Edges<'a,Ed<'a>> { self.edges.iter().collect() }
    fn source(&self, e: &Ed) -> Nd { e.0 }
    fn target(&self, e: &Ed) -> Nd { e.1 }
}

pub fn main() {
    use std::fs::File;
    let mut f = File::create("example2.dot").unwrap();
    render_to(&mut f)
}

The third example is similar to the second, except now each node and edge now carries a reference to the string label for each node as well as that node’s index. (This is another illustration of how to share structure with the graph itself, and why one might want to do so.)

The output from this example is the same as the second example: the Hasse-diagram for the subsets of the set {x, y}.

use std::io::Write;

type Nd<'a> = (usize, &'a str);
type Ed<'a> = (Nd<'a>, Nd<'a>);
struct Graph { nodes: Vec<&'static str>, edges: Vec<(usize,usize)> }

pub fn render_to<W: Write>(output: &mut W) {
    let nodes = vec!("{x,y}","{x}","{y}","{}");
    let edges = vec!((0,1), (0,2), (1,3), (2,3));
    let graph = Graph { nodes: nodes, edges: edges };

    dot::render(&graph, output).unwrap()
}

impl<'a> dot::Labeller<'a, Nd<'a>, Ed<'a>> for Graph {
    fn graph_id(&'a self) -> dot::Id<'a> { dot::Id::new("example3").unwrap() }
    fn node_id(&'a self, n: &Nd<'a>) -> dot::Id<'a> {
        dot::Id::new(format!("N{}", n.0)).unwrap()
    }
    fn node_label<'b>(&'b self, n: &Nd<'b>) -> dot::LabelText<'b> {
        let &(i, _) = n;
        dot::LabelText::LabelStr(self.nodes[i].into())
    }
    fn edge_label<'b>(&'b self, _: &Ed<'b>) -> dot::LabelText<'b> {
        dot::LabelText::LabelStr("&sube;".into())
    }
}

impl<'a> dot::GraphWalk<'a, Nd<'a>, Ed<'a>> for Graph {
    fn nodes(&'a self) -> dot::Nodes<'a,Nd<'a>> {
        self.nodes.iter().map(|s| &s[..]).enumerate().collect()
    }
    fn edges(&'a self) -> dot::Edges<'a,Ed<'a>> {
        self.edges.iter()
            .map(|&(i,j)|((i, &self.nodes[i][..]),
                          (j, &self.nodes[j][..])))
            .collect()
    }
    fn source(&self, e: &Ed<'a>) -> Nd<'a> { e.0 }
    fn target(&self, e: &Ed<'a>) -> Nd<'a> { e.1 }
}

pub fn main() {
    use std::fs::File;
    let mut f = File::create("example3.dot").unwrap();
    render_to(&mut f)
}

References

Structs

Arrow
This structure holds all information that can describe an arrow connected to either start or end of an edge.
Id
Id is a Graphviz ID.

Enums

ArrowShape
This enumeration represents all possible arrow edge as defined in graphviz documentation.
CompassPoint
Allowed values for compass points. Used for specifying edge directions. See also https://graphviz.org/docs/attr-types/portPos/
Fill
Arrow modifier that determines if the shape is empty or filled.
Kind
Graph kind determines if digraph or graph is used as keyword for the graph.
LabelText
The text for a graphviz label on a node or edge.
RankDir
The direction to draw directed graphs (one rank at a time) See https://graphviz.org/docs/attr-types/rankdir/ for descriptions
RenderOption
Side
Arrow modifier that determines if the shape is clipped. For example Side::Left means only left side is visible.
Style
The style for a node or edge. See https://graphviz.org/doc/info/attrs.html#k:style for descriptions. Note that some of these are not valid for edges.

Traits

GraphWalk
GraphWalk is an abstraction over a graph = (nodes,edges) made up of node handles N and edge handles E, where each E can be mapped to its source and target nodes.
Labeller
Each instance of a type that implements Label<C> maps to a unique identifier with respect to C, which is used to identify it in the generated .dot file. They can also provide more elaborate (and non-unique) label text that is used in the graphviz rendered output. The graph instance is responsible for providing the DOT compatible identifiers for the nodes and (optionally) rendered labels for the nodes and edges, as well as an identifier for the graph itself.

Functions

default_options
Returns vec holding all the default render options.
escape_html
Escape tags in such a way that it is suitable for inclusion in a Graphviz HTML label.
render
Renders graph g into the writer w in DOT syntax. (Simple wrapper around render_opts that passes a default set of options.)
render_opts
Renders graph g into the writer w in DOT syntax. (Main entry point for the library.)