rescribet / Dotlin

Kotlin Graphviz DOT DSL

Dotlin - Kotlin Graphviz Dot DSL

// build.gradle
implementation 'io.github.rchowell:dotlin:1.0.2'

// build.gradle.kts
implementation("io.github.rchowell:dotlin:1.0.2")

The library is just one file, Dot.kt — so you could just copy that file à la picocli.

About

This library is a Kotlin DSL for the Graphviz Dot language. Its syntax is fairly similar to standard Dot, with some tweaks to get it to work as a Kotlin DSL. The library can be useful to generate graphs.

digraph {

    // Normal Kotlin statements
    val p = (0..9).partition { it % 2 == 0 }
    val evens = p.first
    val odds = p.second

    // Building a Dot graph
    for (i in evens) {
        +"$i" + { shape = DotNodeShape.SQUARE }
        odds.filter { abs(it - i) == 1 }.forEach { "$it" - "$i" }
    }
    for (i in odds) {
        +"$i" + { shape = DotNodeShape.CIRCLE }
        evens.filter { abs(it - i) == 1 }.forEach { "$it" - "$i" }
    }
}

Puzzle

graph {
    "a" - "b"
    "a" - "c"
    "a" - "d"
    "b" - "a"
    "b" - "d"
    "c" - "a"
    "c" - "d"
}

Example

Dot

digraph g {
	node [shape=plaintext];
	A1 -> B1;
	A2 -> B2;
	A3 -> B3;
	
	A1 -> A2 [label=f];
	A2 -> A3 [label=g];
	B2 -> B3 [label="g'"];
	B1 -> B3 [label="(g o f)'" tailport=s headport=s];

	{ rank=same; A1 A2 A3 }
	{ rank=same; B1 B2 B3 } 
}

Dotlin

digraph("g") {

    // Global node attributes
    node {
        shape = DotNodeShape.PLAINTEXT
    }
    
    // Edges
    "A1" - "B1"
    "A2" - "B2"
    "A3" - "B3"
    "A1" - "A2" + { label = "f" }
    "A2" - "A3" + { label = "g" }
    "B2" - "B3" + { label = "g'" }
    "B1" - "B3" + {
        label = "(g o f)'"
        tailport = DotPortPos.S
        headport = DotPortPos.S
    }

    +subgraph {
        rank = "same"
        +"A1"
        +"A2"
        +"A3"
    }

    +subgraph {
        rank = "same"
        +"B1"
        +"B2"
        +"B3"
    }
}

Usage

Basics

// This produces the Dreampuf default graph
// https://dreampuf.github.io/GraphvizOnline 

val g = digraph("G") {

    +subgraph("cluster_0") {
        node {
            style = "filled"
            color = "white"
            "a0" - "a1"
            "a1" - "a2"
            "a2" - "a3"
        }
        style = DotSubgraphStyle.FILLED
        color = "lightgrey"
        label = "process #1"
    }

    +subgraph("cluster_1") {
        node {
            style = "filled"
        }
        "b0" - "b1"
        "b1" - "b2"
        "b2" - "b3"
        color = "blue"
        label = "process #2"
    }

    "start" - "a0"
    "start" - "b0"
    "a1" - "b3"
    "b2" - "a3"
    "a3" - "a0"
    "a3" - "end"
    "b3" - "end"

    +"start" + {
        shape = DotNodeShape.DIAMOND
    }
    +"end" + {
        shape = DotNodeShape.MSQUARE
    }
}

println(g.dot())

Attributes

This library has all attributes listed in the Graphviz docs with corresponding types. Some attributes allow for multiple types such as Boolean and String so you will find attributes with the suffixes "B" and "S" for Boolean and String respectively.

See https://graphviz.org/doc/info/attrs.html

Graphs

graph { ... }

digraph { ... }

graph("name") { ... }

digraph("name") { ... }

Nodes

Add nodes in graphs using the + unary operator like the Kotlin HTML DSL.

graph {
   // basic nodes
   +"a"
   +"b"
   
   // add node attributes using + binary infix op
   +"c" + {
     color = "blue"
   }
}

Edges

You can add edges between nodes using the binary infix -. You can add edges between nodes and subgraphs. The graph type -- graph vs digraph -- determines the edge type. In Dotlin, you just use - not "--" and "->".

graph {
    // Nodes with attributes
    +"a" + { color = "blue" }
    +"b" + { shape = DotNodeShape.TRAPEZIUM }
    
    // Basic Edge
    "a" - "b"
}

digraph {
    // Edge with attributes
    "a" - "z" + {
        color = "green"
        style = DotEdgeStyle.DASHED
    }
}

Subgraphs

Add subgraphs with +subgraph { ... } and the code within the subgraph block is the same as for a graph/digraph block.

graph {

    // Add subgraph to graph
    +subgraph {
        ...
    }
    
    // Subgraph as variable
    val sg = subgraph { ... }

    // Add it to the graph
    +sg
    
    // Subgraph as edge target
    "A" - subgraph { ... }
    
    // Subgraph as edge source
    subgraph { ... } - "B"
}

Reference

The library is based on the BNF given in the official docs. See https://graphviz.org/doc/info/lang.html

graph 	        : [ strict ] (graph | digraph) [ ID ] '{' stmt_list '}'
stmt_list       : [ stmt [ ';' ] stmt_list ]
stmt            : node_stmt
                  | 	edge_stmt
                  | 	attr_stmt
                  | 	ID '=' ID
                  | 	subgraph
attr_stmt 	: 	(graph | node | edge) attr_list
attr_list 	: 	'[' [ a_list ] ']' [ attr_list ]
a_list 		: 	ID '=' ID [ (';' | ',') ] [ a_list ]
edge_stmt 	: 	(node_id | subgraph) edgeRHS [ attr_list ]
edgeRHS 	: 	edgeop (node_id | subgraph) [ edgeRHS ]
node_stmt 	: 	node_id [ attr_list ]
node_id 	: 	ID [ port ]
port            : ':' ID [ ':' compass_pt ]
	          | ':' compass_pt
subgraph 	: 	[ subgraph [ ID ] ] '{' stmt_list '}'
compass_pt 	: 	(n | ne | e | se | s | sw | w | nw | c | _)