dot

README

dot

a lightweight, pure golang graphviz-compatible dot language implementation

📝 Table of Contents

• About
• Getting Started
• Usage
• Contributing
• Authors
• Acknowledgments

🧐 About

WARNING: this package is a WIP and will introduce breaking changes while on major version zero.

Dot provides interfaces and ready-to-use concrete types to create graphviz-compatible graphs using its dot language.

This package was inspired/initially forked from emicklei/dot, but has too many breaking changes compared to the original - namely interface usage and other distinct design decisions - that I decided to maintain it separately. If you need a simpler, no-brainy option, use emicklei's dot package.

🏁 Getting Started

Clone the repository and then run make to build, test, generate coverage and lint the code.

Prerequisites

Golang 1.12+ and ideally a modules-enabled application. Dot has no dependencies.

🎈 Usage

Add it to your modules with

go get -u github.com/wwmoraes/dot

And then:

package main

import (
  "os"
  "github.com/wwmoraes/dot"
  "github.com/wwmoraes/dot/attributes"
)

func main() {
  graph := dot.NewGraph(nil)
  clusterA := graph.Subgraph(&attributes.GraphOptions{ ID: "Cluster A", Cluster: true })
  clusterA.SetAttributeString("label", "Cluster A")
  clusterB := graph.Subgraph(&attributes.GraphOptions{ ID: "Cluster B", Cluster: true })
  clusterB.SetAttributeString("label", "Cluster B")

  clusterA.
    Node("one").
    Edge(clusterA.Node("two")).
    Edge(clusterB.Node("three")).
    Edge(graph.Node("Outside")).
    Edge(clusterB.Node("four")).
    Edge(clusterA.Node("one"))

  graph.Write(os.Create("sample.dot"))
}

The attributes sub-package has all supported keys defined as variables, and can be used instead of plain strings to avoid both duplication and errors:

graph := dot.NewGraph(nil)
graph.Node("n1").SetAttributeString(attributes.KeyLabel, "my label")

You can also set literals and HTML values using the helper functions:

graph := dot.NewGraph(nil)
graph.Node("n1").SetAttributeLiteral(attributes.KeyLabel, `my left label\l`)
graph.Node("n2").SetAttributeHTML(attributes.KeyLabel, `<b>a bold label</b>`)

✍️ Authors

• @emicklei - Original package
• @wwmoraes - Modified version

🎉 Acknowledgements

• @emicklei for the amazing original package, which initially helped me get rid of a graphviz cgo package I used on the kubegraph project
• @damianopetrungaro for the reviews and discussion about golang ways - my personal master Yoda!

Documentation

Overview

Package dot provides interfaces and ready-to-use concrete types to create graphviz-compatible graphs using its dot language.

This package was inspired/initially forked from github.com/emicklei/dot, but has too many breaking changes compared to the original - namely interface usage and other distinct design decisions - that it was decided to maintain separately. If you need a simpler, no-brainy option, use the original one.

Copyright (c) William Artero. MIT License

Index

• type Edge
• type Graph
  • func NewGraph(options *GraphOptions) Graph
• type GraphOptions
• type IDGenerator
• type IndentWriter
  • func NewIndentWriter(w io.Writer) *IndentWriter
  • func (i *IndentWriter) BackIndent()
  • func (i *IndentWriter) Indent()
  • func (i *IndentWriter) IndentWhile(block func())
  • func (i *IndentWriter) NewLine()
  • func (i *IndentWriter) NewLineIndentWhile(block func())
  • func (i *IndentWriter) Write(data []byte) (n int, err error)
  • func (i *IndentWriter) WriteString(s string) (n int, err error)
• type Node
• type StyledEdge
• type StyledNode

Types

type Edge

type Edge interface {
	attributes.Styleable
	attributes.Serializable
	// From returns the tail node this Edge is connected from
	From() Node
	// From returns the head node this Edge is connected to
	To() Node
	// Edge creates an Edge to a Node using the head node of this Edge as tail
	Edge(to Node) Edge
	// Edge creates an Edge with the provided attributes to a Node using the head
	// node of this Edge as tail
	EdgeWithAttributes(to Node, attributes attributes.Reader) Edge
	// EdgesTo returns all edges between the head Node of this Edge and the target
	// Node
	EdgesTo(to Node) []Edge
}

Edge is implemented by dot-compatible edge values

type Graph

