127 lines
2.6 KiB
Text
127 lines
2.6 KiB
Text
: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[]
|
|
----
|