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