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] 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 + )); +}