type Graph interface {
	attributes.Identity
	attributes.Styleable
	fmt.Stringer

	// Root returns the root graph (i.e. the topmost, without a parent graph)
	Root() Graph
	// Type returns the graph type: directed, undirected or sub
	Type() attributes.GraphType
	// FindSubgraph returns the subgraph of this graph or from one of its parents
	FindSubgraph(id string) (Graph, bool)
	// Subgraph creates a subgraph of this graph
	Subgraph(options *GraphOptions) Graph
	// Node gets a node by id, or creates a new one if it doesn't exist
	Node(id string) Node
	// Edge creates a new edge between the two provided nodes
	Edge(n1, n2 Node) StyledEdge
	// Edge creates a new edge between the two provided nodes, and also set the
	// given attributes
	EdgeWithAttributes(n1, n2 Node, attributes attributes.Reader) StyledEdge
	// FindEdges gets all edges in the graph between the two provided nodes
	FindEdges(fromNode, toNode Node) (found []Edge)
	// FindNode gets a node by id
	FindNode(id string) (Node, bool)
	// IndentedWrite write the graph to a writer using TAB indentation
	IndentedWrite(w *IndentWriter)
	// VisitNodes runs the provided function on all nodes recursively
	VisitNodes(callback func(node Node) (done bool))
	// AddToSameRank adds the given nodes to the specified rank group, forcing
	// them to be rendered in the same row
	AddToSameRank(group string, nodes ...Node)
	// FindNodeByID return node by id
	FindNodeByID(id string) (foundNode Node, found bool)
	// FindNodes returns all nodes recursively
	FindNodes() (nodes []Node)
	// Write outputs the current graph state in dot language notation
	Write(w io.Writer)
}

Graph is implemented by dot-compatible graph values

func NewGraph

func NewGraph(options *GraphOptions) Graph

NewGraph return a new initialized Graph

if id is "-", a randonly generated ID will be set

type GraphOptions

type GraphOptions struct {

	// ID immutable id
	ID string
	// Type the graph type (directed, undirected or sub)
	Type attributes.GraphType
	// Cluster forbids the creation of multi-edges i.e.:
	//
	// on directed graphs, only one one edge between a given pair of head and tail nodes is allowed
	//
	// on undirected graphs, only one edge between the same two nodes is allowed
	Strict bool
	// Cluster denotes if the graph is the special cluster subgraph, whose name
	// starts with "cluster_"
	Cluster bool
	// NodeInitializer applies defaults to newly created nodes
	NodeInitializer func(Node)
	// EdgeInitializer applies defaults to newly created edges
	EdgeInitializer func(StyledEdge)
	// contains filtered or unexported fields
}

GraphOptions contains the parameters used for graph creation

type IDGenerator

type IDGenerator interface {
	String() string
	Stringn(length int) string
}

IDGenerator is implemented by pseudorandom generator values that output strings safe enough to be used within a single dot file

type IndentWriter

type IndentWriter struct {
	// contains filtered or unexported fields
}

IndentWriter io.Writer that indents content with the set level

func NewIndentWriter

func NewIndentWriter(w io.Writer) *IndentWriter

NewIndentWriter new instance of IndentWriter

func (*IndentWriter) BackIndent

func (i *IndentWriter) BackIndent()

BackIndent decrease the indent level

func (*IndentWriter) Indent

func (i *IndentWriter) Indent()

Indent increase the indent level and write a tab

func (*IndentWriter) IndentWhile

func (i *IndentWriter) IndentWhile(block func())

IndentWhile executes a block on an indented section

func (*IndentWriter) NewLine

func (i *IndentWriter) NewLine()

NewLine adds a line break and indent the new line

func (*IndentWriter) NewLineIndentWhile

func (i *IndentWriter) NewLineIndentWhile(block func())

NewLineIndentWhile executes a block on a indented and newline separared section

func (*IndentWriter) Write

func (i *IndentWriter) Write(data []byte) (n int, err error)

Write makes it an io.Writer

func (*IndentWriter) WriteString

func (i *IndentWriter) WriteString(s string) (n int, err error)

WriteString writes the given string

type Node

type Node interface {
	attributes.Identity
	attributes.Styleable
	attributes.Serializable
	// Edge creates an Edge to a Node
	Edge(to Node) Edge
	// EdgeWithAttributes creates an Edge with the provided attributes to a Node
	EdgeWithAttributes(to Node, attributes attributes.Reader) Edge
	// EdgesTo returns all edges between this Node and the target Node
	EdgesTo(to Node) []Edge
}

Node is implemented by dot-compatible node values

type StyledEdge

type StyledEdge interface {
	Edge
	// Solid sets the edge style to solid
	Solid() Edge
	// Solid sets the edge style to bold
	Bold() Edge
	// Solid sets the edge style to dashed
	Dashed() Edge
	// Solid sets the edge style to dotted
	Dotted() Edge
}

StyledEdge is implemented by dot-compatible edge values which have convenience styling methods

type StyledNode

type StyledNode interface {
	// Box sets the node style to box
	Box() Node
}

StyledNode is implemented by dot-compatible node values which have convenience styling methods