Crate ptree

Expand description

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.


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)?;