1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
|
:examples: ../examples/
= Debug Tree
This library allows you to build a tree one element at a time and output it as a pretty string.
The tree can easily be output to a `String`, `stdout` or a file.
This is particularly convenient for generating clean output from nested and recursive functions.
:toc:
== Recursive Fibonacci Example
Using the `add_branch!()` macro at the start of the `factors()` function, you can generate an entire call tree, with minimal effort.
[source,rust]
----
include::{examples}fibonacci.rs[]
----
----
include::{examples}out/fibonacci.txt[]
----
== Overview
* Add a branch
- `add_branch!("Hello, {}", "World")`
- The branch will exit at the end of the current block
* Add a leaf
- `add_leaf!("I am a {}", "leaf")`
- Added to the current scoped branch
* Print a tree, or write it to file at the end of a block
- `defer_print!()`
- `defer_write!("filename.txt")`
- The tree will be empty after these calls
- To prevent clearing, use `defer_peek_print!` and `defer_peek_write!`
* Get the trees pretty-string
-
* Handle multiple trees using named trees
- `add_branch_to!("A", "I'm a branch on tree 'A'")`
- `add_leaf_to!("A", "I'm a leaf on tree 'A'")`
- `defer_print!("A")`
- `defer_write!("A", "filename.txt")`
* Get a named tree
- `tree("TREE_NAME")`
* Retrieve the pretty-string from a tree
- `tree("TREE_NAME").string()`
* Usage across threads
- `default_tree()` is local to each thread
- Named trees are shared between threads
== More Examples
=== Multiple Tagged Trees
If you need multiple, separated trees you can use a name tag.
[source,rust]
----
include::{examples}multiple_trees.rs[]
----
----
include::{examples}out/multiple_trees_A.txt[]
----
----
include::{examples}out/multiple_trees_B.txt[]
----
=== Nested Functions
Branches also make nested function calls a lot easier to follow.
[source,rust]
----
include::{examples}nested.rs[]
----
----
include::{examples}out/nested.txt[]
----
=== Line Breaks
Newlines in multi-line strings are automatically indented.
[source,rust]
----
include::{examples}multi_line.rs[]
----
----
include::{examples}out/multi_line.txt[]
----
=== Panics
Even if there is a panic, the tree is not lost!
The `defer_` functions were introduced to allow the tree
to be printed our written to file in the case of a `panic!` or early return.
[source,rust]
----
include::{examples}panic.rs[]
----
----
include::{examples}out/panic.txt[]
----
=== Without Macros
If you prefer not using macros, you can construct `TreeBuilder`s manually.
[source,rust]
----
include::{examples}no_macros.rs[]
----
----
include::{examples}out/no_macros.txt[]
----
|
