From caf5cdcfa04d92bdea0dcd924296990425212b91 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Thu, 9 Nov 2023 12:46:16 -0600 Subject: [PATCH] feat(help): Allow flattening usage --- clap_builder/src/output/usage.rs | 24 ++++++++++++-- examples/git-derive.md | 5 ++- examples/git.md | 5 ++- tests/builder/help.rs | 54 +++++++++++++++++++++++++------- 4 files changed, 73 insertions(+), 15 deletions(-) diff --git a/clap_builder/src/output/usage.rs b/clap_builder/src/output/usage.rs index d4e932ce..0b2ff3b9 100644 --- a/clap_builder/src/output/usage.rs +++ b/clap_builder/src/output/usage.rs @@ -101,9 +101,29 @@ impl<'cmd> Usage<'cmd> { // Creates a usage string for display in help messages (i.e. not for errors) fn write_help_usage(&self, styled: &mut StyledStr) { debug!("Usage::write_help_usage"); + use std::fmt::Write; - self.write_arg_usage(styled, &[], true); - self.write_subcommand_usage(styled); + if self.cmd.is_flatten_help_set() { + if !self.cmd.is_subcommand_required_set() + || self.cmd.is_args_conflicts_with_subcommands_set() + { + self.write_arg_usage(styled, &[], true); + styled.trim_end(); + let _ = write!(styled, "{}", USAGE_SEP); + } + let mut cmd = self.cmd.clone(); + cmd.build(); + for (i, sub) in cmd.get_subcommands().enumerate() { + if i != 0 { + styled.trim_end(); + let _ = write!(styled, "{}", USAGE_SEP); + } + Usage::new(sub).write_usage_no_title(styled, &[]); + } + } else { + self.write_arg_usage(styled, &[], true); + self.write_subcommand_usage(styled); + } } // Creates a context aware usage string, or "smart usage" from currently used diff --git a/examples/git-derive.md b/examples/git-derive.md index 57edb612..afc4d0c8 100644 --- a/examples/git-derive.md +++ b/examples/git-derive.md @@ -73,7 +73,10 @@ Default subcommand: ```console $ git-derive stash -h Usage: git-derive[EXE] stash [OPTIONS] - git-derive[EXE] stash + git-derive[EXE] stash push [OPTIONS] + git-derive[EXE] stash pop [STASH] + git-derive[EXE] stash apply [STASH] + git-derive[EXE] stash help [COMMAND]... Commands: push diff --git a/examples/git.md b/examples/git.md index d90b2e8e..66e8baae 100644 --- a/examples/git.md +++ b/examples/git.md @@ -71,7 +71,10 @@ Default subcommand: ```console $ git stash -h Usage: git[EXE] stash [OPTIONS] - git[EXE] stash + git[EXE] stash push [OPTIONS] + git[EXE] stash pop [STASH] + git[EXE] stash apply [STASH] + git[EXE] stash help [COMMAND]... Commands: push diff --git a/tests/builder/help.rs b/tests/builder/help.rs index eefc188f..22cbaab5 100644 --- a/tests/builder/help.rs +++ b/tests/builder/help.rs @@ -2952,7 +2952,9 @@ fn display_name_subcommand_explicit() { #[test] fn flatten_basic() { static EXPECTED: &str = "\ -Usage: parent [OPTIONS] [COMMAND] +Usage: parent [OPTIONS] + parent test [OPTIONS] + parent help [COMMAND]... Commands: test some @@ -2976,7 +2978,9 @@ Options: #[test] fn flatten_short_help() { static EXPECTED: &str = "\ -Usage: parent [OPTIONS] [COMMAND] +Usage: parent [OPTIONS] + parent test [OPTIONS] + parent help [COMMAND]... Commands: test some @@ -3006,7 +3010,9 @@ Options: #[test] fn flatten_long_help() { static EXPECTED: &str = "\ -Usage: parent [OPTIONS] [COMMAND] +Usage: parent [OPTIONS] + parent test [OPTIONS] + parent help [COMMAND]... Commands: test some @@ -3039,7 +3045,9 @@ Options: #[test] fn flatten_help_cmd() { static EXPECTED: &str = "\ -Usage: parent [OPTIONS] [COMMAND] +Usage: parent [OPTIONS] + parent test [OPTIONS] + parent help [COMMAND]... Commands: test some @@ -3072,7 +3080,9 @@ Options: #[test] fn flatten_with_global() { static EXPECTED: &str = "\ -Usage: parent [OPTIONS] [COMMAND] +Usage: parent [OPTIONS] + parent test [OPTIONS] + parent help [COMMAND]... Commands: test some @@ -3096,7 +3106,9 @@ Options: #[test] fn flatten_arg_required() { static EXPECTED: &str = "\ -Usage: parent --parent [COMMAND] +Usage: parent --parent + parent --parent test --child + parent --parent help [COMMAND]... Commands: test some @@ -3120,7 +3132,9 @@ Options: #[test] fn flatten_with_external_subcommand() { static EXPECTED: &str = "\ -Usage: parent [OPTIONS] [COMMAND] +Usage: parent [OPTIONS] + parent test [OPTIONS] + parent help [COMMAND]... Commands: test some @@ -3160,7 +3174,8 @@ Options: #[test] fn flatten_with_subcommand_required() { static EXPECTED: &str = "\ -Usage: parent [OPTIONS] +Usage: parent test [OPTIONS] + parent help [COMMAND]... Commands: test some @@ -3186,7 +3201,8 @@ Options: fn flatten_with_args_conflicts_with_subcommands() { static EXPECTED: &str = "\ Usage: parent [OPTIONS] - parent + parent test [OPTIONS] + parent help [COMMAND]... Commands: test some @@ -3212,7 +3228,19 @@ Options: #[test] fn flatten_recursive() { static EXPECTED: &str = "\ -Usage: parent [OPTIONS] [COMMAND] +Usage: parent [OPTIONS] + parent child1 [OPTIONS] + parent child1 grandchild1 [OPTIONS] + parent child1 grandchild1 greatgrandchild1 [OPTIONS] + parent child1 grandchild1 greatgrandchild2 [OPTIONS] + parent child1 grandchild1 greatgrandchild3 [OPTIONS] + parent child1 grandchild1 help [COMMAND] + parent child1 grandchild2 [OPTIONS] + parent child1 grandchild3 [OPTIONS] + parent child1 help [COMMAND] + parent child2 [OPTIONS] + parent child3 [OPTIONS] + parent help [COMMAND]... Commands: child1 some 1 @@ -3280,7 +3308,11 @@ Options: #[test] fn flatten_not_recursive() { static EXPECTED: &str = "\ -Usage: parent [OPTIONS] [COMMAND] +Usage: parent [OPTIONS] + parent child1 [OPTIONS] [COMMAND] + parent child2 [OPTIONS] + parent child3 [OPTIONS] + parent help [COMMAND]... Commands: child1 some 1