[−][src]Crate text_trees
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 also uses 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 formatting of the tree is
specified by the structure TreeFormatting
with default formatting provided by the
ascii_formatting
and box_char_formatting
functions.
Example
The following creates a StringTreeNode
using a combination of with_child_nodes
and
with_children
that demonstrates the structure of the tree well.
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 following sections demonstrate how different combinations of values for the TreeFormatting
and
FormtCharacters
structures will affect the output.
Option | Setting |
---|---|
Character Set | ASCII |
Orientation | TopDown |
Anchor Position | Below |
Prefix String | None |
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
Option | Setting |
---|---|
Character Set | ASCII |
Orientation | TopDown |
Anchor Position | Left |
Prefix String | None |
+ 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
Option | Setting |
---|---|
Character Set | Box char |
Orientation | TopDown |
Anchor Position | Below |
Prefix String | None |
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
Option | Setting |
---|---|
Character Set | Box char |
Orientation | TopDown |
Anchor Position | Left |
Prefix String | None |
┌ 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
The 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 ".".
Option | Setting |
---|---|
Character Set | Custom |
Orientation | TopDown |
Anchor Position | Left |
Prefix String | ">> " |
>> ┌..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
Structs
FormatCharacters | Contains the set of characters, and counts, to use when line formatting. |
TreeFormatting | This structure collects together all the formatting options that control how the tree is output. |
TreeNode | Denotes a node in the tree, and any node can be the root of a tree when output. The generic
parameter |
Enums
AnchorPosition | Denotes the position where the generated tree lines are anchored to the label text. |
TreeOrientation | This denotes the orientation of the tree as it is written. |
Type Definitions
StringTreeNode | A common type where the only data is the node's label as a |