[−][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 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.

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.