Crate ptree[−][src]
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 builder::TreeBuilder; |
pub use item::TreeItem; |
pub use output::print_tree; |
pub use output::print_tree_with; |
pub use output::write_tree; |
pub use output::write_tree_with; |
pub use print_config::IndentChars; |
pub use print_config::PrintConfig; |
pub use style::Color; |
pub use style::Style; |
Modules
builder | Contains the |
graph | Implementation of |
item | Contains the |
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 |