treedrawer

treedrawer is a Go module for drawing trees on the terminal like the one below.

╭─╮                                    
                                    │9│                                    
                                    ╰┬╯                                    
                   ╭─────────────────┴─────────────┬─────────────┬───┬───╮ 
        ╭──────────┴─────────╮                    ╭┴╮           ╭┴╮ ╭┴╮ ╭┴╮
        │I can handle strings│                    │1│           │2│ │3│ │4│
        ╰──────────┬─────────╯                    ╰┬╯           ╰─╯ ╰─╯ ╰─╯
                   │                      ╭─────┬──┴─────╮                 
  ╭────────────────┴────────────────╮   ╭─┴─╮ ╭─┴╮  ╭────┴───╮             
  │with as many children as you want│   │124│ │13│  │a string│             
  ╰────────────────┬────────────────╯   ╰───╯ ╰──╯  ╰────────╯             
                   │                                                       
   ╭───────────────┴───────────────╮                                       
   │with as many layers as you want│                                       
   ╰───────────────┬───────────────╯                                       
                   │                                                       
 ╭─────────────────┴─────────────────╮                                     
 │actually I can handle everything...│                                     
 ╰─────────────────┬─────────────────╯                                     
                   │                                                       
╭──────────────────┴──────────────────╮                                    
│...that satisfies NodeValue interface│                                    
╰─────────────────────────────────────╯

Import

import "github.com/m1gwings/treedrawer/tree"

Quick start

# Assume the following code is in example.go file
$ cat example.go

