cli_forge/lib.rs
1//! # cli-forge
2//!
3//! A unified command-line framework where argument parsing and styled output
4//! speak one API. This release delivers the output layer every other piece — and
5//! every sibling crate in the cli collection — is built on: one styling system,
6//! reached three ways, over a single cross-platform terminal backend.
7//!
8//! ## The three styling paths
9//!
10//! Plain text is the common case and stays cheap — [`out`] and [`err`] do no
11//! parsing and no allocation for a string literal:
12//!
13//! ```
14//! use cli_forge::{out, err};
15//!
16//! out("building...");
17//! err("something went wrong");
18//! ```
19//!
20//! When you want color, opt into one of three paths that all render to the same
21//! bytes for the same intent:
22//!
23//! ```
24//! use cli_forge::{define_tag, out, parse, style, tag};
25//!
26//! // 1. The builder — chain methods, drop the result into `out`.
27//! out(style("done").green().bold());
28//!
29//! // 2. Inline tags — markup parsed only here, never in `out`.
30//! parse("<c=red><b>ERROR:</b></c> <c=#ff8800>disk almost full</c>");
31//!
32//! // 3. A named style — define once, reuse anywhere.
33//! define_tag("error", style("").red().bold());
34//! out(tag("error").render_with("build failed"));
35//! ```
36//!
37//! ## Colors and terminals
38//!
39//! Colors are the eight standard names, plus any 24-bit value via
40//! [`Style::hex`] / [`Style::rgb`] or a `<c=#rrggbb>` / `<c=r,g,b>` tag. The
41//! terminal's capability is detected once: on a true-color terminal the exact
42//! value is emitted; on a 256- or 16-color terminal it is downgraded to the
43//! nearest representable color; on a pipe, under `NO_COLOR`, or with the `color`
44//! feature off, styling is dropped and only text is written. The Windows console
45//! is handled behind the same API as Unix terminals.
46//!
47//! ## Feature flags
48//!
49//! - **`std`** *(default)* — terminal detection and the stdout/stderr writers.
50//! - **`color`** *(default)* — ANSI styled output. Disable for plain output; the
51//! API stays complete and every styled value renders as its plain text.
52//! - **`auth`** — reserved for the `requires_auth` command flag (v0.5.0); no
53//! effect yet.
54
55#![cfg_attr(not(feature = "std"), no_std)]
56#![cfg_attr(docsrs, feature(doc_cfg))]
57#![forbid(unsafe_code)]
58#![deny(missing_docs)]
59#![deny(unused_must_use)]
60#![deny(unused_results)]
61#![deny(clippy::unwrap_used)]
62#![deny(clippy::expect_used)]
63#![deny(clippy::todo)]
64#![deny(clippy::unimplemented)]
65#![deny(clippy::unreachable)]
66#![deny(clippy::print_stdout)]
67#![deny(clippy::print_stderr)]
68#![deny(clippy::dbg_macro)]
69
70#[cfg(feature = "std")]
71mod color;
72#[cfg(feature = "std")]
73mod output;
74#[cfg(feature = "std")]
75mod registry;
76#[cfg(feature = "std")]
77mod style;
78#[cfg(feature = "std")]
79mod tags;
80#[cfg(feature = "std")]
81mod terminal;
82
83#[cfg(all(test, feature = "color"))]
84mod crosspath_tests;
85
86#[cfg(feature = "std")]
87pub use crate::output::{err, out};
88#[cfg(feature = "std")]
89pub use crate::registry::{Tag, define_tag, tag};
90#[cfg(feature = "std")]
91pub use crate::style::{Style, style};
92#[cfg(feature = "std")]
93pub use crate::tags::parse;