Struct Tree

pub struct Tree { /* private fields */ }

A tree node that can contain both a value and child nodes.

Tree is the main building block for creating hierarchical tree structures. Unlike Leaf nodes, trees can have children and support advanced features like custom styling, enumerators, indenters, and offset-based child filtering.

Key Features

• Hierarchical structure: Can contain child nodes forming a tree
• Custom styling: Support for root, item, and enumerator styling
• Custom rendering: Override enumerators and indenters per-node
• Child filtering: Use offsets to display only a subset of children
• Builder pattern: Fluent API for easy tree construction

Examples

use lipgloss_tree::Tree;

let tree = Tree::new()
    .root("My Project")
    .child(vec![
        "file1.txt".into(),
        "file2.txt".into(),
        Tree::new()
            .root("subfolder")
            .child(vec!["nested.txt".into()])
            .into(),
    ]);

println!("{}", tree);

This creates a tree structure like:

My Project
├── file1.txt
├── file2.txt
├── subfolder
│   └── nested.txt

Implementations

impl Tree

pub fn new() -> Self

Creates a new empty tree with default settings.

The tree starts with no root value, no children, and default rendering settings.

Examples

use lipgloss_tree::{Tree, Node, Children};

let tree = Tree::new();
assert!(tree.value().is_empty());
assert_eq!(tree.children().length(), 0);

pub fn root(self, root: impl Into<String>) -> Self

Sets the root value of this tree.

The root value is displayed at the top of the tree when rendered. If no root is set, the tree will start directly with its children.

Arguments

• root - The root value (anything convertible to String)

Examples

use lipgloss_tree::{Tree, Node};

let tree = Tree::new().root("My Root");
assert_eq!(tree.value(), "My Root");

pub fn hide(self, hide: bool) -> Self

Sets the visibility of this tree.

Hidden trees are not rendered in the output, but their children may still be visible depending on the rendering context.

Arguments

• hide - true to hide this tree, false to show it

Examples

use lipgloss_tree::{Tree, Node};

let hidden_tree = Tree::new().root("Hidden").hide(true);
assert!(hidden_tree.hidden());

pub fn offset(self, start: usize, end: usize) -> Self

Sets the offset range for displaying children.

This allows you to display only a subset of the tree’s children, which is useful for pagination or filtering large trees.

Arguments

• start - Starting index (inclusive) for child display
• end - Ending index (exclusive) for child display

Examples

use lipgloss_tree::Tree;

let tree = Tree::new()
    .child(vec!["A".into(), "B".into(), "C".into(), "D".into()])
    .offset(1, 3); // Will only show children B and C

Note

If start > end, the values will be swapped. If end exceeds the number of children, it will be clamped to the children count.

pub fn child(self, children: Vec<Box<dyn Node>>) -> Self

Adds multiple children to this tree.

This method accepts a vector of boxed nodes and appends them all to the tree’s children collection. It matches Go’s Child(...any) method for API compatibility.

Arguments

• children - A vector of boxed nodes to add as children

Examples

use lipgloss_tree::{Tree, Node, Children};

let tree = Tree::new()
    .root("Parent")
    .child(vec![
        "Child 1".into(),
        "Child 2".into(),
        Tree::new().root("Nested").into(),
    ]);

assert_eq!(tree.children().length(), 3);

pub fn add_child(self, child: impl Into<Box<dyn Node>>) -> Self

Adds a single child to this tree.

This is a convenience method for adding one child at a time, accepting anything that can be converted into a boxed node.

Arguments

• child - A node (or convertible value) to add as a child

Examples

use lipgloss_tree::{Tree, Leaf, Node, Children};

let tree = Tree::new()
    .root("Parent")
    .add_child("String child")
    .add_child(Leaf::new("Leaf child", false))
    .add_child(Tree::new().root("Tree child"));

assert_eq!(tree.children().length(), 3);

pub fn enumerator(self, enumerator: Enumerator) -> Self

Sets a custom enumerator function for this tree.

The enumerator generates branch characters (like ├──, └──) based on each child’s position. This overrides the default enumerator for this tree.

Arguments

• enumerator - A function that takes (children, index) and returns a string

Examples

use lipgloss_tree::Tree;

let tree = Tree::new()
    .root("Custom")
    .enumerator(|children, i| {
        if i == children.length() - 1 {
            "╰──".to_string()  // Rounded last branch
        } else {
            "├──".to_string()  // Standard branch
        }
    })
    .child(vec!["A".into(), "B".into()]);

pub fn indenter(self, indenter: Indenter) -> Self

