Crate ptree

Pretty-print tree-like structures

Basic usage

// Build a tree using a TreeBuilder
let tree = TreeBuilder::new("tree".to_string())
    .begin_child("branch".to_string())
        .add_empty_child("leaf".to_string())
    .end_child()
    .add_empty_child("empty branch".to_string())
    .build();

// Print out the tree using default formatting
print_tree(&tree)?;

Output configuration

Ptree allows user configuration of the output format. Thus any program using the library can be configured globaly, providing a consistent user experience.

Output formatting is controlled by a user configuration file or by environment variables.

# <config_dir>/ptree.toml

indent = 4

[branch]
foreground = red
dimmed = true

[leaf]
bold = true

The configuration file resides in the platform-specific user configuration directory, as returned by config_dir. It can be in TOML, YAML, INI or JSON format, provided the file stem is ptree. A custom configuration file can be specified by setting the PTREE_CONFIG environment variable to the full path of the file.

Individual configuration parameters can also be overriden using environment variables.

PTREE_INDENT=3 PTREE_BRANCH_BACKGROUND=yellow <command>

See PrintConfig for the list of all configuration options.

Advanced usage

Implementing the TreeItem trait

Rather than construct a new tree, one can implement the TreeItem trait for a custom data structure.

#[derive(Clone)]
struct MyCustomTree {}

impl TreeItem for MyCustomTree {
    type Child = Self;
    fn write_self<W: io::Write>(&self, f: &mut W, style: &Style) -> io::Result<()> {
        write!(f, "{}", style.paint("My custom tree"))
    }
    fn children(&self) -> Cow<[Self::Child]> {
        Cow::from(vec![])
    }
}

// Build my custom tree structure
let tree = MyCustomTree {};

// Print out the tree using default formatting
print_tree(&tree)?;

Custom output formatting

The print_tree function loads the user configuration to control output formatting. If you want to override this, you can create your own PrintConfig and use the print_tree_with function.

// Build a tree using a TreeBuilder
let tree = TreeBuilder::new("tree".to_string())
    .add_empty_child("empty branch".to_string())
    .build();

// Set up the print configuration
let config = {
    let mut config = PrintConfig::from_env();
    config.branch = Style {
        foreground: Some(Color::Red),
        background: Some(Color::Yellow),
        dimmed: true,
        ..Style::default()
    };
    config.leaf = Style {
        bold: true,
        ..Style::default()
    };
    config.characters = UTF_CHARS_BOLD.into();
    config.indent = 4;
    config
};

// Print out the tree using custom formatting
print_tree_with(&tree, &config)?;

Write to a file

To write a tree to a file rather than to standard output, use write_tree or write_tree_with.

Unless PrintConfig::styled is set to Always, these two functions will not use ANSI coloring and styling for the output text.

// Build a tree using a TreeBuilder
let tree = TreeBuilder::new("tree".to_string())
    .add_empty_child("empty branch".to_string())
    .build();

// Open a file for writing
let file_name = "tree.txt";
let file = File::create(&file_name)?;

// Write out the tree to the file
write_tree(&tree, file)?;

Re-exports

pub use crate::builder::TreeBuilder;

pub use crate::item::TreeItem;

pub use crate::output::print_tree;

pub use crate::output::print_tree_with;

pub use crate::output::write_tree;

pub use crate::output::write_tree_with;

pub use crate::print_config::IndentChars;

pub use crate::print_config::PrintConfig;

pub use crate::style::Color;

pub use crate::style::Style;

Modules

builder

Contains the TreeBuilder structure, useful for manually constructing trees

graph

Implementation of TreeItem for petgraph::Graph

item

Contains the TreeItem trait

output

Functions for printing trees to standard output or to custom writers

print_config

Structures to control the output formatting

style

Structures to control terminal colors and styles

value

Implementation of TreeItem for serde_value::Value, allowing easy printing of deserialized structures from a variety of formats.