Expand description
Simple textual output for tree-like structures.
This crate is another that will output a tree structure in text. Similar to the existing ascii_tree crate, however it is more flexible in its formatting options.
This crate provides a generic TreeNode so that items are stored in the
tree as long as the item implements std::fmt::Display. Commonly however a tree is generated
separately from the data it represents and so the simple StringTreeNode
allows construction of trees with string data throughout. The output trees are generated by writing
to an implementation of std::io::Write and helper functions are provided that write to, and
return, a String.
The goal is to make not only the writing of the tree easy but the construction should support not
only creating a tree as a stand-alone structure or as a representation of another structure. So,
where options may be provided these option structures implement Default and methods that do, and
do not, take options are provided. Additionally, implementations of From are provided to simplify
the creation of the tree itself.
§Example
The following example constructs a tree using the StringTreeNode type and a combination of
with_child_nodes and
with_children. This demonstrates the structure of
the tree well.
For a more complete example, see the included tls tree ls source.
use text_trees::StringTreeNode;
fn make_tree() -> StringTreeNode {
StringTreeNode::with_child_nodes(
"root".to_string(),
vec![
"Uncle".into(),
StringTreeNode::with_child_nodes(
"Parent".to_string(),
vec![
StringTreeNode::with_children(
"Child 1".to_string(),
vec!["Grand Child 1".into()].into_iter(),
),
StringTreeNode::with_child_nodes(
"Child 2".to_string(),
vec![StringTreeNode::with_child_nodes(
"Grand Child 2".to_string(),
vec![StringTreeNode::with_children(
"Great Grand Child 2".to_string(),
vec!["Great Great Grand Child 2".to_string()].into_iter(),
)]
.into_iter(),
)]
.into_iter(),
),
]
.into_iter(),
),
StringTreeNode::with_children(
"Aunt".to_string(),
vec!["Child 3".to_string()].into_iter(),
),
]
.into_iter(),
)
}The tree implements Display and therefore provides a to_string method. It also has a
to_string_with_format method that allows for customization of the output format. Finally, it
has two write methods that take implementations of std::io::Write and will serialize accordingly.
use text_trees::{FormatCharacters, TreeFormatting, TreeNode};
fn ascii_tree(tree: TreeNode<String>) {
let result = tree.to_string_with_format(
&TreeFormatting::dir_tree(FormatCharacters::ascii())
);
assert!(result.is_ok());
// ... do something else
}This results in a textual representation of the tree as follows.
root
+-- Uncle
+-- Parent
| +-- Child 1
| | '-- Grand Child 1
| '-- Child 2
| '-- Grand Child 2
| '-- Great Grand Child 2
| '-- Great Great Grand Child 2
'-- Aunt
'-- Child 3§Formatting Options
The format of the output tree is specified by the structure TreeFormatting
with a simple format available using the dir_tree
and dir_tree_left associated functions. You may
also override the default characters used to draw the tree lines with the
FormatCharacters structure. Two common sets can be made using the
ascii or
box_chars associated functions.
The following sections demonstrate how different combinations of values for the TreeFormatting and
FormtCharacters structures will affect the output.
root
+-- Uncle
+-- Parent
| +-- Child 1
| | '-- Grand Child 1
| '-- Child 2
| '-- Grand Child 2
| '-- Great Grand Child 2
| '-- Great Great Grand Child 2
'-- Aunt
'-- Child 3+ root
+--- Uncle
+--, Parent
| +--, Child 1
| | '--- Grand Child 1
| '--, Child 2
| '--, Grand Child 2
| '--, Great Grand Child 2
| '--- Great Great Grand Child 2
'--, Aunt
'--- Child 3root
├── Uncle
├── Parent
│ ├── Child 1
│ │ └── Grand Child 1
│ └── Child 2
│ └── Grand Child 2
│ └── Great Grand Child 2
│ └── Great Great Grand Child 2
└── Aunt
└── Child 3┌ root
├─── Uncle
├──┬ Parent
│ ├──┬ Child 1
│ │ └─── Grand Child 1
│ └──┬ Child 2
│ └──┬ Grand Child 2
│ └──┬ Great Grand Child 2
│ └─── Great Great Grand Child 2
└──┬ Aunt
└─── Child 3The following example overrides the basic values of the box character formatting characters to allow for visualization of the spaces generated. The horizontal spaces are shown as “#” and the label spacing is shown as “.”.
>> ┌..root
>> ├──────..Uncle
>> ├─────┬..Parent
>> │#####├─────┬..Child 1
>> │#####│#####└──────..Grand Child 1
>> │#####└─────┬..Child 2
>> │###########└─────┬..Grand Child 2
>> │#################└─────┬..Great Grand Child 2
>> │#######################└──────..Great Great Grand Child 2
>> └─────┬..Aunt
>> ######└──────..Child 3Structs§
- Format
Characters - Contains the set of characters, and counts, to use when line formatting.
- Tree
Formatting - This structure collects together all the formatting options that control how the tree is output.
- Tree
Node - Denotes a node in the tree, and any node can be the root of a tree when output. The generic
parameter
Tmust implementDisplaywhich is used to generate the label for each node in the output.
Enums§
- Anchor
Position - Denotes the position where the generated tree lines are anchored to the label text.
- Tree
Orientation - This denotes the orientation of the tree as it is written.
Type Aliases§
- String
Tree Node - A common type where the only data is the node’s label as a
String.