Sets a custom indenter function for this tree.

The indenter generates indentation strings for nested child content. This overrides the default indenter for this tree.

Arguments

• indenter - A function that takes (children, index) and returns an indentation string

Examples

use lipgloss_tree::Tree;

let tree = Tree::new()
    .indenter(|children, i| {
        if i == children.length() - 1 {
            "    ".to_string()  // Spaces for last child
        } else {
            "│   ".to_string()  // Vertical line for continuing
        }
    });

pub fn root_style(self, style: Style) -> Self

Sets the styling for the root value of this tree.

Arguments

• style - The lipgloss Style to apply to the root

Examples

use lipgloss_tree::Tree;
use lipgloss::Style;

let tree = Tree::new()
    .root("Styled Root")
    .root_style(Style::new().bold(true).foreground("blue"));

pub fn item_style(self, style: Style) -> Self

Sets the base style applied to all child items.

This style is applied to item content before any style functions.

Arguments

• style - The lipgloss Style to apply to all items

Examples

use lipgloss_tree::Tree;
use lipgloss::Style;

let tree = Tree::new()
    .child(vec!["Item 1".into(), "Item 2".into()])
    .item_style(Style::new().foreground("green"));

pub fn enumerator_style(self, style: Style) -> Self

Sets the base style applied to all enumerators (branch characters).

This style is applied to enumerators before any style functions.

Arguments

• style - The lipgloss Style to apply to all enumerators

Examples

use lipgloss_tree::Tree;
use lipgloss::Style;

let tree = Tree::new()
    .child(vec!["Item 1".into(), "Item 2".into()])
    .enumerator_style(Style::new().foreground("yellow"));

pub fn item_style_func(self, func: StyleFunc) -> Self

Sets a dynamic styling function for child items.

The function receives the children collection and the current index, allowing for context-aware styling decisions.

Arguments

• func - A function that takes (children, index) and returns a Style

Examples

use lipgloss_tree::Tree;
use lipgloss::Style;

let tree = Tree::new()
    .child(vec!["First".into(), "Second".into(), "Third".into()])
    .item_style_func(|_children, i| {
        if i % 2 == 0 {
            Style::new().foreground("red")
        } else {
            Style::new().foreground("blue")
        }
    });

pub fn enumerator_style_func(self, func: StyleFunc) -> Self

Sets a dynamic styling function for enumerators (branch characters).

The function receives the children collection and the current index, allowing for context-aware styling of branch characters.

Arguments

• func - A function that takes (children, index) and returns a Style

Examples

use lipgloss_tree::{Tree, Children};
use lipgloss::Style;

let tree = Tree::new()
    .child(vec!["Item 1".into(), "Item 2".into()])
    .enumerator_style_func(|children, i| {
        if i == children.length() - 1 {
            Style::new().foreground("red")   // Last item in red
        } else {
            Style::new().foreground("green") // Others in green
        }
    });

pub fn get_enumerator(&self) -> Option<&Enumerator>

Returns the custom enumerator function for this tree.

The enumerator function generates branch characters (like ├──, └──) for this tree’s children based on their position in the collection. This allows for custom tree rendering styles.

Returns

An optional reference to the enumerator function. Returns Some if a custom enumerator has been set with Tree::enumerator, or None if using the default enumerator.

Examples

use lipgloss_tree::Tree;

let tree = Tree::new()
    .enumerator(|children, i| {
        if i == children.length() - 1 {
            "└──".to_string()
        } else {
            "├──".to_string()
        }
    });

assert!(tree.get_enumerator().is_some());

pub fn get_indenter(&self) -> Option<&Indenter>

Returns the custom indenter function for this tree.

The indenter function generates indentation strings for nested content under this tree’s children. This determines how deeply nested items are visually offset in the rendered output.

Returns

An optional reference to the indenter function. Returns Some if a custom indenter has been set with Tree::indenter, or None if using the default indenter.

Examples

use lipgloss_tree::Tree;

let tree = Tree::new()
    .indenter(|children, i| {
        if i == children.length() - 1 {
            "    ".to_string()  // Spaces for last child
        } else {
            "│   ".to_string()  // Vertical line continuing
        }
    });

assert!(tree.get_indenter().is_some());

pub fn get_root_style(&self) -> Option<&Style>

Returns the styling configuration for this tree’s root value.

The root style is applied to the tree’s main value when rendered, allowing for custom colors, formatting, and visual effects on the top-level tree node.

Returns

An optional reference to the root style. Returns Some if a custom style has been set with Tree::root_style, or None if using the default (unstyled) appearance.

Examples

