Crate treelog

Expand description

A customizable tree rendering library and CLI for Rust

Provides low-level and high-level APIs for rendering hierarchical data structures, similar to tree, npm ls, or cargo tree. Also includes a command-line utility for quick tree visualization.

Documentation • Examples

Key Features: Multiple styles • Macro DSL • Builder API • Iterator support • Tree statistics & traversal • Search & filtering • Transformation & sorting • Export to HTML/SVG/DOT • Integrations with JSON/YAML/TOML, filesystem, Git, Cargo, and more

§Installation

§As a Library

Add this to your Cargo.toml:

[dependencies]
treelog = "0.0.6"

§As a CLI Tool

# Install from crates.io
cargo install treelog --features cli,arbitrary-walkdir,serde-json

# Or build from source
git clone https://github.com/muijf/treelog
cd treelog
cargo build --release --bin treelog --features cli,arbitrary-walkdir,serde-json

Note: The CLI requires the cli feature. Enable additional features based on the input sources you need. You can use convenience aliases like walkdir (for arbitrary-walkdir).

§Feature Flags

Most features are optional to keep the core library lightweight. Enable only what you need.

Core Features:

builder - Builder API for constructing trees
iterator - Iterator API for streaming trees
macro - Macro DSL for tree construction
formatters - Custom formatters for nodes and leaves
color - Color output support (requires colored)

Tree Operations:

traversal - Tree traversal iterators (pre-order, post-order, level-order)
transform - Tree transformation operations (map, filter, prune)
path - Tree path utilities (get by path, flatten)
compare - Tree comparison and diff operations
search - Tree search operations (find nodes/leaves, get paths)
sort - Tree sorting operations (sort by label, depth, custom)
stats - Tree statistics and metrics
merge - Tree merging with different strategies
export - Export to HTML, SVG, and DOT formats

Exact Serialization (Round-Trip):

serde - Meta-feature enabling all serde serialization

Enables all of the following:
- serde-json - JSON serialization/deserialization (Tree ↔ JSON)
- serde-yaml - YAML serialization/deserialization (Tree ↔ YAML)
- serde-toml - TOML serialization/deserialization (Tree ↔ TOML)
- serde-ron - RON serialization/deserialization (Tree ↔ RON)
You can also enable individual features instead of the meta-feature.

Arbitrary Conversion (One-Way):

arbitrary - Meta-feature enabling all arbitrary conversions

Enables all of the following:
- arbitrary-json - Convert any JSON to Tree (requires serde-json)
- arbitrary-yaml - Convert any YAML to Tree (requires serde-yaml)
- arbitrary-toml - Convert any TOML to Tree (requires serde-toml)
- arbitrary-xml - Convert XML/HTML to Tree
- arbitrary-walkdir - Build trees from directory structures
- arbitrary-petgraph - Convert petgraph graphs to Tree
- arbitrary-cargo - Build trees from Cargo metadata
- arbitrary-git2 - Build trees from Git repositories
- arbitrary-syn - Build trees from Rust AST
- arbitrary-tree-sitter - Build trees from tree-sitter parse trees
- arbitrary-clap - Build trees from clap command structures
You can also enable individual features instead of the meta-feature.

Convenience Aliases:

walkdir - Alias for arbitrary-walkdir
petgraph - Alias for arbitrary-petgraph
cargo-metadata - Alias for arbitrary-cargo
git2 - Alias for arbitrary-git2
syn - Alias for arbitrary-syn
tree-sitter - Alias for arbitrary-tree-sitter
clap - Alias for arbitrary-clap (also used by CLI)
cli - CLI binary (includes clap)

Quick examples:

# Common feature set
treelog = { version = "0.0.6", features = ["traversal", "transform", "path", "compare", "merge", "export"] }

# Enable everything
treelog = { version = "0.0.6", features = ["all"] }

Note: The cli feature is separate and must be enabled explicitly for the binary. Use convenience aliases like walkdir (for arbitrary-walkdir) when available.

§Quick Start

use treelog::{Tree, renderer::write_tree};

let tree = Tree::Node("root".to_string(), vec![
    Tree::Leaf(vec!["item1".to_string()]),
    Tree::Node("sub".to_string(), vec![
        Tree::Leaf(vec!["subitem1".to_string()]),
        Tree::Leaf(vec!["subitem2".to_string()]),
    ]),
]);

let mut output = String::new();
write_tree(&mut output, &tree).unwrap();
println!("{}", output);

Output:

root
├─ item1
└─ sub
   ├─ subitem1
   └─ subitem2

For more examples and usage patterns, see the examples.

§CLI Usage

The CLI tool provides a convenient way to visualize trees from various sources without writing code. All library features are available through the command-line interface.

§Basic Usage

# Visualize a directory structure
treelog from dir . --max-depth 3

# Visualize Cargo dependencies
treelog from cargo

# Visualize Git repository structure
treelog from git .

# Render a tree from a file (JSON/YAML/TOML/RON)
treelog render tree.json

# Render a tree from stdin
cat tree.json | treelog render

# Get tree statistics
treelog from dir . --format json | treelog stats

§Input Sources

# Filesystem & Git
treelog from dir <path> [--max-depth <n>]        # arbitrary-walkdir
treelog from git [path] [--branches] [--commit]  # arbitrary-git2

