prodash

prodash uses Cargo features to allow users to tailor the library to their specific needs (e.g., choosing a terminal backend or enabling specific unit formatting).

Core Rendering Features

render-tui (Terminal User Interface)

Provides a full-screen TUI visualizing the entire progress state. It treats the terminal as a matrix display and supports keyboard controls and dynamic resizing. Requires one of the following (mutually exclusive):

• render-tui-crossterm: Uses the crossterm backend. Works natively everywhere but has more dependencies. (Example: cargo build --features render-tui-crossterm,crossterm/event-stream)
• render-tui-termion: Uses the termion backend. Leaner, but works only on unix systems.

render-line (Line-based Renderer)

A minimal, low-dependency renderer that displays progress in a single line (or subset of the hierarchy). It supports clicolors and no-color specs and can include an initial delay to show progress only when needed. Requires one of the following (mutually exclusive):

• render-line-crossterm: Uses the crossterm backend (useful for Windows).
• render-line-termion: Uses the termion backend (useful for lean Unix-only builds).

Optional render-line features:

• render-line-autoconfigure: Automatically configures display based on terminal presence and color support via render::line::Options::auto_configure().
• signal-hook: Automatically handles SIG_INT and SIG_TERM to reset the cursor if hide_cursor is enabled. Requires an extra thread and dependencies.

Progress and Logging

• progress-tree (default): Provides Progress and Root trait implementations using dashmap for render-line and render-tui.
  • progress-tree-hp-hashmap: High-performance registry for ultra-heavy insertions/deletions.
  • progress-tree-log: Redirects tree::Item::message(...) calls to the log crate instead of writing progress.
• progress-log: A Progress implementation that logs messages and progress using the log crate.

Unit Formatting

• unit-bytes: Supports dynamic byte display (via bytesize).
• unit-human: Displays counts in human-readable formats (via human_format).
• unit-duration: Displays durations in a friendly format like _5m4s_ (via jiff).

Other

• local-time: Uses local time instead of UTC for timestamps in render-tui or render-line message panes.

A Key represents a specific position within a hierarchical tree of tasks. It is composed of up to 6 levels of nesting, where each level is identified by a unique Id (a u16).

To build a path for a child task, use the add_child method on an existing Key. This creates a new Key with the child's ID at the next nesting level.

Important Limitations:

• Maximum Depth: The maximum nesting level is 6. If you attempt to add a child beyond this depth, the system will warn you and add the task to the current parent level instead.
• Sibling Capacity: There is a practical limit of $2^{16}$ tasks at any single level. Exceeding this may cause unexpected behavior as multiple progress handles might attempt to manipulate the same state.

// Example of building a hierarchical key
let root = Key::default();
let level1 = root.add_child(101);
let level2 = level1.add_child(202);

assert_eq!(level2.level(), 2);

The progress tree is organized starting from a Root. You can use the tree to create a hierarchy of tasks, where each task (represented by an Item) can have its own progress state, messages, and child tasks.

To use the tree:

1. Initialize a Root.
2. Add children to the root or existing items using add_child or add_child_with_id.
3. Use the returned progress handle to call init, set, done, or fail to update the task's status.

This allows for complex, nested progress reporting where sub-tasks can be tracked independently under a parent task.

let tree = prodash::tree::Root::new();
let mut progress = tree.add_child("task 1");

// Initialize with total steps and an optional label
progress.init(Some(10), Some("elements".into()));

// Update progress
for p in 0..10 {
    progress.set(p);
}

// Mark task as completed
progress.done("great success");

// Add a sub-task with a specific ID
let mut sub_progress = progress.add_child_with_id("sub-task 1", *b"TSK2");
sub_progress.init(None, None);
sub_progress.set(5);
sub_progress.fail("couldn't finish");