Merge pull request #6057 from GilShoshan94/master

epage · web-flow · commit 0f602396a338 · 2025-07-09T17:37:08.000-05:00
feat(help): Allow styling for inline context
diff --git a/clap_builder/src/builder/styling.rs b/clap_builder/src/builder/styling.rs
@@ -28,6 +28,8 @@ pub struct Styles {
     placeholder: Style,
     valid: Style,
     invalid: Style,
+    context: Style,
+    context_value: Option<Style>,
 }
 
 impl Styles {
@@ -41,6 +43,8 @@ impl Styles {
             placeholder: Style::new(),
             valid: Style::new(),
             invalid: Style::new(),
+            context: Style::new(),
+            context_value: None,
         }
     }
 
@@ -58,6 +62,8 @@ impl Styles {
                 placeholder: Style::new(),
                 valid: Style::new().fg_color(Some(Color::Ansi(AnsiColor::Green))),
                 invalid: Style::new().fg_color(Some(Color::Ansi(AnsiColor::Yellow))),
+                context: Style::new(),
+                context_value: None,
             }
         }
         #[cfg(not(feature = "color"))]
@@ -114,6 +120,24 @@ impl Styles {
         self.invalid = style;
         self
     }
+
+    /// Highlight all specified contexts, e.g. `[default: false]`
+    ///
+    /// To specialize the style of the value within the context, see [`Styles::context_value`]
+    #[inline]
+    pub const fn context(mut self, style: Style) -> Self {
+        self.context = style;
+        self
+    }
+
+    /// Highlight values within all of the context, e.g. the `false` in `[default: false]`
+    ///
+    /// If not explicitly set, falls back to `context`'s style.
+    #[inline]
+    pub const fn context_value(mut self, style: Style) -> Self {
+        self.context_value = Some(style);
+        self
+    }
 }
 
 /// Reflection
@@ -159,6 +183,25 @@ impl Styles {
     pub const fn get_invalid(&self) -> &Style {
         &self.invalid
     }
+
+    /// Highlight all specified contexts, e.g. `[default: false]`
+    ///
+    /// To specialize the style of the value within the context, see [`Styles::context_value`]
+    #[inline(always)]
+    pub const fn get_context(&self) -> &Style {
+        &self.context
+    }
+
+    /// Highlight values within all of the context, e.g. the `false` in `[default: false]`
+    ///
+    /// If not explicitly set, falls back to `context`'s style.
+    #[inline(always)]
+    pub const fn get_context_value(&self) -> &Style {
+        match &self.context_value {
+            Some(s) => s,
+            None => &self.context,
+        }
+    }
 }
 
 impl super::AppExt for Styles {}
