From c1c269b427ef02f10c86cb30d90fa160514e27a8 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Wed, 31 Aug 2022 14:16:49 -0500 Subject: [PATCH] fix(help): Clarify short vs long help In reviewing CLIs for #4132, I found some were providing helps on `-h` vs `--help` and figured that could be built directly into clap. I had considered not making this hint automatic but I figured the overhead of checking if long exists wouldn't be too bad. The code exists (no binary size increase) and just a simple iteration is probably not too slow compared to everything else. Fixes #1015 --- CHANGELOG.md | 1 + .../tests/snapshots/possible_values.bash.roff | 2 +- .../tests/snapshots/value_env.bash.roff | 2 +- src/builder/command.rs | 29 ++++++++++++++----- tests/builder/help.rs | 20 ++++++------- tests/builder/hidden_args.rs | 8 ++--- tests/derive/help.rs | 2 +- tests/ui/arg_required_else_help_stderr.toml | 2 +- tests/ui/h_flag_stdout.toml | 2 +- tests/ui/help_cmd_stdout.toml | 2 +- tests/ui/help_flag_stdout.toml | 2 +- 11 files changed, 44 insertions(+), 28 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d7b1189f120..0b63aad3e39 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -101,6 +101,7 @@ Deprecated - *(help)* Show all `[positional]` in usage - *(help)* Polish up subcommands by referring to them as commands - *(help)* Trim extra whitespace to avoid artifacts from different uses of templates +- *(help)* Hint to the user the difference between `-h` / `--help` when applicable (#4159) - *(version)* Use `Command::display_name` rather than `Command::bin_name` - *(parser)* Assert on unknown args when using external subcommands (#3703) - *(parser)* Always fill in `""` argument for external subcommands (#3263) diff --git a/clap_mangen/tests/snapshots/possible_values.bash.roff b/clap_mangen/tests/snapshots/possible_values.bash.roff index 10f9af3dc7d..d4be2d2c9af 100644 --- a/clap_mangen/tests/snapshots/possible_values.bash.roff +++ b/clap_mangen/tests/snapshots/possible_values.bash.roff @@ -25,7 +25,7 @@ slow: use the slow method .RE .TP /fB/-h/fR, /fB/-/-help/fR -Print help information +Print help information (use `/-h` for a summary) .TP [/fIpositional_choice/fR] Pick the Position you want the command to run in diff --git a/clap_mangen/tests/snapshots/value_env.bash.roff b/clap_mangen/tests/snapshots/value_env.bash.roff index a6ef6dddb13..7e8966198f4 100644 --- a/clap_mangen/tests/snapshots/value_env.bash.roff +++ b/clap_mangen/tests/snapshots/value_env.bash.roff @@ -15,4 +15,4 @@ May also be specified with the /fBCONFIG_FILE/fR environment variable. .RE .TP /fB/-h/fR, /fB/-/-help/fR -Print help information +Print help information (use `/-h` for a summary) diff --git a/src/builder/command.rs b/src/builder/command.rs index d3019544416..afe15113db8 100644 --- a/src/builder/command.rs +++ b/src/builder/command.rs @@ -102,6 +102,7 @@ pub struct Command { subcommand_value_name: Option, subcommand_heading: Option, external_value_parser: Option, + long_help_exists: bool, } /// # Basic API @@ -4124,13 +4125,21 @@ impl Command { pub(crate) fn _check_help_and_version(&mut self) { debug!("Command::_check_help_and_version:{}", self.name,); + self.long_help_exists = self.long_help_exists_(); + if !self.is_disable_help_flag_set() { debug!("Command::_check_help_and_version: Building default --help"); - let arg = Arg::new(Id::HELP) + let mut arg = Arg::new(Id::HELP) .short('h') .long("help") - .action(ArgAction::Help) - .help("Print help information"); + .action(ArgAction::Help); + if self.long_help_exists { + arg = arg + .help("Print help information (use `--help` for more detail)") + .long_help("Print help information (use `-h` for a summary)"); + } else { + arg = arg.help("Print help information"); + } // Avoiding `arg_internal` to not be sensitive to `next_help_heading` / // `next_display_order` self.args.push(arg); @@ -4454,10 +4463,10 @@ impl Command { debug!( "Command::write_help_err: {}, use_long={:?}", self.get_display_name().unwrap_or_else(|| self.get_name()), - use_long && self.use_long_help(), + use_long && self.long_help_exists(), ); - use_long = use_long && self.use_long_help(); + use_long = use_long && self.long_help_exists(); let usage = Usage::new(self); let mut styled = StyledStr::new(); @@ -4473,8 +4482,13 @@ impl Command { styled } - pub(crate) fn use_long_help(&self) -> bool { - debug!("Command::use_long_help"); + pub(crate) fn long_help_exists(&self) -> bool { + debug!("Command::long_help_exists: {}", self.long_help_exists); + self.long_help_exists + } + + fn long_help_exists_(&self) -> bool { + debug!("Command::long_help_exists"); // In this case, both must be checked. This allows the retention of // original formatting, but also ensures that the actual -h or --help // specified by the user is sent through. If hide_short_help is not included, @@ -4545,6 +4559,7 @@ impl Default for Command { subcommand_value_name: Default::default(), subcommand_heading: Default::default(), external_value_parser: Default::default(), + long_help_exists: false, } } } diff --git a/tests/builder/help.rs b/tests/builder/help.rs index 73d2c68e01e..32e9f2415ac 100644 --- a/tests/builder/help.rs +++ b/tests/builder/help.rs @@ -272,7 +272,7 @@ Usage: clap-test Options: - -h, --help Print help information + -h, --help Print help information (use `--help` for more detail) -V, --version Print version information some text that comes after the help @@ -288,7 +288,7 @@ Usage: Options: -h, --help - Print help information + Print help information (use `-h` for a summary) -V, --version Print version information @@ -494,7 +494,7 @@ Options: - second: short help -h, --help - Print help information + Print help information (use `-h` for a summary) "; let cmd = Command::new("test") .term_width(67) @@ -678,7 +678,7 @@ Options: A coffeehouse, coffee shop, or café. -h, --help - Print help information + Print help information (use `-h` for a summary) -V, --version Print version information @@ -1021,7 +1021,7 @@ Arguments: Options: -h, --help - Print help information + Print help information (use `-h` for a summary) -V, --version Print version information @@ -1743,7 +1743,7 @@ Usage: test [OPTIONS] --song --song-volume Options: - -h, --help Print help information + -h, --help Print help information (use `--help` for more detail) -V, --version Print version information OVERRIDE SPECIAL: @@ -1796,7 +1796,7 @@ Usage: Options: -h, --help - Print help information + Print help information (use `-h` for a summary) -V, --version Print version information @@ -1820,7 +1820,7 @@ Usage: ctest foo Options: - -h, --help Print help information + -h, --help Print help information (use `--help` for more detail) -V, --version Print version information "; @@ -1847,7 +1847,7 @@ Arguments: Options: -f - -h, --help Print help information + -h, --help Print help information (use `--help` for more detail) "; let cmd = Command::new("demo") @@ -2006,7 +2006,7 @@ Options: and on, so I'll stop now. -h, --help - Print help information + Print help information (use `-h` for a summary) "; let cmd = Command::new("prog").arg( diff --git a/tests/builder/hidden_args.rs b/tests/builder/hidden_args.rs index 836fc9ede8b..49bb3ccb2d4 100644 --- a/tests/builder/hidden_args.rs +++ b/tests/builder/hidden_args.rs @@ -40,7 +40,7 @@ Usage: Options: -v, --visible This text should be visible - -h, --help Print help information + -h, --help Print help information (use `--help` for more detail) -V, --version Print version information "; @@ -86,7 +86,7 @@ Options: This text should be visible -h, --help - Print help information + Print help information (use `-h` for a summary) -V, --version Print version information @@ -125,7 +125,7 @@ Options: This text should be visible -h, --help - Print help information + Print help information (use `-h` for a summary) -V, --version Print version information @@ -164,7 +164,7 @@ Usage: Options: -c, --config Some help text describing the --config arg -v, --visible This text should be visible - -h, --help Print help information + -h, --help Print help information (use `--help` for more detail) -V, --version Print version information "; diff --git a/tests/derive/help.rs b/tests/derive/help.rs index 30ad6f1eb0b..293dbb84139 100644 --- a/tests/derive/help.rs +++ b/tests/derive/help.rs @@ -414,7 +414,7 @@ Arguments: Options: -h, --help - Print help information + Print help information (use `-h` for a summary) "; /// Application help diff --git a/tests/ui/arg_required_else_help_stderr.toml b/tests/ui/arg_required_else_help_stderr.toml index a8cdbc840e0..50db4b20d14 100644 --- a/tests/ui/arg_required_else_help_stderr.toml +++ b/tests/ui/arg_required_else_help_stderr.toml @@ -14,6 +14,6 @@ Commands: Options: --verbose log - -h, --help Print help information + -h, --help Print help information (use `--help` for more detail) -V, --version Print version information """ diff --git a/tests/ui/h_flag_stdout.toml b/tests/ui/h_flag_stdout.toml index 645c27fdd4b..f858340aae5 100644 --- a/tests/ui/h_flag_stdout.toml +++ b/tests/ui/h_flag_stdout.toml @@ -13,7 +13,7 @@ Commands: Options: --verbose log - -h, --help Print help information + -h, --help Print help information (use `--help` for more detail) -V, --version Print version information """ stderr = "" diff --git a/tests/ui/help_cmd_stdout.toml b/tests/ui/help_cmd_stdout.toml index 60f1a2540b4..a64c593a4f3 100644 --- a/tests/ui/help_cmd_stdout.toml +++ b/tests/ui/help_cmd_stdout.toml @@ -18,7 +18,7 @@ Options: more log -h, --help - Print help information + Print help information (use `-h` for a summary) -V, --version Print version information diff --git a/tests/ui/help_flag_stdout.toml b/tests/ui/help_flag_stdout.toml index f4ab5c1f66a..b4d37a72290 100644 --- a/tests/ui/help_flag_stdout.toml +++ b/tests/ui/help_flag_stdout.toml @@ -18,7 +18,7 @@ Options: more log -h, --help - Print help information + Print help information (use `-h` for a summary) -V, --version Print version information