concolor-clap

concolor-clap is a small helper crate from the rust-cli organization that bridges the clap argument parser with concolor, a shared library for detecting and controlling terminal color support across a Rust application’s dependency tree. Instead of every CLI author writing their own --color <auto|always|never> flag and separately wiring it into concolor’s detection logic, this crate provides a single #[derive(clap::Args)] struct that can be flattened into any clap Cli definition.

Once mixed in, the crate exposes a color_choice() helper for setting clap’s own coloring at startup, and a Color struct whose to_control()/apply() methods translate the user’s CLI selection into concolor’s ColorChoice enum. This keeps color-flag behavior consistent across the ecosystem of CLIs that adopt concolor as their shared detection layer, rather than each tool reinventing ad hoc environment-variable or TTY checks.

What You Get

• A Color struct implementing clap::Args that can be #[command(flatten)]ed into any clap Cli struct to add a standard --color <auto|always|never> argument
• A color_choice() function that resolves clap’s own internal coloring (help text, error messages) using concolor’s terminal detection
• A ColorChoice enum (Auto, Always, Never) with FromStr and Display implementations for use as a clap value_enum
• An apply() method (behind the api feature) that pushes the user’s selection into concolor’s global state so downstream crates in the same process pick it up
• An auto feature (enabled by default) that pulls in concolor/auto and clap/color so detection works out of the box with zero extra configuration

Common Use Cases

• Adding a standards-compliant --color flag to a new clap-based CLI without hand-rolling detection logic
• Keeping color behavior consistent across a suite of internal Rust CLI tools that all depend on concolor
• Respecting NO_COLOR/CLICOLOR environment conventions in a clap app without manually checking environment variables
• Propagating a user’s explicit color preference to other concolor-aware crates used within the same binary

Under The Hood

Architecture The crate is a single-file mixin (src/lib.rs) inside the larger concolor umbrella workspace, sitting alongside sibling crates concolor (core detection), concolor-query (low-level capability probing), and concolor-override. It exposes one public struct, Color, deriving clap::Args so consumers #[command(flatten)] it directly into their own Cli struct rather than composing it through inheritance or a builder. A free function, color_choice(), is called before argument parsing to resolve clap’s own internal coloring, while Color::to_control()/Color::apply() translate the parsed flag into concolor’s ColorChoice type after parsing. This split — one path for clap’s self-coloring, one for the user’s business logic — is the crate’s entire design surface; there is no internal state beyond what clap and concolor already own, so changing the core abstraction would mean changing either the clap::Args derive shape or the enum contract with concolor itself.

Tech Stack Written in Rust 2021 edition with an MSRV of 1.64.0, the crate depends on concolor (path dependency within the workspace, ^0.1.1, default-features = false) and clap ^4.0.0 with derive and std features enabled. It has no runtime dependencies beyond these two, no build script, and no bundled binary — it is purely a library crate published to crates.io. The workspace uses standard cargo tooling with GitHub Actions for CI (ci.yml, rust-next.yml for nightly/beta checks, audit.yml for cargo-audit, plus committed.yml for commit-message linting and a spelling.yml check), and Renovate for dependency updates.

Code Quality The crate has a single inline test (verify_app) that constructs a clap Cli using the flattened Color struct and calls Cli::command().debug_assert(), which validates clap’s internal invariants but does not assert on argument-parsing behavior or output values — coverage is minimal by design given the crate’s small surface area. Error handling is limited to FromStr::from_str returning a Result<Self, String> for unrecognized color-choice strings; there are no unwraps or panics in the public API path. Naming is consistent with clap and Rust conventions (ColorChoice, Color, to_control), and the crate is #![warn(missing_docs)]-adjacent in spirit with doc comments on every public item, though it does not enforce a linter or formatter check in CI beyond cargo fmt/clippy implied by the shared workspace tooling.

API Design The public API is deliberately minimal: one struct to flatten, one function to call at startup, and one enum with three variants. This keeps integration to two or three lines of code in a consumer’s Cli definition, and the #[command(about = None, long_about = None)] attribute on Color avoids polluting the consuming CLI’s own help text with mixin-specific descriptions. The trade-off is that customization is limited — there’s no way to rename the flag, change its default, or add additional color-choice variants without forking the crate, which is consistent with its role as an opinionated, drop-in convenience rather than a configurable framework.