From 33caf49793a54737fd55e34b81f6bff943a02bbc Mon Sep 17 00:00:00 2001 From: pretzelhammer <7769424+pretzelhammer@users.noreply.github.com> Date: Thu, 24 Sep 2020 17:49:12 -0400 Subject: [PATCH 1/2] api(App): Adds help_about method to App. Help about text is now customizable and propagates to subcommands. Closes #2080. --- src/build/app/mod.rs | 35 +++++++++- tests/help.rs | 152 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 184 insertions(+), 3 deletions(-) diff --git a/src/build/app/mod.rs b/src/build/app/mod.rs index 10ee2c53..f4d7f908 100644 --- a/src/build/app/mod.rs +++ b/src/build/app/mod.rs @@ -83,6 +83,7 @@ pub struct App<'help> { pub(crate) long_version: Option<&'help str>, pub(crate) about: Option<&'help str>, pub(crate) long_about: Option<&'help str>, + pub(crate) help_about: Option<&'help str>, pub(crate) before_help: Option<&'help str>, pub(crate) before_long_help: Option<&'help str>, pub(crate) after_help: Option<&'help str>, @@ -420,6 +421,29 @@ impl<'help> App<'help> { self } + /// Sets the help text for the auto-generated help argument and subcommand. + /// + /// By default clap sets this to "Prints help information" for the help + /// argument and "Prints this message or the help of the given subcommand(s)" + /// for the help subcommand but if you're using a different convention + /// for your help messages and would prefer a different phrasing you can + /// override it. + /// + /// **NOTE:** This setting propagates to subcommands. + /// + /// # Examples + /// + /// ```no_run + /// # use clap::App; + /// App::new("myprog") + /// .help_about("Print help information") // Impertive tone + /// # ; + /// ``` + pub fn help_about>(mut self, help_about: S) -> Self { + self.help_about = Some(help_about.into()); + self + } + /// (Re)Sets the program's name. This will be displayed when displaying help /// or version messages. /// @@ -2247,6 +2271,9 @@ impl<'help> App<'help> { $sc.g_settings = $sc.g_settings | $_self.g_settings; $sc.term_w = $_self.term_w; $sc.max_w = $_self.max_w; + if $sc.help_about.is_none() && $_self.help_about.is_some() { + $sc.help_about = $_self.help_about.clone(); + } } { // FIXME: This doesn't belong here at all. @@ -2299,7 +2326,7 @@ impl<'help> App<'help> { debug!("App::_create_help_and_version: Building --help"); let mut help = Arg::new("help") .long("help") - .about("Prints help information"); + .about(self.help_about.unwrap_or("Prints help information")); if !self.args.args.iter().any(|x| x.short == Some('h')) { help = help.short('h'); } @@ -2333,8 +2360,10 @@ impl<'help> App<'help> { { debug!("App::_create_help_and_version: Building help"); self.subcommands.push( - App::new("help") - .about("Prints this message or the help of the given subcommand(s)"), + App::new("help").about( + self.help_about + .unwrap_or("Prints this message or the help of the given subcommand(s)"), + ), ); } } diff --git a/tests/help.rs b/tests/help.rs index ce2e3fe5..a23fd3f8 100644 --- a/tests/help.rs +++ b/tests/help.rs @@ -1825,3 +1825,155 @@ fn after_help_no_args() { assert_eq!(help, AFTER_HELP_NO_ARGS); } + +static HELP_ABOUT: &str = "myapp 1.0 + +USAGE: + myapp + +FLAGS: + -h, --help Print custom help about text + -V, --version Prints version information"; + +static HELP_ABOUT_MULTI_SC: &str = "myapp-subcmd-multi 1.0 + +USAGE: + myapp subcmd multi + +FLAGS: + -h, --help Print custom help about text + -V, --version Prints version information"; + +static HELP_ABOUT_MULTI_SC_OVERRIDE: &str = "myapp-subcmd-multi 1.0 + +USAGE: + myapp subcmd multi + +FLAGS: + -h, --help Print custom help about text from multi + -V, --version Prints version information"; + +#[test] +fn help_about_short_flag() { + let app = App::new("myapp") + .version("1.0") + .help_about("Print custom help about text"); + + assert!(utils::compare_output(app, "myapp -h", HELP_ABOUT, false)); +} + +#[test] +fn help_about_long_flag() { + let app = App::new("myapp") + .version("1.0") + .help_about("Print custom help about text"); + + assert!(utils::compare_output( + app, + "myapp --help", + HELP_ABOUT, + false + )); +} + +#[test] +fn help_about_multi_subcmd() { + let app = App::new("myapp") + .help_about("Print custom help about text") + .subcommand(App::new("subcmd").subcommand(App::new("multi").version("1.0"))); + + assert!(utils::compare_output( + app, + "myapp help subcmd multi", + HELP_ABOUT_MULTI_SC, + false + )); +} + +#[test] +fn help_about_multi_subcmd_short_flag() { + let app = App::new("myapp") + .help_about("Print custom help about text") + .subcommand(App::new("subcmd").subcommand(App::new("multi").version("1.0"))); + + assert!(utils::compare_output( + app, + "myapp subcmd multi -h", + HELP_ABOUT_MULTI_SC, + false + )); +} + +#[test] +fn help_about_multi_subcmd_long_flag() { + let app = App::new("myapp") + .help_about("Print custom help about text") + .subcommand(App::new("subcmd").subcommand(App::new("multi").version("1.0"))); + + assert!(utils::compare_output( + app, + "myapp subcmd multi --help", + HELP_ABOUT_MULTI_SC, + false + )); +} + +#[test] +fn help_about_multi_subcmd_override() { + let app = App::new("myapp") + .help_about("Print custom help about text") + .subcommand( + App::new("subcmd").subcommand( + App::new("multi") + .version("1.0") + .help_about("Print custom help about text from multi"), + ), + ); + + assert!(utils::compare_output( + app, + "myapp help subcmd multi", + HELP_ABOUT_MULTI_SC_OVERRIDE, + false + )); +} + +#[test] +fn help_about_multi_subcmd_override_short_flag() { + let app = App::new("myapp") + .help_about("Print custom help about text") + .subcommand( + App::new("subcmd").subcommand( + App::new("multi") + .version("1.0") + .help_about("Print custom help about text from multi"), + ), + ); + + assert!(utils::compare_output( + app, + "myapp subcmd multi -h", + HELP_ABOUT_MULTI_SC_OVERRIDE, + false + )); +} + +#[test] +fn help_about_multi_subcmd_override_long_flag() { + let app = App::new("myapp") + .help_about("Print custom help about text") + .subcommand( + App::new("subcmd").subcommand( + App::new("multi") + .version("1.0") + .help_about("Print custom help about text from multi"), + ), + ); + + assert!(utils::compare_output( + app, + "myapp subcmd multi --help", + HELP_ABOUT_MULTI_SC_OVERRIDE, + false + )); +} From 523729d3fca89cd9f310d2e10ce2d9a5e46978ad Mon Sep 17 00:00:00 2001 From: pretzelhammer <7769424+pretzelhammer@users.noreply.github.com> Date: Fri, 25 Sep 2020 09:06:10 -0400 Subject: [PATCH 2/2] api(App): Adds version_about method to App. Version about text is now customizable and propagates to subcommands. Closes #1640. --- src/build/app/mod.rs | 27 +++++++- tests/help.rs | 152 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 178 insertions(+), 1 deletion(-) diff --git a/src/build/app/mod.rs b/src/build/app/mod.rs index f4d7f908..253ca9b6 100644 --- a/src/build/app/mod.rs +++ b/src/build/app/mod.rs @@ -84,6 +84,7 @@ pub struct App<'help> { pub(crate) about: Option<&'help str>, pub(crate) long_about: Option<&'help str>, pub(crate) help_about: Option<&'help str>, + pub(crate) version_about: Option<&'help str>, pub(crate) before_help: Option<&'help str>, pub(crate) before_long_help: Option<&'help str>, pub(crate) after_help: Option<&'help str>, @@ -444,6 +445,27 @@ impl<'help> App<'help> { self } + /// Sets the help text for the auto-generated version argument. + /// + /// By default clap sets this to "Prints versoin information" but if + /// you're using a different convention for your help messages and + /// would prefer a different phrasing you can override it. + /// + /// **NOTE:** This setting propagates to subcommands. + /// + /// # Examples + /// + /// ```no_run + /// # use clap::App; + /// App::new("myprog") + /// .version_about("Print version information") // Impertive tone + /// # ; + /// ``` + pub fn version_about>(mut self, version_about: S) -> Self { + self.version_about = Some(version_about.into()); + self + } + /// (Re)Sets the program's name. This will be displayed when displaying help /// or version messages. /// @@ -2274,6 +2296,9 @@ impl<'help> App<'help> { if $sc.help_about.is_none() && $_self.help_about.is_some() { $sc.help_about = $_self.help_about.clone(); } + if $sc.version_about.is_none() && $_self.version_about.is_some() { + $sc.version_about = $_self.version_about.clone(); + } } { // FIXME: This doesn't belong here at all. @@ -2347,7 +2372,7 @@ impl<'help> App<'help> { debug!("App::_create_help_and_version: Building --version"); let mut version = Arg::new("version") .long("version") - .about("Prints version information"); + .about(self.version_about.unwrap_or("Prints version information")); if !self.args.args.iter().any(|x| x.short == Some('V')) { version = version.short('V'); } diff --git a/tests/help.rs b/tests/help.rs index a23fd3f8..33da7251 100644 --- a/tests/help.rs +++ b/tests/help.rs @@ -1977,3 +1977,155 @@ fn help_about_multi_subcmd_override_long_flag() { false )); } + +static VERSION_ABOUT: &str = "myapp 1.0 + +USAGE: + myapp + +FLAGS: + -h, --help Prints help information + -V, --version Print custom version about text"; + +static VERSION_ABOUT_MULTI_SC: &str = "myapp-subcmd-multi 1.0 + +USAGE: + myapp subcmd multi + +FLAGS: + -h, --help Prints help information + -V, --version Print custom version about text"; + +static VERSION_ABOUT_MULTI_SC_OVERRIDE: &str = "myapp-subcmd-multi 1.0 + +USAGE: + myapp subcmd multi + +FLAGS: + -h, --help Prints help information + -V, --version Print custom version about text from multi"; + +#[test] +fn version_about_short_flag() { + let app = App::new("myapp") + .version("1.0") + .version_about("Print custom version about text"); + + assert!(utils::compare_output(app, "myapp -h", VERSION_ABOUT, false)); +} + +#[test] +fn version_about_long_flag() { + let app = App::new("myapp") + .version("1.0") + .version_about("Print custom version about text"); + + assert!(utils::compare_output( + app, + "myapp --help", + VERSION_ABOUT, + false + )); +} + +#[test] +fn version_about_multi_subcmd() { + let app = App::new("myapp") + .version_about("Print custom version about text") + .subcommand(App::new("subcmd").subcommand(App::new("multi").version("1.0"))); + + assert!(utils::compare_output( + app, + "myapp help subcmd multi", + VERSION_ABOUT_MULTI_SC, + false + )); +} + +#[test] +fn version_about_multi_subcmd_short_flag() { + let app = App::new("myapp") + .version_about("Print custom version about text") + .subcommand(App::new("subcmd").subcommand(App::new("multi").version("1.0"))); + + assert!(utils::compare_output( + app, + "myapp subcmd multi -h", + VERSION_ABOUT_MULTI_SC, + false + )); +} + +#[test] +fn version_about_multi_subcmd_long_flag() { + let app = App::new("myapp") + .version_about("Print custom version about text") + .subcommand(App::new("subcmd").subcommand(App::new("multi").version("1.0"))); + + assert!(utils::compare_output( + app, + "myapp subcmd multi --help", + VERSION_ABOUT_MULTI_SC, + false + )); +} + +#[test] +fn version_about_multi_subcmd_override() { + let app = App::new("myapp") + .version_about("Print custom version about text") + .subcommand( + App::new("subcmd").subcommand( + App::new("multi") + .version("1.0") + .version_about("Print custom version about text from multi"), + ), + ); + + assert!(utils::compare_output( + app, + "myapp help subcmd multi", + VERSION_ABOUT_MULTI_SC_OVERRIDE, + false + )); +} + +#[test] +fn version_about_multi_subcmd_override_short_flag() { + let app = App::new("myapp") + .version_about("Print custom version about text") + .subcommand( + App::new("subcmd").subcommand( + App::new("multi") + .version("1.0") + .version_about("Print custom version about text from multi"), + ), + ); + + assert!(utils::compare_output( + app, + "myapp subcmd multi -h", + VERSION_ABOUT_MULTI_SC_OVERRIDE, + false + )); +} + +#[test] +fn version_about_multi_subcmd_override_long_flag() { + let app = App::new("myapp") + .version_about("Print custom version about text") + .subcommand( + App::new("subcmd").subcommand( + App::new("multi") + .version("1.0") + .version_about("Print custom version about text from multi"), + ), + ); + + assert!(utils::compare_output( + app, + "myapp subcmd multi --help", + VERSION_ABOUT_MULTI_SC_OVERRIDE, + false + )); +}