diff --git a/clap_builder/src/output/help_template.rs b/clap_builder/src/output/help_template.rs
@@ -739,6 +739,10 @@ impl HelpTemplate<'_, '_> {
 
     fn spec_vals(&self, a: &Arg) -> String {
         debug!("HelpTemplate::spec_vals: a={a}");
+        let ctx = &self.styles.get_context();
+        let ctx_val = &self.styles.get_context_value();
+        let val_sep = format!("{ctx}, {ctx:#}"); // context values styled separator
+
         let mut spec_vals = Vec::new();
         #[cfg(feature = "env")]
         if let Some(ref env) = a.env {
@@ -758,7 +762,11 @@ impl HelpTemplate<'_, '_> {
                 } else {
                     Default::default()
                 };
-                let env_info = format!("[env: {}{}]", env.0.to_string_lossy(), env_val);
+                let env_info = format!(
+                    "{ctx}[env: {ctx:#}{ctx_val}{}{}{ctx_val:#}{ctx}]{ctx:#}",
+                    env.0.to_string_lossy(),
+                    env_val
+                );
                 spec_vals.push(env_info);
             }
         }
@@ -768,21 +776,23 @@ impl HelpTemplate<'_, '_> {
                 a.default_vals
             );
 
-            let pvs = a
+            let dvs = a
                 .default_vals
                 .iter()
-                .map(|pvs| pvs.to_string_lossy())
-                .map(|pvs| {
-                    if pvs.contains(char::is_whitespace) {
-                        Cow::from(format!("{pvs:?}"))
+                .map(|dv| dv.to_string_lossy())
+                .map(|dv| {
+                    if dv.contains(char::is_whitespace) {
+                        Cow::from(format!("{dv:?}"))
                     } else {
-                        pvs
+                        dv
                     }
                 })
                 .collect::<Vec<_>>()
                 .join(" ");
 
-            spec_vals.push(format!("[default: {pvs}]"));
+            spec_vals.push(format!(
+                "{ctx}[default: {ctx:#}{ctx_val}{dvs}{ctx_val:#}{ctx}]{ctx:#}"
+            ));
         }
 
         let mut als = Vec::new();
@@ -791,7 +801,7 @@ impl HelpTemplate<'_, '_> {
             .short_aliases
             .iter()
             .filter(|&als| als.1) // visible
-            .map(|als| format!("-{}", als.0)); // name
+            .map(|als| format!("{ctx_val}-{}{ctx_val:#}", als.0)); // name
         debug!(
             "HelpTemplate::spec_vals: Found short aliases...{:?}",
             a.short_aliases
@@ -802,12 +812,13 @@ impl HelpTemplate<'_, '_> {
             .aliases
             .iter()
             .filter(|&als| als.1) // visible
-            .map(|als| format!("--{}", als.0)); // name
+            .map(|als| format!("{ctx_val}--{}{ctx_val:#}", als.0)); // name
         debug!("HelpTemplate::spec_vals: Found aliases...{:?}", a.aliases);
         als.extend(long_als);
 
         if !als.is_empty() {
-            spec_vals.push(format!("[aliases: {}]", als.join(", ")));
+            let als = als.join(&val_sep);
+            spec_vals.push(format!("{ctx}[aliases: {ctx:#}{als}{ctx}]{ctx:#}"));
         }
 
         if !a.is_hide_possible_values_set() && !self.use_long_pv(a) {
@@ -818,10 +829,11 @@ impl HelpTemplate<'_, '_> {
                 let pvs = possible_vals
                     .iter()
                     .filter_map(PossibleValue::get_visible_quoted_name)
+                    .map(|pv| format!("{ctx_val}{pv}{ctx_val:#}"))
                     .collect::<Vec<_>>()
-                    .join(", ");
+                    .join(&val_sep);
 
-                spec_vals.push(format!("[possible values: {pvs}]"));
+                spec_vals.push(format!("{ctx}[possible values: {ctx:#}{pvs}{ctx}]{ctx:#}"));
             }
         }
         let connector = if self.use_long { "\n" } else { " " };
@@ -984,15 +996,20 @@ impl HelpTemplate<'_, '_> {
 
     fn sc_spec_vals(&self, a: &Command) -> String {
         debug!("HelpTemplate::sc_spec_vals: a={}", a.get_name());
+        let ctx = &self.styles.get_context();
+        let ctx_val = &self.styles.get_context_value();
+        let val_sep = format!("{ctx}, {ctx:#}"); // context values styled separator
         let mut spec_vals = vec![];
 
         let mut short_als = a
             .get_visible_short_flag_aliases()
-            .map(|a| format!("-{a}"))
+            .map(|a| format!("{ctx_val}-{a}{ctx_val:#}"))
             .collect::<Vec<_>>();
-        let als = a.get_visible_aliases().map(|s| s.to_string());
+        let als = a
+            .get_visible_aliases()
+            .map(|s| format!("{ctx_val}{s}{ctx_val:#}"));
         short_als.extend(als);
-        let all_als = short_als.join(", ");
+        let all_als = short_als.join(&val_sep);
         if !all_als.is_empty() {
             debug!(
                 "HelpTemplate::spec_vals: Found aliases...{:?}",
@@ -1002,7 +1019,7 @@ impl HelpTemplate<'_, '_> {
                 "HelpTemplate::spec_vals: Found short flag aliases...{:?}",
                 a.get_all_short_flag_aliases().collect::<Vec<_>>()
             );
-            spec_vals.push(format!("[aliases: {all_als}]"));
+            spec_vals.push(format!("{ctx}[aliases: {ctx:#}{all_als}{ctx}]{ctx:#}"));
         }
 
         spec_vals.join(" ")
diff --git a/src/bin/stdio-fixture.rs b/src/bin/stdio-fixture.rs
@@ -1,25 +1,105 @@
+use clap::{builder::PossibleValue, Arg, ArgAction, Command};
+
 fn main() {
     #[allow(unused_mut)]
-    let mut cmd = clap::Command::new("stdio-fixture")
+    let mut cmd = Command::new("stdio-fixture")
         .version("1.0")
         .long_version("1.0 - a2132c")
         .arg_required_else_help(true)
-        .subcommand(clap::Command::new("more"))
+        .subcommand(Command::new("more"))
+        .subcommand(
+            Command::new("test")
+                .visible_alias("do-stuff")
+                .long_about("Subcommand with one visible alias"),
+        )
+        .subcommand(
+            Command::new("test_2")
+                .visible_aliases(["do-other-stuff", "tests"])
+                .about("several visible aliases")
+                .long_about("Subcommand with multiple visible aliases"),
+        )
+        .subcommand(
+            Command::new("test_3")
+                .long_flag("test")
+                .about("several visible long flag aliases")
+                .visible_long_flag_aliases(["testing", "testall", "test_all"]),
+        )
+        .subcommand(
+            Command::new("test_4")
+                .short_flag('t')
+                .about("several visible short flag aliases")
+                .visible_short_flag_aliases(['q', 'w']),
+        )
+        .subcommand(
+            Command::new("test_5")
+                .short_flag('e')
+                .long_flag("test-hdr")
+                .about("all kinds of visible aliases")
+                .visible_aliases(["tests_4k"])
+                .visible_long_flag_aliases(["thetests", "t4k"])
+                .visible_short_flag_aliases(['r', 'y']),
+        )
         .arg(
-            clap::Arg::new("verbose")
+            Arg::new("verbose")
                 .long("verbose")
                 .help("log")
-                .action(clap::ArgAction::SetTrue)
+                .action(ArgAction::SetTrue)
                 .long_help("more log"),
+        )
+        .arg(
+            Arg::new("config")
+                .action(ArgAction::Set)
+                .help("Speed configuration")
+                .short('c')
+                .long("config")
+                .value_name("MODE")
+                .value_parser([
+                    PossibleValue::new("fast"),
+                    PossibleValue::new("slow").help("slower than fast"),
+                    PossibleValue::new("secret speed").hide(true),
+                ])
+                .default_value("fast"),
+        )
+        .arg(
+            Arg::new("name")
+                .action(ArgAction::Set)
+                .help("App name")
+                .long_help("Set the instance app name")
+                .value_name("NAME")
+                .visible_alias("app-name")
+                .default_value("clap"),
+        )
+        .arg(
+            Arg::new("fruits")
+                .short('f')
+                .visible_short_alias('b')
+                .action(ArgAction::Append)
+                .value_name("FRUITS")
+                .help("List of fruits")
+                .default_values(["apple", "banane", "orange"]),
         );
+    #[cfg(feature = "env")]
+    {
+        cmd = cmd.arg(
+            Arg::new("env_arg")
+                .help("Read from env var when arg is not present.")
+                .value_name("ENV")
+                .env("ENV_ARG"),
+        );
+    }
     #[cfg(feature = "color")]
     {
-        use clap::builder::styling;
-        const STYLES: styling::Styles = styling::Styles::styled()
-            .header(styling::AnsiColor::Green.on_default().bold())
-            .usage(styling::AnsiColor::Green.on_default().bold())
-            .literal(styling::AnsiColor::Blue.on_default().bold())
-            .placeholder(styling::AnsiColor::Cyan.on_default());
+        use clap::builder::styling::{AnsiColor, Styles};
+        const STYLES: Styles = Styles::styled()
+            .header(AnsiColor::Green.on_default().bold())
+            .error(AnsiColor::Red.on_default().bold())
+            .usage(AnsiColor::Green.on_default().bold().underline())
+            .literal(AnsiColor::Blue.on_default().bold())
+            .placeholder(AnsiColor::Cyan.on_default())
+            .valid(AnsiColor::Green.on_default())
+            .invalid(AnsiColor::Magenta.on_default().bold())
+            .context(AnsiColor::Yellow.on_default().dimmed())
+            .context_value(AnsiColor::Yellow.on_default().italic());
         cmd = cmd.styles(STYLES);
     }
     cmd.get_matches();
diff --git a/tests/ui/arg_required_else_help_stderr.toml b/tests/ui/arg_required_else_help_stderr.toml
@@ -3,14 +3,25 @@ args = []
 status.code = 2
 stdout = ""
 stderr = """
-Usage: stdio-fixture[EXE] [OPTIONS] [COMMAND]
+Usage: stdio-fixture[EXE] [OPTIONS] [NAME] [ENV] [COMMAND]
 
 Commands:
-  more  
-  help  Print this message or the help of the given subcommand(s)
+  more                    
+  test                    Subcommand with one visible alias [aliases: do-stuff]
+  test_2                  several visible aliases [aliases: do-other-stuff, tests]
+  test_3, --test          several visible long flag aliases
+  test_4, -t              several visible short flag aliases [aliases: -q, -w]
+  test_5, -e, --test-hdr  all kinds of visible aliases [aliases: -r, -y, tests_4k]
+  help                    Print this message or the help of the given subcommand(s)
+
+Arguments:
+  [NAME]  App name [default: clap] [aliases: --app-name]
+  [ENV]   Read from env var when arg is not present. [env: ENV_ARG=]
 
 Options:
-      --verbose  log
-  -h, --help     Print help (see more with '--help')
-  -V, --version  Print version
+      --verbose        log
+  -c, --config <MODE>  Speed configuration [default: fast] [possible values: fast, slow]
+  -f <FRUITS>          List of fruits [default: apple banane orange] [aliases: -b]
+  -h, --help           Print help (see more with '--help')
+  -V, --version        Print version
 """
diff --git a/tests/ui/error_stderr.toml b/tests/ui/error_stderr.toml
@@ -5,7 +5,9 @@ stdout = ""
 stderr = """
 error: unexpected argument '--unknown-argument' found
 
-Usage: stdio-fixture[EXE] [OPTIONS] [COMMAND]
+  tip: to pass '--unknown-argument' as a value, use '-- --unknown-argument'
+
+Usage: stdio-fixture[EXE] [OPTIONS] [NAME] [ENV] [COMMAND]
 
 For more information, try '--help'.
 """
diff --git a/tests/ui/h_flag_stdout.toml b/tests/ui/h_flag_stdout.toml
@@ -2,15 +2,26 @@ bin.name = "stdio-fixture"
 args = ["-h"]
 status.code = 0
 stdout = """
-Usage: stdio-fixture[EXE] [OPTIONS] [COMMAND]
+Usage: stdio-fixture[EXE] [OPTIONS] [NAME] [ENV] [COMMAND]
 
 Commands:
-  more  
-  help  Print this message or the help of the given subcommand(s)
+  more                    
+  test                    Subcommand with one visible alias [aliases: do-stuff]
+  test_2                  several visible aliases [aliases: do-other-stuff, tests]
+  test_3, --test          several visible long flag aliases
+  test_4, -t              several visible short flag aliases [aliases: -q, -w]
+  test_5, -e, --test-hdr  all kinds of visible aliases [aliases: -r, -y, tests_4k]
+  help                    Print this message or the help of the given subcommand(s)
+
+Arguments:
+  [NAME]  App name [default: clap] [aliases: --app-name]
+  [ENV]   Read from env var when arg is not present. [env: ENV_ARG=]
 
 Options:
-      --verbose  log
-  -h, --help     Print help (see more with '--help')
-  -V, --version  Print version
+      --verbose        log
+  -c, --config <MODE>  Speed configuration [default: fast] [possible values: fast, slow]
+  -f <FRUITS>          List of fruits [default: apple banane orange] [aliases: -b]
+  -h, --help           Print help (see more with '--help')
+  -V, --version        Print version
 """
 stderr = ""
diff --git a/tests/ui/help_cmd_stdout.toml b/tests/ui/help_cmd_stdout.toml
diff --git a/tests/ui/help_flag_stdout.toml b/tests/ui/help_flag_stdout.toml
