diff --git a/clap_builder/src/builder/arg.rs b/clap_builder/src/builder/arg.rs index 60ea2cc3296..b542760376f 100644 --- a/clap_builder/src/builder/arg.rs +++ b/clap_builder/src/builder/arg.rs @@ -89,6 +89,8 @@ pub struct Arg { pub(crate) index: Option, pub(crate) help_heading: Option>, pub(crate) ext: Extensions, + pub(crate) aliases_heading: Option, + pub(crate) default_heading: Option, } /// # Basic API @@ -466,6 +468,40 @@ impl Arg { self } + /// Set arg aliases heading + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let m = Command::new("myprog") + /// .arg(Arg::new("test") + /// .long("test") + /// .action(ArgAction::SetTrue) + /// .visible_alias("b") + /// .aliases_heading("another heading") + /// ) + /// .print_help(); + ///``` + /// + /// will produce + /// + /// ```text + /// myprog + /// + /// Usage: myprog [OPTIONS] + /// + /// Options: + /// --test [b: --b] + /// -h, --help Print help + /// ``` + #[must_use] + pub fn aliases_heading(mut self, heading: impl IntoResettable) -> Self { + self.aliases_heading = heading.into_resettable().into_option(); + self + } + /// Specifies the index of a positional argument **starting at** 1. /// ///
@@ -1855,6 +1891,38 @@ impl Arg { } } + /// # Examples + /// + /// First we use the default value without providing any value at runtime. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, parser::ValueSource}; + /// Command::new("prog") + /// .arg(Arg::new("opt") + /// .long("myopt") + /// .default_value("myval") + /// .default_heading("another default")) + /// .print_help() + /// .unwrap() + ///``` + /// + /// get result: + /// + /// ```text + /// Usage: prog [OPTIONS] + /// + /// Options: + /// --myopt [default: myval] + /// -h, --help Print help + /// ``` + #[inline] + #[must_use] + pub fn default_heading(mut self, heading: impl IntoResettable) -> Self { + self.default_heading = heading.into_resettable().into_option(); + self + } + #[inline] #[must_use] #[doc(hidden)] @@ -4159,6 +4227,18 @@ impl Arg { } } + /// Get aliases heading + #[inline] + pub fn get_aliases_heading(&self) -> Option<&str> { + self.aliases_heading.as_deref() + } + + /// Get default heading + #[inline] + pub fn get_default_heading(&self) -> Option<&str> { + self.default_heading.as_deref() + } + /// Get *all* short aliases for this argument, if any, both visible and hidden. #[inline] pub fn get_all_short_aliases(&self) -> Option> { diff --git a/clap_builder/src/builder/command.rs b/clap_builder/src/builder/command.rs index 5ac6a1d0b93..16444f8a0a6 100644 --- a/clap_builder/src/builder/command.rs +++ b/clap_builder/src/builder/command.rs @@ -104,6 +104,7 @@ pub struct Command { current_disp_ord: Option, subcommand_value_name: Option, subcommand_heading: Option, + aliases_heading: Option, external_value_parser: Option, long_help_exists: bool, deferred: Option Command>, @@ -2275,6 +2276,46 @@ impl Command { self } + /// Sets the aliases heading used for subcommands when printing usage and help. + /// + /// By default, this is "COMMAND". + /// + /// See also [`Command::subcommand_help_heading`] + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg}; + /// Command::new("myprog") + /// .subcommand(Command::new("sub1")) + /// .subcommand_aliases_heading("another aliases") + /// .print_help() + /// # ; + /// ``` + /// + /// will produce + /// + /// ```text + /// myprog + /// + /// Usage: myprog [COMMAND] + /// + /// Commands: + /// help Print this message or the help of the given subcommand(s) + /// sub1 [another aliases: sub2] + /// + /// Options: + /// -h, --help Print help + /// -V, --version Print version + /// ``` + #[must_use] + #[cfg(feature = "help")] + pub fn subcommand_aliases_heading(mut self, s: impl IntoResettable) -> Self { + self.aliases_heading = s.into_resettable().into_option(); + self + } + #[inline] #[must_use] pub(crate) fn setting(mut self, setting: AppSettings) -> Self { @@ -3873,6 +3914,12 @@ impl Command { } } + /// Return aliases heading + #[inline] + pub fn get_subcommand_aliases_heading(&self) -> Option<&str> { + self.aliases_heading.as_deref() + } + /// Return the current `Styles` for the `Command` #[inline] pub fn get_styles(&self) -> &Styles { @@ -5187,6 +5234,7 @@ impl Default for Command { #[cfg(feature = "unstable-ext")] ext: Default::default(), app_ext: Default::default(), + aliases_heading: Default::default(), } } } diff --git a/clap_builder/src/output/help_template.rs b/clap_builder/src/output/help_template.rs index c954f5cb2a1..5475ec08098 100644 --- a/clap_builder/src/output/help_template.rs +++ b/clap_builder/src/output/help_template.rs @@ -805,7 +805,8 @@ impl HelpTemplate<'_, '_> { .join(" "); spec_vals.push(format!( - "{ctx}[default: {ctx:#}{ctx_val}{dvs}{ctx_val:#}{ctx}]{ctx:#}" + "{ctx}[{}: {ctx:#}{ctx_val}{dvs}{ctx_val:#}{ctx}]{ctx:#}", + a.get_default_heading().unwrap_or("default") )); } @@ -832,7 +833,8 @@ impl HelpTemplate<'_, '_> { if !als.is_empty() { let als = als.join(&val_sep); - spec_vals.push(format!("{ctx}[aliases: {ctx:#}{als}{ctx}]{ctx:#}")); + let help_heading = a.get_aliases_heading().unwrap_or("aliases"); + spec_vals.push(format!("{ctx}[{help_heading}: {ctx:#}{als}{ctx}]{ctx:#}")); } if !a.is_hide_possible_values_set() && !self.use_long_pv(a) { @@ -1041,7 +1043,10 @@ impl HelpTemplate<'_, '_> { "HelpTemplate::spec_vals: Found long flag aliases...{:?}", a.get_all_long_flag_aliases().collect::>() ); - spec_vals.push(format!("{ctx}[aliases: {ctx:#}{all_als}{ctx}]{ctx:#}")); + let help_heading = a.get_subcommand_aliases_heading().unwrap_or("aliases"); + spec_vals.push(format!( + "{ctx}[{help_heading}: {ctx:#}{all_als}{ctx}]{ctx:#}", + )); } spec_vals.join(" ")