# Code & AST
treelog from rust <file>                         # arbitrary-syn
treelog from tree-sitter <file> [--language]     # arbitrary-tree-sitter
treelog from xml <file>                          # arbitrary-xml

# Package Managers
treelog from cargo [--manifest <path>] [--package <name>]  # arbitrary-cargo

# Data Formats
treelog from json <file>   # serde-json
treelog from yaml <file>   # serde-yaml
treelog from toml <file>   # serde-toml
treelog from ron <file>    # serde-ron

§Rendering Options

# Styles
treelog from dir . --style ascii
treelog from dir . --custom-style ">-,<-,| ,   "

# Output
treelog from dir . --output tree.txt
treelog from dir . --format json > tree.json
treelog from dir . --format html > tree.html
treelog from dir . --format svg > tree.svg
treelog from dir . --format dot > tree.dot

§Tree Operations

# Basic operations
treelog render tree.json          # Render from file
treelog render -                   # Render from stdin
treelog stats tree.json            # Get statistics
treelog search "pattern" tree.json # Search nodes/leaves

# Manipulation
treelog sort --method label tree.json
treelog sort --method depth --reverse tree.json
treelog transform map-nodes "[{}]" tree.json
treelog transform filter "src" tree.json

# Comparison & Merging
treelog compare tree1.json tree2.json
treelog merge --strategy append tree1.json tree2.json

# Export
treelog export html tree.json > output.html
treelog export svg tree.json > output.svg
treelog export dot tree.json > output.dot

§Piping and Serialization

# Create tree and get statistics
treelog from dir . --format json | treelog stats

# Transform and export
treelog from dir . --format json | treelog transform filter "src" | treelog export html > output.html

Note: When piping between commands, use --format json (or yaml, toml, ron) to serialize the tree structure. The default text format is for human-readable output only.

§Help

treelog --help
treelog from --help
treelog from dir --help

§Examples

Run any example with: cargo run --example <name> --all-features

Core Examples:

basic - Basic tree construction and rendering
builder - Using the builder API
iterator - Streaming large trees
macro - Using the macro DSL
customization - Custom styles and formatters
complex - Complex tree structures
file_tree - File system tree example

Advanced Examples:

statistics - Tree statistics and analysis
traversal - Tree traversal iterators
search - Tree search and query operations
transform - Tree transformation operations
sorting - Tree sorting operations
path - Tree path utilities
comparison - Tree comparison and diff
merge - Tree merging strategies
export - Export to HTML, SVG, and DOT formats

Integration Examples:

arbitrary - Arbitrary data conversion (JSON/YAML/TOML to Tree)
serde - Exact JSON and YAML serialization (Tree ↔ JSON/YAML)
toml - TOML parsing and conversion
filesystem - File system tree building
petgraph - Graph to/from tree conversion
cargo - Cargo dependency tree visualization
git2 - Git repository structure visualization
xml - XML/HTML DOM tree visualization
syn - Rust AST visualization
ron - RON serialization
tree_sitter - Tree-sitter parse tree visualization
clap - Command-line argument structure visualization

§Development

Format code:

cargo fmt --all

Formats all Rust code according to the official style guide.

Lint code:

cargo clippy --all-targets --all-features -- -D warnings

Runs Clippy linter with all targets and features enabled, treating warnings as errors.

Run tests:

cargo test --all-features

Runs all tests with all features enabled to ensure comprehensive coverage.

Editor setup: Recommended extensions are available in .vscode/extensions.json. See CONTRIBUTING.md for development guidelines and pre-commit hooks.

§License

This project is licensed under the MIT License - see the LICENSE file for details.

§Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Re-exports§

pub use config::RenderConfig;
pub use iterator::Line;
pub use iterator::TreeIteratorExt;
pub use stats::TreeStats;
pub use style::StyleConfig;
pub use style::TreeStyle;
pub use tree::Tree;
pub use renderer::render_to_string;
pub use renderer::render_to_string_with_config;
pub use renderer::write_tree;
pub use renderer::write_tree_with_config;

Modules§

arbitrary: Arbitrary data structure conversion support for Tree.
builder: High-level builder API for constructing trees.
compare: Tree comparison operations.
config: Configuration options for tree rendering.
export: Tree export to various formats (HTML, SVG, DOT).
iterator: Iterator API for line-by-line tree access.
merge: Tree merging operations.
path: Tree path utilities for navigating and accessing tree elements by path.
renderer: Core rendering logic for trees.
search: Tree search and find operations.
serde: Serde serialization and deserialization support for Tree.
sort: Tree sorting operations.
stats: Tree statistics and metrics.
style: Tree style definitions and customization options.
transform: Tree transformation operations.
traversal: Tree traversal iterators for different traversal orders.
tree: Core tree data structure for representing hierarchical data.

Macros§

tree: Creates a tree using a DSL-like syntax.

Crate treelog

Crate treelog Copy item path

§Table of Contents

§Installation

§As a Library

§As a CLI Tool

§Feature Flags

§Quick Start

§CLI Usage

§Basic Usage

§Input Sources

§Rendering Options

§Tree Operations

§Piping and Serialization

§Help

§Examples

§Development

§License

§Contributing

Re-exports§

Modules§

Macros§

Crate treelog