feat(help): Allow flattening usage

clap-rs · Nov 9, 2023 · caf5cdc · caf5cdc
1 parent a1fd922
commit caf5cdc
Show file tree

Hide file tree

Showing 4 changed files with 73 additions and 15 deletions.
diff --git 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
@@ -73,7 +73,10 @@ Default subcommand:
 ```console
 $ git-derive stash -h
 Usage: git-derive[EXE] stash [OPTIONS]
-       git-derive[EXE] stash <COMMAND>
+       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
@@ -71,7 +71,10 @@ Default subcommand:
 ```console
 $ git stash -h
 Usage: git[EXE] stash [OPTIONS]
-       git[EXE] stash <COMMAND>
+       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
@@ -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 <parent> [COMMAND]
+Usage: parent --parent <parent>
+       parent --parent <parent> test --child <child>
+       parent --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] <COMMAND>
+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 <COMMAND>
+       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