Documentation
¶
Overview ¶
Package tree is used to produce textual tree graphs. The graph can be produced using ASCII, Unicode or custom characters:
|- Start ├─ Start |- Middle ├─ Middle | |- Second Branch │ ├─ Second Branch | `- With Text │ └─ With Text `- End └─ End
The zero value of a Tree is ready to be populated by appending text and branch nodes using the Append and Branch methods. Once all nodes have been added the tree can be rendered by calling the Render method.
The maximum depth and breadth of the tree is very large, usually only limited by the memory available.
Example ¶
An example of using the tree package to produce the graphs in the package description.
package main
import (
"fmt"
"code.wolfmud.org/WolfMUD.git/text/tree"
)
func main() {
graph := tree.Tree{}
graph.Append("Start").Append("Middle").Branch().Append("Second Branch").Append("With Text")
graph.Append("End")
fmt.Println(graph.Render())
graph.Style = tree.StyleUnicode
fmt.Println(graph.Render())
}
Output: |- Start |- Middle | |- Second Branch | `- With Text `- End ├─ Start ├─ Middle │ ├─ Second Branch │ └─ With Text └─ End
Example (Building) ¶
A longer, contrived example of programmatically building a tree graph.
package main
import (
"fmt"
"code.wolfmud.org/WolfMUD.git/text/tree"
)
func main() {
bibliography := []struct {
title string
authors []string
publisher string
published string
pages int
ISBN10 string
}{
{
"The Go Programming Language",
[]string{"Alan A. A. Donovan", "Brian W. Kernighan"},
"Addison-Wesley Professional", "16 November 2015", 398, "9780134190440",
},
{
"Programming in Go",
[]string{"Mark Summerfield"},
"Addison-Wesley", "30 April 2012", 496, "9780132764094",
},
{
"Unix Text Processing",
[]string{"Dale Dougherty", "Tim O'Reilly"},
"Hayden Books", "1987", 665, "0672462915",
},
}
graph := tree.Tree{}
books := graph.Append("Book Catalogue").Branch()
for _, info := range bibliography {
books = books.Append(info.title)
book := books.Branch()
auth := book.Append("Author(s):").Branch()
book.Append("Publisher: %s", info.publisher)
book.Append("Published: %s", info.published)
book.Append("Pages : %d", info.pages)
book.Append("ISBN-10 : %s", info.ISBN10)
for _, author := range info.authors {
auth.Append(author)
}
}
graph.Style = tree.StyleUnicode
fmt.Println(graph.Render())
}
Output: └─ Book Catalogue ├─ The Go Programming Language │ ├─ Author(s): │ │ ├─ Alan A. A. Donovan │ │ └─ Brian W. Kernighan │ ├─ Publisher: Addison-Wesley Professional │ ├─ Published: 16 November 2015 │ ├─ Pages : 398 │ └─ ISBN-10 : 9780134190440 ├─ Programming in Go │ ├─ Author(s): │ │ └─ Mark Summerfield │ ├─ Publisher: Addison-Wesley │ ├─ Published: 30 April 2012 │ ├─ Pages : 496 │ └─ ISBN-10 : 9780132764094 └─ Unix Text Processing ├─ Author(s): │ ├─ Dale Dougherty │ └─ Tim O'Reilly ├─ Publisher: Hayden Books ├─ Published: 1987 ├─ Pages : 665 └─ ISBN-10 : 0672462915
Index ¶
Examples ¶
Constants ¶
const ( StyleASCII = "|-|`" StyleUnicode = "│─├└" StyleUnicodeBold = "┃━┣┗" )
Predefined style constants for rendering the tree output. The Tree.Style field can be set to one of the predefined style strings or a custom string of the form "vhjes" where:
v - vertical branch h - horizontal branch j - join between a vertical and horizontal branch e - the elbow at the end of a branch s - character for indentation and gaps between branches
For example, the following is rendered with the StyleUnicode "│─├└" string:
├─ jhs │ vss └─ ehs
If a custom style string is less than 5 characters long then spaces ' ' (ASCII 0x20) will be used for the missing characters. If Tree.Style is the default empty string then StyleASCII is used.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Node ¶
type Node struct {
// contains filtered or unexported fields
}
Node is used to represent the tree like structure of text and branch nodes. A Node may point to the next text node on the branch and/or to a different branch node.
A new text node can be appended to a branch by calling the Append method. A new branch can be added using the Branch method.
func (*Node) Append ¶
Append adds a new text node to the end of the current branch pointed to by the receiver and returns the new node. The passed format and args parameters are processed by the fmt.Sprintf function.
If the text passed to Append evaluates to the empty string no new text node will be created and the receiver node will be returned.
The returned node may be saved to bookmark a position in the tree. The saved node can then be used to add additional nodes and/or branches.
Example ¶
A simple example of appending text nodes to a graph.
package main
import (
"fmt"
"code.wolfmud.org/WolfMUD.git/text/tree"
)
func main() {
graph := tree.Tree{}
graph.Style = tree.StyleUnicode
graph.Append("First").Append("Second")
fmt.Println(graph.Render())
}
Output: ├─ First └─ Second
func (*Node) Branch ¶
Branch adds a new branch node to the receiver node and returns the new node. If the receiver node already has a branch from it the branch is followed to its end, until a node without a branch is found, and the new branch is then made at the end.
A new branch node will not be added to an empty branch - one that has not had any text nodes added to it. In this case Branch will return the empty branch node found.
The returned Node may be saved to bookmark a position in the tree. The saved Node can then be used to add additional nodes and/or branches.
Example ¶
A simple example of appending text nodes and a branch to a graph.
package main
import (
"fmt"
"code.wolfmud.org/WolfMUD.git/text/tree"
)
func main() {
graph := tree.Tree{}
graph.Style = tree.StyleUnicode
graph.Append("First").Branch().Append("Second")
fmt.Println(graph.Render())
}
Output: └─ First └─ Second
type Tree ¶
type Tree struct {
// Width is the maximum width of rendered graph, excluding indentation. Text
// nodes that exceed the width will be wrapped on to continuation lines. If
// set to the default of 0 no wrapping occurs. Minimum width should be 3 *
// max tree depth + a reasonable amount for text. If there is no way to
// reasonably fit the text to the graph it will be displayed as is,
// regardless of the Width setting. If negative will be set to 0 when the
// graph is rendered.
Width int
// Indent is the amount to indent the rendered graph from the left hand side.
// The Indent is independent of and not included in the Width. If negative
// will be set to 0 when the graph is rendered.
Indent int
// Offset is the amount to offset continuation lines with respect to the
// initial line. If set to the default of 0 then continuation lines will not
// have branches drawn immediately next to them, but underneath. If negative
// will be set to 0 when the graph is rendered.
Offset int
// Runes to render graph. See Style* constants for details and predefined
// styles. If set to the default empty string it will be set to StyleASCII
// when the graph is rendered.
Style string
// contains filtered or unexported fields
}
Tree is used to hold working data and configuration settings for a tree graph. The zero value of a Tree is ready to use. At least one text or branch node needs to be added to the Tree via Tree.Append or Tree.Branch initially in order to obtain a tree.Node instance. All other text and branch nodes can then be added using Node.Append or Node.Branch methods on the returned Node.
Example (Indent) ¶
An example of using Tree.Indent when rendering. A custom style based on StyleUnicode has been used to make the whitespace visible as "·". The Indent controls the indentation of the graph from the left hand side. The Indent is independent of the tree.Width of the graph. The total width of the graph would therefore be Tree.Indent + Tree.Width when rendered.
package main
import (
"fmt"
"code.wolfmud.org/WolfMUD.git/text/tree"
)
func main() {
graph := tree.Tree{}
graph.Width = 30
graph.Style = tree.StyleUnicode + "·"
node := graph.Append("This is some short example text.")
node = node.Branch()
node = node.Append("This is some short example text.")
graph.Indent = 0
fmt.Println(graph.Render())
graph.Indent = 2
fmt.Println(graph.Render())
graph.Indent = 4
fmt.Println(graph.Render())
}
Output: └─·This is some short example ···text. ···└─·This is some short ······example text. ··└─·This is some short example ·····text. ·····└─·This is some short ········example text. ····└─·This is some short example ·······text. ·······└─·This is some short ··········example text.
Example (Offset) ¶
An example of using Tree.Offset when rendering. A custom style based on StyleUnicode has been used to make the whitespace visible as "·". The offset controls the amount of padding applied to continuation lines with respect to the initial line of a text node. Note that if the offset is zero and there is a branch node the branch will only be drawn after the continuation lines and not next to them.
package main
import (
"fmt"
"code.wolfmud.org/WolfMUD.git/text/tree"
)
func main() {
graph := tree.Tree{}
graph.Width = 30
graph.Style = tree.StyleUnicode + "·"
node := graph.Append("This is some short example text.")
node = node.Branch()
node = node.Append("This is some short example text.")
graph.Offset = 0
fmt.Println(graph.Render())
graph.Offset = 2
fmt.Println(graph.Render())
graph.Offset = 8
fmt.Println(graph.Render())
}
Output: └─·This is some short example ···text. ···└─·This is some short ······example text. └─·This is some short example ···│·text. ···└─·This is some short ········example text. └─·This is some short example ···│·······text. ···└─·This is some short ··············example text.
Example (Width) ¶
An example of using Tree.Width when rendering.
package main
import (
"fmt"
"code.wolfmud.org/WolfMUD.git/text/tree"
)
func main() {
graph := tree.Tree{}
graph.Style = tree.StyleUnicode
node := graph.Append("This is some short example text.")
node = node.Branch()
node = node.Append("This is some short example text.")
graph.Width = 40
fmt.Println(graph.Render())
graph.Width = 30
fmt.Println(graph.Render())
graph.Width = 20
fmt.Println(graph.Render())
}
Output: └─ This is some short example text. └─ This is some short example text. └─ This is some short example text. └─ This is some short example text. └─ This is some short example text. └─ This is some short example text.
func (*Tree) Append ¶
Append adds a new text node to the end of the root branch and returns the new Node. The passed format and args parameters are processed by the fmt.Sprintf function.
If the text passed to Append evaluates to the empty string no new text node will be created and the receiver node will be returned. However, if there are no other text nodes on the root branch this is the equivalent of calling the Tree.Branch method, which has no visible effect on the resulting graph but allows for a Node to be returned.
func (*Tree) Branch ¶
Branch adds a new branch node to the receiver node and returns the new node. If the receiver node already has a branch from it the branch is followed to its end, until a node without a branch is found, and the new branch is then made at the end.
func (*Tree) Render ¶
Render processes the current tree structure and returns the resulting graph as a string. The same Tree may be rendered multiple times using different settings. See the Tree type for configurable settings.
Example (Prefix) ¶
An example of using Tree.Offset when rendering with a fixed length prefix. In this case the prefix is a memory address. The tree.Offset value of 15 is derived from 12 positions for the address plus three positions for the space, hyphen and space that follow it.
package main
import (
"fmt"
"code.wolfmud.org/WolfMUD.git/text/tree"
)
func main() {
graph := tree.Tree{}
graph.Width = 40
graph.Style = tree.StyleUnicode
node := graph.Append("0xc000108000 - This is some short example text.")
node = node.Append("0xc000108010 - This is some short example text.")
node = node.Branch()
node = node.Append("0xc000108020 - This is some short example text.")
node = node.Append("0xc000108020 - This is some short example text.")
node = node.Branch()
node = node.Append("0xc000108030 - This is some short example text.")
graph.Offset = 15
fmt.Println(graph.Render())
}
Output: ├─ 0xc000108000 - This is some short │ example text. └─ 0xc000108010 - This is some short │ example text. ├─ 0xc000108020 - This is some short │ example text. └─ 0xc000108020 - This is some short │ example text. └─ 0xc000108030 - This is some short example text.
Source Files