crates/debug_tree/doc/readme_template.adoc

: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[]
----