use lipgloss_tree::Tree;
use lipgloss::Style;

let tree = Tree::new()
    .root("Project Root")
    .root_style(Style::new().bold(true).foreground("blue"));

assert!(tree.get_root_style().is_some());

pub fn get_item_style_func(&self) -> Option<&StyleFunc>

Returns the dynamic styling function for this tree’s child items.

The item style function provides context-aware styling based on each child’s position within the tree. It receives the children collection and the current child’s index, allowing for complex styling logic.

Returns

An optional reference to the item style function. Returns Some if a custom function has been set with Tree::item_style_func, or None if using the default (no dynamic styling).

Examples

use lipgloss_tree::Tree;
use lipgloss::Style;

let tree = Tree::new()
    .child(vec!["Item 1".into(), "Item 2".into()])
    .item_style_func(|_children, i| {
        if i % 2 == 0 {
            Style::new().foreground("red")
        } else {
            Style::new().foreground("blue")
        }
    });

assert!(tree.get_item_style_func().is_some());

pub fn get_enumerator_style_func(&self) -> Option<&StyleFunc>

Returns the dynamic styling function for this tree’s branch characters.

The enumerator style function provides context-aware styling for the branch characters (like ├──, └──) based on each child’s position. It receives the children collection and current index for styling decisions.

Returns

An optional reference to the enumerator style function. Returns Some if a custom function has been set with Tree::enumerator_style_func, or None if using the default (no dynamic styling).

Examples

use lipgloss_tree::{Tree, Children};
use lipgloss::Style;

let tree = Tree::new()
    .child(vec!["First".into(), "Last".into()])
    .enumerator_style_func(|children, i| {
        if i == children.length() - 1 {
            Style::new().foreground("red")    // Last item
        } else {
            Style::new().foreground("green")  // Others
        }
    });

assert!(tree.get_enumerator_style_func().is_some());

pub fn get_item_style(&self) -> Option<&Style>

Returns the base styling configuration for this tree’s child items.

The item style is applied to all child item content before any dynamic style functions are applied. This provides a consistent base appearance for all children in the tree.

Returns

An optional reference to the base item style. Returns Some if a custom style has been set with Tree::item_style, or None if using the default (unstyled) appearance.

Examples

use lipgloss_tree::Tree;
use lipgloss::Style;

let tree = Tree::new()
    .child(vec!["Item 1".into(), "Item 2".into()])
    .item_style(Style::new().foreground("green").italic(true));

assert!(tree.get_item_style().is_some());

pub fn get_enumerator_style(&self) -> Option<&Style>

Returns the base styling configuration for this tree’s branch characters.

The enumerator style is applied to all branch characters (like ├──, └──) before any dynamic style functions are applied. This provides consistent base styling for all tree branch elements.

Returns

An optional reference to the base enumerator style. Returns Some if a custom style has been set with Tree::enumerator_style, or None if using the default (unstyled) appearance.

Examples

use lipgloss_tree::Tree;
use lipgloss::Style;

let tree = Tree::new()
    .child(vec!["Item 1".into(), "Item 2".into()])
    .enumerator_style(Style::new().foreground("yellow").bold(true));

assert!(tree.get_enumerator_style().is_some());

Trait Implementations

impl Clone for Tree

fn clone(&self) -> Tree

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for Tree

fn default() -> Self

Creates a default tree instance.

Equivalent to Tree::new() - creates an empty tree with no root value, no children, and default rendering settings.

impl Display for Tree

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<Tree> for Box<dyn Node>

fn from(tree: Tree) -> Self

Converts to this type from the input type.

impl Node for Tree

fn value(&self) -> String

Returns the string value of this node.

fn children(&self) -> Box<dyn Children>

Returns the children of this node.

fn hidden(&self) -> bool

Returns whether this node is hidden from rendering.

fn set_hidden(&mut self, hidden: bool)

Sets the visibility state of this node.

fn set_value(&mut self, value: String)

Updates the value of this node.

fn get_enumerator(&self) -> Option<&Enumerator>

Returns the custom enumerator function for this node, if any.

fn get_indenter(&self) -> Option<&Indenter>

Returns the custom indenter function for this node, if any.

fn get_item_style(&self) -> Option<&Style>

Returns the base item style for this node, if any.

fn get_enumerator_style(&self) -> Option<&Style>

Returns the base enumerator style for this node, if any.

fn get_item_style_func(&self) -> Option<&StyleFunc>

Returns the item style function for this node, if any.

fn get_enumerator_style_func(&self) -> Option<&StyleFunc>

Returns the enumerator style function for this node, if any.