treeprint

The treeprint package allows you to build and render ASCII trees using a fluent API.

1. Initialize: Create a new tree using treeprint.New() (or treeprint.NewWithRoot(name) for a custom root).
2. Build Structure:
   • Use AddNode(name) to add a node at the current level.
   • Use AddBranch(name) to create a new level (a branch) and descend into it.
3. Render: Call .String() or .Bytes() on the root tree or a specific branch to get the ASCII representation of that subtree.

tree := treeprint.New()
// Add a branch and descend
branch := tree.AddBranch("folder")
// Add nodes inside that branch
branch.AddNode("file1").AddNode("file2")
// Print the whole tree
fmt.Println(tree.String())

To use treeprint in your Go project, install it using go get:

$ go get github.com/xlab/treeprint

You can control how treeprint processes struct fields using the tree struct tag. This affects FromStruct and FromStructWithMeta calls.

Supported tag behaviors:

• tree:"-": Skips the field entirely.
• tree:"new_name": Uses new_name as the node name instead of the actual field name.
• tree:"name,omitempty": Omits the field if it is considered empty (zero value).

type User struct {
    ID       int    `tree:"user_id"`       // Renames field in tree
    Password string `tree:"-"`             // Skips field
    Email    string `tree:"email,omitempty"` // Omits if empty
}

The treeprint library uses a hierarchical Node structure to build ASCII trees.

• Nodes vs Branches: A Node is a simple container for a Value and optional Meta. A Node becomes a branch when it contains child nodes. You can explicitly turn a leaf into a branch using the Branch() method.
• Metadata: Every node can carry a MetaValue. This is useful for attaching context (like file permissions, IDs, or status) to a node without polluting the primary Value.
• Traversal: The library supports searching (FindByValue, FindByMeta) and full traversal (VisitAll). VisitAll uses a breadth-first approach.
• Rendering: The rendering engine handles multi-line values by automatically calculating the necessary padding and link edges (│, ├──, └──) to maintain visual alignment.

You can build deeply nested structures by chaining AddBranch and AddNode calls. AddBranch moves the context one level deeper, while AddNode keeps the context at the current level.

func main() {
    // to add a custom root name use `treeprint.NewWithRoot()` instead
    tree := treeprint.New()

    // create a new branch in the root
    one := tree.AddBranch("one")

    // add some nodes
    one.AddNode("subnode1").AddNode("subnode2")

    // create a new sub-branch
    one.AddBranch("two").
        AddNode("subnode1").AddNode("subnode2"). // add some nodes
        AddBranch("three"). // add a new sub-branch
        AddNode("subnode1").AddNode("subnode2") // add some nodes too

    // add one more node that should surround the inner branch
    one.AddNode("subnode3")

    // add a new node to the root
    tree.AddNode("outernode")

    fmt.Println(tree.String())
}

If you need to attach metadata (like file sizes or permissions) to nodes or branches, use the following methods:

• AddMetaBranch(meta, name): Creates a branch that includes metadata in brackets, e.g., [ 204] bin.
• AddMetaNode(meta, name): Adds a leaf node with metadata, e.g., [122K] testtool.a.

func main() {
    // to add a custom root name use `treeprint.NewWithRoot()` instead
    tree := treeprint.New()

    tree.AddNode("Dockerfile")
    tree.AddNode("Makefile")
    tree.AddNode("aws.sh")
    tree.AddMetaBranch(" 204", "bin").
        AddNode("dbmaker").AddNode("someserver").AddNode("testtool")
    tree.AddMetaBranch(" 374", "deploy").
        AddNode("Makefile").AddNode("bootstrap.sh")
    tree.AddMetaNode("122K", "testtool.a")

    fmt.Println(tree.String())
}

The IndentSize variable controls the number of spaces used for each tree level. You can modify this globally to change the visual density of the tree output.

treeprint.IndentSize = 4

The Repr function is a convenience method that returns a string representation of a struct's values. It internally creates a new tree, performs a valueTree traversal, and returns the resulting string.

If the input is not a struct, it returns the standard fmt.Sprintf("%+v", val) representation.

str := treeprint.Repr(myStruct)
fmt.Println(str)

To visualize the tree in ASCII format, use the following methods:

• String(): Returns the ASCII representation of the tree as a string.
• Bytes(): Returns the ASCII representation of the tree as a []byte.

Metadata is rendered in brackets, e.g., ├── [meta] value.

fmt.Println(tree.String())

Use New() to create a new tree with a default root value of . or NewWithRoot(root Value) to specify a custom starting value for the root node.

Both functions return a Tree interface which allows for building and traversing the structure.

import "github.com/xlab/treeprint"

// Default root ('.')
tree := treeprint.New()

// Custom root
tree := treeprint.NewWithRoot("root-name")