lipgloss_tree/
lib.rs

1//! # lipgloss-tree
2//!
3//! A Rust library for rendering styled tree structures in terminal applications.
4//! This crate is part of the lipgloss-rs ecosystem, providing a 1:1 Rust port
5//! of the Go [lipgloss/tree] library from [Charm].
6//!
7//! [lipgloss/tree]: https://github.com/charmbracelet/lipgloss/tree/main/tree
8//! [Charm]: https://charm.sh
9//!
10//! ## Features
11//!
12//! - **Rich tree rendering** with customizable branch characters (├──, └──, etc.)
13//! - **Custom enumerators** supporting Roman numerals, bullet points, or any custom format
14//! - **Advanced styling** with colors, padding, borders, and text formatting
15//! - **Multi-line content** support with proper indentation
16//! - **Style inheritance** from parent to child nodes
17//! - **Alignment control** for mixed-width enumerators
18//!
19//! ## Quick Start
20//!
21//! ```rust
22//! use lipgloss_tree::Tree;
23//!
24//! let tree = Tree::new()
25//!     .root("My Project")
26//!     .child(vec![
27//!         "src/".into(),
28//!         "README.md".into(),
29//!         Tree::new()
30//!             .root("docs/")
31//!             .child(vec!["guide.md".into(), "api.md".into()])
32//!             .into(),
33//!     ]);
34//!
35//! println!("{}", tree);
36//! ```
37//!
38//! This produces:
39//!
40//! ```text
41//! My Project
42//! ├── src/
43//! ├── README.md
44//! ├── docs/
45//! │   ├── guide.md
46//! │   └── api.md
47//! ```
48//!
49//! ## Advanced Usage
50//!
51//! ### Custom Styling
52//!
53//! ```rust
54//! use lipgloss::{Style, Color};
55//! use lipgloss_tree::{Tree, Renderer};
56//! use lipgloss_tree::renderer::TreeStyle;
57//!
58//! let custom_style = TreeStyle {
59//!     enumerator_func: |_, _| Style::new().foreground(Color::from("blue")),
60//!     item_func: |_, _| Style::new().foreground(Color::from("green")),
61//!     root: Style::new().bold(true).foreground(Color::from("magenta")),
62//!     ..TreeStyle::default()
63//! };
64//!
65//! let tree = Tree::new()
66//!     .root("Styled Tree")
67//!     .child(vec!["Item 1".into(), "Item 2".into()]);
68//!
69//! let renderer = Renderer::new().style(custom_style);
70//! // Use renderer.render(&tree, true, "") for custom rendering
71//! ```
72//!
73//! ### Custom Enumerators
74//!
75//! ```rust
76//! use lipgloss_tree::Tree;
77//!
78//! let tree = Tree::new()
79//!     .root("Roman List")
80//!     .child(vec!["First".into(), "Second".into(), "Third".into()])
81//!     .enumerator(|_, i| match i + 1 {
82//!         1 => "I".to_string(),
83//!         2 => "II".to_string(),  
84//!         3 => "III".to_string(),
85//!         n => n.to_string(),
86//!     });
87//! ```
88//!
89//! ## Architecture
90//!
91//! The crate is organized into three main modules:
92//!
93//! - [`children`] - Node and tree data structures
94//! - [`enumerator`] - Functions for generating branch characters and indentation  
95//! - [`renderer`] - Core rendering engine with styling support
96
97#![warn(missing_docs)]
98
99/// Node and tree data structures for building hierarchical content.
100pub mod children;
101/// Functions for generating branch characters and indentation strings.
102pub mod enumerator;
103/// Core rendering engine with styling and formatting support.
104pub mod renderer;
105
106// Re-export the main types and functions
107pub use children::{new_string_data, root, Children, Filter, Leaf, Node, NodeChildren, Tree};
108pub use enumerator::{
109    default_enumerator, default_indenter, rounded_enumerator, Enumerator, Indenter, StyleFunc,
110};
111pub use renderer::Renderer;
112
113// Go API compatibility aliases
114/// Trait alias for `Children` - provides compatibility with Go naming conventions
115pub use Children as ChildrenTrait;
116/// Type alias for `Leaf` - provides compatibility with Go naming conventions  
117pub use Leaf as LeafType;
118/// Type alias for `NodeChildren` - provides compatibility with Go naming conventions
119pub use NodeChildren as NodeChildrenType;
120/// Type alias for `Tree` - provides compatibility with Go naming conventions
121pub use Tree as TreeType;
122
123/// Creates a new empty tree.
124///
125/// This is a convenience function equivalent to `Tree::new()`.
126/// The tree starts with no root value and no children.
127///
128/// # Returns
129///
130/// A new empty `Tree` instance
131///
132/// # Examples
133///
134/// ```rust
135/// use lipgloss_tree;
136///
137/// let tree = lipgloss_tree::new();
138/// assert!(tree.to_string().is_empty());
139/// ```
140pub fn new() -> Tree {
141    Tree::new()
142}
143
144/// Creates a new tree with a root value.
145///
146/// This is a convenience function that creates a new tree and immediately
147/// sets its root value, equivalent to `Tree::new().root(root)`.
148///
149/// # Arguments
150///
151/// * `root` - The root value for the tree (anything that can be converted to a String)
152///
153/// # Returns
154///
155/// A new `Tree` instance with the specified root value
156///
157/// # Examples
158///
159/// ```rust
160/// use lipgloss_tree;
161///
162/// let tree = lipgloss_tree::new_with_root("My Root");
163/// println!("{}", tree); // Outputs: "My Root"
164/// ```
165pub fn new_with_root(root: impl Into<String>) -> Tree {
166    Tree::new().root(root)
167}
lipgloss_tree/lib.rs

lipgloss_tree/
lib.rs
