nils_term/lib.rs
1//! Small terminal utilities shared across the workspace.
2//!
3//! ## Progress
4//!
5//! `nils-term` provides a minimal, RAII-friendly progress abstraction that is safe for
6//! machine-readable stdout output.
7//!
8//! - Progress is drawn to **stderr** by default.
9//! - With `ProgressEnabled::Auto` (default), progress is enabled only when **stderr is a TTY**.
10//!
11//! ### Determinate progress
12//!
13//! ```rust
14//! use nils_term::progress::{Progress, ProgressOptions};
15//!
16//! let total = 3_u64;
17//! let progress = Progress::new(total, ProgressOptions::default().with_prefix("work "));
18//!
19//! for i in 0..total {
20//! progress.set_message(format!("item {i}"));
21//! progress.inc(1);
22//! }
23//!
24//! progress.finish();
25//! ```
26//!
27//! ### Spinner progress
28//!
29//! ```rust
30//! use nils_term::progress::{Progress, ProgressFinish, ProgressOptions};
31//!
32//! let spinner = Progress::spinner(
33//! ProgressOptions::default()
34//! .with_prefix("fetch ")
35//! .with_finish(ProgressFinish::Clear),
36//! );
37//!
38//! spinner.set_message("loading");
39//! spinner.tick();
40//! spinner.finish_and_clear();
41//! ```
42//!
43//! ### Library guidance
44//!
45//! Prefer accepting a `Progress` (or `ProgressOptions`) from the caller instead of reading env vars
46//! inside library code. This keeps libraries deterministic and lets binaries decide whether to show
47//! progress (e.g. interactive vs CI).
48
49pub mod progress;