Revision control
Copy as Markdown
Other Tools
: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[]
----