1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
//! Terminal color capability detection and environment handling.
//!
//! This module determines the terminal's supported color level by inspecting
//! environment variables and whether stdout is attached to an interactive TTY.
//! The detected [`ColorLevel`] is used throughout `prettyt` to ensure styled
//! output behaves correctly across terminals, pipes, log files, and CI systems.
//!
//! # Detection Order
//!
//! Detection uses a strict precedence-based cascade. The first matching rule
//! determines the final [`ColorLevel`].
//!
//! | Priority | Source | Behavior | Result |
//! | :---: | :--- | :--- | :--- |
//! | **1** | `NO_COLOR` | Variable is present (any value) | [`ColorLevel::None`] |
//! | **2** | `FORCE_COLOR` | `"0"` | [`ColorLevel::None`] |
//! | | | `"1"` | [`ColorLevel::Basic`] |
//! | | | `"2"` | [`ColorLevel::Ansi256`] |
//! | | | Any other value (`"3"`, `"true"`, `"yes"`, etc.) | [`ColorLevel::TrueColor`] |
//! | **3** | TTY Check (`stdout`) | Output is not a terminal | [`ColorLevel::None`] |
//! | **4** | `COLORTERM` | Contains `"truecolor"` or `"24bit"` | [`ColorLevel::TrueColor`] |
//! | **5** | `TERM` | Equals `"dumb"` | [`ColorLevel::None`] |
//! | | | Contains `"256color"` | [`ColorLevel::Ansi256`] |
//! | **6** | Fallback | Standard interactive terminal | [`ColorLevel::Basic`] |
//!
//! ---
//!
//! # Behavior Notes
//!
//! ## `NO_COLOR`
//!
//! `NO_COLOR` has the highest precedence and always disables styling,
//! regardless of TTY state or forced color settings. This follows the
//! community convention defined at [no-color.org](https://no-color.org).
//!
//! ## `FORCE_COLOR`
//!
//! `FORCE_COLOR` explicitly enables color output, even when stdout is being
//! piped or redirected. This is commonly used in CI pipelines, snapshot tests,
//! and logging environments where ANSI output should be preserved.
//!
//! ## TTY Detection
//!
//! If stdout is not connected to an interactive terminal and no explicit
//! override is active, styling is disabled automatically to avoid leaking raw
//! ANSI escape sequences into logs or downstream commands.
//!
//! ## `COLORTERM` and `TERM`
//!
//! Modern terminals often expose `COLORTERM=truecolor` or `24bit` to advertise
//! full 24-bit RGB support. Legacy terminals commonly expose `256color` through
//! the `TERM` variable to indicate extended ANSI palette support.
pub use ;
pub use get_cached_level;