[−][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 `T` must implement `Display` which is used to generate the label for each node in the output.

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 String.