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

@@ -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

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

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

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.

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;

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")]
         {

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