verbosio/lib.rs
1#![allow(unused_imports)]
2//! # verbosio
3//!
4//! A lightweight, macro-based logging utility for CLI tools and scripts.
5//! Designed for ergonomics, speed, and minimal dependencies — with optional ANSI-colored output and terminal spinners.
6//!
7//! ## Features
8//!
9//! - Global verbosity level
10//! - Set/get via `set_verbosity!`, `get_verbosity!`, or `verbose_env!`
11//! - Conditional message printing
12//! - `verbose!`, `vinfo!`, `vwarn!`, `verror!`, `vebug!`
13//! - Distinct log levels: `INFO`, `WARN`, `ERROR`, `DEBUG`
14//! - Optional section headers via `vsection!`
15//! - Interactive terminal spinners via `status_line!` macros
16//! - Terminal-safe output (no flickering) using `crossterm`
17//! - All macros are verbosity-aware (`@lvl N`)
18//!
19//! ## Optional Features
20//!
21//! - `color`: Enables ANSI-colored output (via [`colored`](https://crates.io/crates/colored))
22//! - `status`: Enables spinner-based status lines using [`crossterm`](https://crates.io/crates/crossterm)
23//!
24//! ## Dependencies
25//!
26//! | Name | Purpose | Required by default |
27//! |-------------|----------------------------------|----------------------|
28//! | `once_cell` | Global static verbosity state | Yes |
29//! | `colored` | Colored output for log levels | No (`color`) |
30//! | `crossterm` | Interactive terminal spinners | No (`status`) |
31//!
32//! ## Example
33//!
34//! ```rust
35//! use verbosio::*;
36//!
37//! set_verbosity!(2);
38//!
39//! verbose!(@lvl 1, "Hello World!"); // printed
40//! vinfo!("App started."); // [INFO] App started.
41//! vwarn!(@lvl 3, "This won't show."); // not printed
42//! verror!("Something went wrong"); // [ERROR] Something went wrong
43//! ```
44//!
45//! ## Environment Support
46//!
47//! You can also set verbosity via the `VERBOSE` environment variable:
48//!
49//! ```rust
50//! use verbosio::verbose_env;
51//! unsafe {std::env::set_var("VERBOSE", "2");}
52//! verbose_env!(); // Sets verbosity to 2
53//! ```
54//!
55//! ## Status Line Example (feature = `"status"`)
56//!
57//! ```rust
58//! use verbosio::{status_line, status_line_done};
59//!
60//! if let Some(spinner) = status_line!("Building project…") {
61//! // Simulate work
62//! std::thread::sleep(std::time::Duration::from_secs(2));
63//! spinner.stop();
64//! status_line_done!("Build complete.");
65//! }
66//! ```
67//!
68//! ## Section Headers
69//!
70//! ```rust
71//! use verbosio::vsection;
72//!
73//! vsection!("Step 1: Preparation");
74//! vsection!(@lvl 3, "Step 2: {:?}", "Details"); // only printed if verbosity ≥ 3
75//! ```
76//!
77//! ## Debug-Only Output
78//!
79//! ```rust
80//! use verbosio::vebug;
81//!
82//! vebug!("Always shown in debug mode.");
83//! vebug!(@lvl 3, "Detailed: {:?}", "info"); // only if verbosity ≥ 3
84//! ```
85//!
86//! ## Philosophy
87//!
88//! `verbosio` is built to be ultra-lightweight and practical for CLI tooling,
89//! build scripts, and low-dependency utilities — with structured logging, and
90//! configurable verbosity.
91//!
92//! ## Performance Note
93//!
94//! `vebug!` uses `#[cfg(debug_assertions)]` and is completely removed in release builds.
95//! All other macros like `verbose!` and `status_line!` still check verbosity at runtime.
96
97
98
99
100pub mod macros;
101pub mod util;
102use once_cell::sync::Lazy;
103use std::sync::atomic::{AtomicU8};
104
105pub static VERBOSE: Lazy<AtomicU8> = Lazy::new(|| AtomicU8::new(0));
106
107/// Re-exports all macros for easy access.
108pub use macros::verbosity::*;
109pub use macros::terminal::*;
110pub use util::*;