package main
import ( 	"fmt"
"github.com/m1gwings/treedrawer/tree" )
func main() { 	// Creating a tree with 5 as the value of the root node 	t := tree.NewTree(tree.NodeInt64(5))
// Adding children 	t.AddChild(tree.NodeString("adding a string")) 	t.AddChild(tree.NodeInt64(4)) 	t.AddChild(tree.NodeInt64(3))
// Drawing the tree 	fmt.Println(t) }

$ go run example.go

╭─╮                       │5│                       ╰┬╯                    ╭───┴──────┬───╮  ╭───────┴───────╮ ╭┴╮ ╭┴╮ │adding a string│ │4│ │3│ ╰───────────────╯ ╰─╯ ╰─╯

Usage

Building the tree

Creating the tree with 1 as the value of the root node

t := tree.NewTree(tree.NodeInt64(1))

Adding the first child to t with value 2

t.AddChild(tree.NodeInt64(2))

Adding more children

t.AddChild(tree.NodeInt64(3)) t.AddChild(tree.NodeInt64(4)) t.AddChild(tree.NodeInt64(5))

We've just built the tree below

╭─╮             │1│             ╰┬╯        ╭───┬─┴─┬───╮  ╭┴╮ ╭┴╮ ╭┴╮ ╭┴╮ │2│ │3│ │4│ │5│ ╰─╯ ╰─╯ ╰─╯ ╰─╯

Navigating the tree

Navigating to first child of t (we're still working with the tree above)

// This method returns an error if the i-th child does not exist // in this case i = 0 tFirstChild, err := t.Child(0)

Adding children to first child

tFirstChild.AddChild(tree.NodeInt64(6)) tFirstChild.AddChild(tree.NodeInt64(7)) tFirstChild.AddChild(tree.NodeInt64(8))

Going back to parent

// ok would be equal to false if tFirstChild were the root of the tree tFirstChildParent, ok := tFirstChild.Parent()

_ := tFirstChildParent == t // true, we have gone back to the root of the tree

Navigating to third child of t

tThirdChild, err := t.Child(2)

Adding a string child to third child

tThirdChild.AddChild(tree.NodeString("I'm a string"))

Getting a pointer to the root of the tree

tRoot := tThirdChild.Root()

_ := tRoot == t // true

Now the tree looks like this

╭─╮                                 │1│                                 ╰┬╯                      ╭───────┬───┴─────┬─────────╮      ╭┴╮     ╭┴╮       ╭┴╮       ╭┴╮     │2│     │3│       │4│       │5│     ╰┬╯     ╰─╯       ╰┬╯       ╰─╯  ╭───┼───╮             │            ╭┴╮ ╭┴╮ ╭┴╮     ╭──────┴─────╮      │6│ │7│ │8│     │I'm a string│      ╰─╯ ╰─╯ ╰─╯     ╰────────────╯

Getting and setting values from the tree

Getting the value of a node

v := t.Val()

Setting the value of a node

t.SetVal(tree.NodeInt64(3))

Drawing the tree

*tree.Tree implements the Stringer interface, just use package fmt to draw trees to terminal

fmt.Println(t)

Implementing NodeValue interface

The tree can handle every type that satisfies the NodeValue interface

// NodeValue is the interface that wraps the Draw method. // // The Draw method allows to convert data into its unicode canvas representation. // With the Draw method you can control how your data is going to appear on the tree. type NodeValue interface { 	Draw() *drawer.Drawer }

The wrappers for built-in are defined inside the package treedrawer/tree like tree.NodeInt64 or tree.NodeString used above, so you don't need to worry about them. Continue reading this section if you want to draw custom types instead.

• Importing treedrawer/drawer

First of all we need access to the drawer.Drawer type. Just import the following

import "github.com/m1gwings/treedrawer/drawer"

drawer.Drawer under the hood is just a 2D slice of runes on which you can draw a rune specifying its coordinates or another entire drawer.Drawer specifying the coordinates of its upper-left corner.

• Defining a custom type

type NodeAsterisk struct { 	Width, Height int }

NodeAsterisk represents a rectangle of width NodeAsterisk.Width and height NodeAsterisk.Height.

• Implementing NodeAsterisk.Draw() in order to satisfy NodeValue interface

func (nA NodeAsterisk) Draw() *drawer.Drawer {
	d, err := drawer.NewDrawer(nA.Width, nA.Height)
	if err != nil {
		log.Fatal(err)
	}
	for x := 0; x < nA.Width; x++ {
		for y := 0; y < nA.Height; y++ {
			err = d.DrawRune('*', x, y)
			if err != nil {
				log.Fatal(err)
			}
		}
	}
	return d
}

The method allocates a new drawer with width nA.Width and height nA.Height, then loops over each cell and fills it with an '*'. You can implement this method to represent your data as you want.

• Adding instances of NodeAsterisk to a tree

t := tree.NewTree(NodeAsterisk{3, 4})
t.AddChild(NodeAsterisk{1, 2})
t.AddChild(NodeAsterisk{3, 3})

• Drawing the tree

fmt.Println(t)

╭───╮  
  │*│  
  │*│  
  │*│  
  │*│  
  ╰─┬─╯  
 ╭──┴─╮  
╭┴╮ ╭─┴─╮
││ │**│
││ │**│
╰─╯ │*│
    ╰───╯

Examples

You can find these examples inside the ./examples folder

HTML tree

# Assume the following code is in htmltree.go file
$ cat htmltree.go

package main
import ( 	"fmt" 	"log" 	"strings"
"github.com/m1gwings/treedrawer/tree" 	"golang.org/x/net/html" )
func main() { 	s := <p>Links:</p><ul><li><a href="foo">Foo</a><li><a href="/bar/baz">BarBaz</a></ul> 	doc, err := html.Parse(strings.NewReader(s)) 	if err != nil { 		log.Fatal(err) 	}
t := tree.NewTree(tree.NodeString(""))
var f func(html.Node, tree.Tree) 	f = func(n html.Node, t tree.Tree) { 		t.SetVal(tree.NodeString(n.Data)) 		for c := n.FirstChild; c != nil; c = c.NextSibling { 			tChild := t.AddChild(tree.NodeString("")) 			f(c, tChild) 		} 	} 	// Starting from FirstChild because the DocumentRoot has an empty Val 	f(doc.FirstChild, t)
fmt.Println(t) }

$ go run htmltree.go

╭────╮                            │html│                            ╰──┬─╯                  ╭────────────┴───╮             ╭──┴─╮           ╭──┴─╮           │head│           │body│           ╰────╯           ╰──┬─╯                       ╭───────┴────╮                   ╭┴╮         ╭─┴╮                  │p│         │ul│                  ╰┬╯         ╰─┬╯                   │       ╭────┴──╮             ╭───┴──╮  ╭─┴╮    ╭─┴╮            │Links:│  │li│    │li│            ╰──────╯  ╰─┬╯    ╰─┬╯                        │       │                        ╭┴╮     ╭┴╮                       │a│     │a│                       ╰┬╯     ╰┬╯                        │       │                       ╭─┴─╮ ╭───┴──╮                    │Foo│ │BarBaz│                    ╰───╯ ╰──────╯

File system tree

# Assume the following code is in filesystemtree.go file $ cat filesystemtree.go

package main

import ( 	"fmt" 	"log" 	"strings"
"github.com/m1gwings/treedrawer/tree" 	"golang.org/x/net/html" )
func main() { 	s := <p>Links:</p><ul><li><a href="foo">Foo</a><li><a href="/bar/baz">BarBaz</a></ul> 	doc, err := html.Parse(strings.NewReader(s)) 	if err != nil { 		log.Fatal(err) 	}
t := tree.NewTree(tree.NodeString(""))
var f func(html.Node, tree.Tree) 	f = func(n html.Node, t tree.Tree) { 		t.SetVal(tree.NodeString(n.Data)) 		for c := n.FirstChild; c != nil; c = c.NextSibling { 			tChild := t.AddChild(tree.NodeString("")) 			f(c, tChild) 		} 	} 	// Starting from FirstChild because the DocumentRoot has an empty Val 	f(doc.FirstChild, t)
fmt.Println(t) }

$ go run filesystemtree.go

╭──────────╮                                                                                                                                                                  │treedrawer│                                                                                                                                                                  ╰─────┬────╯                                                                                       ╭──────────────────────┬─────────────────────┬───────────────────┬───────────────┴───┬───────────────────────────────────────────╮                                       ╭────┴────╮            ╭────┴───╮             ╭───┴───╮           ╭───┴──╮            ╭───┴──╮                                     ╭──┴─╮                                     │README.md│            │examples│             │LICENSE│           │drawer│            │go.sum│                                     │tree│                                     ╰─────────╯            ╰────┬───╯             ╰───────╯           ╰───┬──╯            ╰──────╯                                     ╰──┬─╯                                                       ╭─────────┴──────╮                            ╭─────┴────────╮                         ╭─────────────────┬──────────┴─┬────────────┬───────────────╮                    ╭─────┴─────╮ ╭────────┴────────╮           ╭───────┴──────╮  ╭────┴────╮           ╭────────┴───────╮  ╭──────┴─────╮  ╭───┴───╮ ╭──────┴──────╮ ╭──────┴─────╮              │htmltree.go│ │filesystemtree.go│           │drawertest.go│  │drawer.go│           │examplestest.go│  │stringify.go│  │tree.go│ │nodevalues.go│ │tree_test.go│              ╰───────────╯ ╰─────────────────╯           ╰──────────────╯  ╰─────────╯           ╰────────────────╯  ╰────────────╯  ╰───────╯ ╰─────────────╯ ╰────────────╯

Benchmarks

You can find the code used for the benchmark inside ./tree/stringify_test.go In order to profile the module we first create trees with l layers and c children for each node, except leaf nodes. Each node has a tree.NodeString("*") as value. For example the tree below has 3 layers and 2 children for each node.

╭─╮             │*│             ╰┬╯          ╭───┴───╮      ╭┴╮     ╭┴╮     ││     ││     ╰┬╯     ╰┬╯    ╭─┴─╮   ╭─┴─╮  ╭┴╮ ╭┴╮ ╭┴╮ ╭┴╮ ││ ││ ││ ││ ╰─╯ ╰─╯ ╰─╯ ╰─╯

In our benchmark function we print to /dev/null a tree with the specified l and c parameter. Name|Iterations|Time|Children per Node|Layers|Total of Nodes|Memory|Allocations -|-|-|-|-|-|-|-| BenchmarkDrawing3L3C-12|10000|100063 ns/op|3.00 children|3.00 layers|13.0 nodes|135576 B/op|722 allocs/op BenchmarkDrawing100L1C-12|382|3096956 ns/op|1.00 children|100 layers|100 nodes|3727628 B/op|23297 allocs/op BenchmarkDrawing6L3C-12|9|119789317 ns/op|3.00 children|6.00 layers|364 nodes|366549320 B/op|33606 allocs/op BenchmarkDrawing1000L1C-12|7|161607620 ns/op|1.00 children|1000 layers|1000 nodes|373048737 B/op|2033004 allocs/op BenchmarkDrawing10L2C-12|2|733952840 ns/op|2.00 children|10.0 layers|1023 nodes|4375790984 B/op|114909 allocs/op BenchmarkDrawing11L2C-12|1|3661883138 ns/op|2.00 children|11.0 layers|2047 nodes|20557038432 B/op|249910 allocs/op BenchmarkDrawing8L3C-12|1|8550947886 ns/op|3.00 children|8.00 layers|3280 nodes|50574173168 B/op|387828 allocs/op BenchmarkDrawing12L2C-12|1|13559015034 ns/op|2.00 children|12.0 layers|4095 nodes|96166288000 B/op|538283 allocs/op

Generated using go version go1.15.1 linux/amd64

Known issues 🐛

• Emojis are larger than normal characters

fmt.Println(tree.NewTree(tree.NodeString("emojis are buggy 🤪")))

╭──────────────────╮  │emojis are buggy 🤪│  ╰──────────────────╯