From 015f88b21a43210b625fbd42dd7140e5c80121ac Mon Sep 17 00:00:00 2001 From: Ed Page Date: Tue, 18 Apr 2023 14:54:16 -0500 Subject: [PATCH] feat(help): Allow customizing terminal styling For now, this is behind the `unstable-styles` feature as we verify this is what we want for #3224 --- Cargo.toml | 1 + Makefile | 2 +- clap_builder/Cargo.toml | 3 ++- clap_builder/src/builder/command.rs | 25 +++++++++++++++++++++++++ clap_builder/src/builder/mod.rs | 3 +++ clap_builder/src/builder/styled_str.rs | 13 ++++++++++++- src/_features.rs | 1 + 7 files changed, 45 insertions(+), 3 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 80cb6b0fed3..f148ffa737a 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -94,6 +94,7 @@ string = ["clap_builder/string"] # Allow runtime generated strings # In-work features unstable-v5 = ["clap_builder/unstable-v5", "clap_derive?/unstable-v5", "deprecated"] +unstable-styles = ["clap_builder/unstable-styles"] [lib] bench = false diff --git a/Makefile b/Makefile index 6f54f577464..1c203cedbc9 100644 --- a/Makefile +++ b/Makefile @@ -16,7 +16,7 @@ _FEATURES = minimal default wasm full debug release _FEATURES_minimal = --no-default-features --features "std" _FEATURES_default = _FEATURES_wasm = --no-default-features --features "std help usage error-context suggestions" --features "deprecated derive cargo env unicode string" -_FEATURES_full = --features "deprecated derive cargo env unicode string wrap_help" +_FEATURES_full = --features "deprecated derive cargo env unicode string wrap_help unstable-styles" _FEATURES_next = ${_FEATURES_full} --features unstable-v5 _FEATURES_debug = ${_FEATURES_full} --features debug --features clap_complete/debug _FEATURES_release = ${_FEATURES_full} --release diff --git a/clap_builder/Cargo.toml b/clap_builder/Cargo.toml index 4ab9f08b5ae..91c9833e1b4 100644 --- a/clap_builder/Cargo.toml +++ b/clap_builder/Cargo.toml @@ -32,7 +32,7 @@ tag-name = "v{{version}}" [features] default = ["std", "color", "help", "usage", "error-context", "suggestions"] debug = ["dep:backtrace"] # Enables debug messages -unstable-doc = ["cargo", "wrap_help", "env", "unicode", "string"] # for docs.rs +unstable-doc = ["cargo", "wrap_help", "env", "unicode", "string", "unstable-styles"] # for docs.rs # Used in default std = ["anstyle/std"] # support for no_std in a backwards-compatible way @@ -52,6 +52,7 @@ string = [] # Allow runtime generated strings # In-work features unstable-v5 = ["deprecated"] +unstable-styles = ["color"] [lib] bench = false diff --git a/clap_builder/src/builder/command.rs b/clap_builder/src/builder/command.rs index 37bed473a0d..abd743382e6 100644 --- a/clap_builder/src/builder/command.rs +++ b/clap_builder/src/builder/command.rs @@ -1081,6 +1081,31 @@ impl Command { } } + /// Sets when to color output. + /// + /// **NOTE:** This choice is propagated to all child subcommands. + /// + /// **NOTE:** Default behaviour is [`ColorChoice::Auto`]. + /// + /// # Examples + /// + /// ```no_run + /// # use clap_builder as clap; + /// # use clap::{Command, ColorChoice}; + /// Command::new("myprog") + /// .color(ColorChoice::Never) + /// .get_matches(); + /// ``` + /// [`ColorChoice::Auto`]: crate::ColorChoice::Auto + #[cfg(feature = "color")] + #[inline] + #[must_use] + #[cfg(feature = "unstable-styles")] + pub fn styles(mut self, styles: Styles) -> Self { + self.app_ext.set(styles); + self + } + /// Sets the terminal width at which to wrap help messages. /// /// Using `0` will ignore terminal widths and use source formatting. diff --git a/clap_builder/src/builder/mod.rs b/clap_builder/src/builder/mod.rs index 4c65e9aaa8d..495c8458762 100644 --- a/clap_builder/src/builder/mod.rs +++ b/clap_builder/src/builder/mod.rs @@ -35,6 +35,8 @@ pub use range::ValueRange; pub use resettable::IntoResettable; pub use resettable::Resettable; pub use styled_str::StyledStr; +#[cfg(feature = "unstable-styles")] +pub use styled_str::Styles; pub use value_hint::ValueHint; pub use value_parser::_AutoValueParser; pub use value_parser::via_prelude; @@ -60,4 +62,5 @@ pub(crate) use self::str::Inner as StrInner; pub(crate) use action::CountType; pub(crate) use arg_settings::{ArgFlags, ArgSettings}; pub(crate) use command::AppTag; +#[cfg(not(feature = "unstable-styles"))] pub(crate) use styled_str::Styles; diff --git a/clap_builder/src/builder/styled_str.rs b/clap_builder/src/builder/styled_str.rs index ba07ae64828..4d277815801 100644 --- a/clap_builder/src/builder/styled_str.rs +++ b/clap_builder/src/builder/styled_str.rs @@ -198,20 +198,30 @@ impl std::fmt::Display for StyledStr { } } +/// Terminal styling definitions #[derive(Clone, Debug)] #[non_exhaustive] -pub(crate) struct Styles { +#[allow(missing_copy_implementations)] // Large enough type that I want an explicit `clone()` for now +pub struct Styles { + /// Heading style, e.g. [`help_heading`][crate::Arg::help_heading] pub header: anstyle::Style, + /// Literal command-line syntax, like `--help` pub literal: anstyle::Style, + /// Descriptions within command-line syntax, like [`value_name`][crate::Arg::value_name] pub placeholder: anstyle::Style, + /// Suggested usage pub good: anstyle::Style, + /// Invalid usage pub warning: anstyle::Style, + /// Error heading pub error: anstyle::Style, + /// Extra details #[allow(dead_code)] pub hint: anstyle::Style, } impl Styles { + /// No terminal styling pub const fn plain() -> Self { Self { header: anstyle::Style::new(), @@ -224,6 +234,7 @@ impl Styles { } } + /// Default terminal styling pub const fn styled() -> Self { #[cfg(feature = "color")] { diff --git a/src/_features.rs b/src/_features.rs index b47ee259c28..27b567c9842 100644 --- a/src/_features.rs +++ b/src/_features.rs @@ -26,3 +26,4 @@ //! **Warning:** These may contain breaking changes between minor releases. //! //! * **unstable-v5**: Preview features which will be stable on the v5.0 release +//! * **unstable-unstable-styles**: Custom theming support for clap