feat(help): Allow flattening help

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

Hide file tree

Showing 4 changed files with 181 additions and 61 deletions.
diff --git a/clap_builder/src/output/help_template.rs b/clap_builder/src/output/help_template.rs
@@ -393,9 +393,11 @@ impl<'cmd, 'writer> HelpTemplate<'cmd, 'writer> {
             .filter_map(|arg| arg.get_help_heading())
             .collect::<FlatSet<_>>();
 
+        let flatten = self.cmd.is_flatten_help_set();
+
         let mut first = true;
 
-        if subcmds {
+        if subcmds && !flatten {
             if !first {
                 self.writer.push_str("\n\n");
             }
@@ -474,6 +476,60 @@ impl<'cmd, 'writer> HelpTemplate<'cmd, 'writer> {
                 }
             }
         }
+        if flatten {
+            let mut cmd = self.cmd.clone();
+            cmd.build();
+
+            let mut ord_v = Vec::new();
+            for subcommand in cmd
+                .get_subcommands()
+                .filter(|subcommand| should_show_subcommand(subcommand))
+            {
+                ord_v.push((
+                    subcommand.get_display_order(),
+                    subcommand.get_name(),
+                    subcommand,
+                ));
+            }
+            ord_v.sort_by(|a, b| (a.0, &a.1).cmp(&(b.0, &b.1)));
+            for (_, _, subcommand) in ord_v {
+                if !first {
+                    self.writer.push_str("\n\n");
+                }
+                first = false;
+
+                let heading = subcommand.get_usage_name_fallback();
+                let about = cmd
+                    .get_about()
+                    .or_else(|| cmd.get_long_about())
+                    .unwrap_or_default();
+
+                let _ = write!(
+                    self.writer,
+                    "{}{heading}:{}\n",
+                    header.render(),
+                    header.render_reset()
+                );
+                if !about.is_empty() {
+                    let _ = write!(self.writer, "{about}\n",);
+                }
+
+                let mut sub_help = HelpTemplate {
+                    writer: self.writer,
+                    cmd: subcommand,
+                    styles: self.styles,
+                    usage: self.usage,
+                    next_line_help: false,
+                    term_w: self.term_w,
+                    use_long: false,
+                };
+                let args = subcommand
+                    .get_arguments()
+                    .filter(|arg| should_show_arg(self.use_long, arg))
+                    .collect::<Vec<_>>();
+                sub_help.write_args(&args, heading, option_sort_key);
+            }
+        }
     }
 
     /// Sorts arguments by length and display order and write their help to the wrapped stream.

diff --git a/examples/git-derive.md b/examples/git-derive.md
@@ -78,16 +78,25 @@ Usage: git-derive[EXE] stash [OPTIONS]
        git-derive[EXE] stash apply [STASH]
        git-derive[EXE] stash help [COMMAND]...
 
-Commands:
-  push   
-  pop    
-  apply  
-  help   Print this message or the help of the given subcommand(s)
-
 Options:
   -m, --message <MESSAGE>  
   -h, --help               Print help
 
+git-derive[EXE] stash push:
+  -m, --message <MESSAGE>  
+  -h, --help               Print help
+
+git-derive[EXE] stash pop:
+  -h, --help   Print help
+  [STASH]  
+
+git-derive[EXE] stash apply:
+  -h, --help   Print help
+  [STASH]  
+
+git-derive[EXE] stash help:
+  [COMMAND]...  Print help for the subcommand(s)
+
 $ git-derive stash push -h
 Usage: git-derive[EXE] stash push [OPTIONS]
 

diff --git a/examples/git.md b/examples/git.md
@@ -76,16 +76,25 @@ Usage: git[EXE] stash [OPTIONS]
        git[EXE] stash apply [STASH]
        git[EXE] stash help [COMMAND]...
 
-Commands:
-  push   
-  pop    
-  apply  
-  help   Print this message or the help of the given subcommand(s)
-
 Options:
   -m, --message <MESSAGE>  
   -h, --help               Print help
 
+git[EXE] stash push:
+  -m, --message <MESSAGE>  
+  -h, --help               Print help
+
+git[EXE] stash pop:
+  -h, --help   Print help
+  [STASH]  
+
+git[EXE] stash apply:
+  -h, --help   Print help
+  [STASH]  
+
+git[EXE] stash help:
+  [COMMAND]...  Print help for the subcommand(s)
+
 $ git stash push -h
 Usage: git[EXE] stash push [OPTIONS]
 

diff --git a/tests/builder/help.rs b/tests/builder/help.rs
@@ -2956,13 +2956,16 @@ Usage: parent [OPTIONS]
        parent test [OPTIONS]
        parent help [COMMAND]...
 
-Commands:
-  test  some
-  help  Print this message or the help of the given subcommand(s)
-
 Options:
       --parent <parent>  
   -h, --help             Print help
+
+parent test:
+      --child <child>  
+  -h, --help           Print help
+
+parent help:
+  [COMMAND]...  Print help for the subcommand(s)
 ";
     let cmd = Command::new("parent")
         .flatten_help(true)
@@ -2982,13 +2985,16 @@ Usage: parent [OPTIONS]
        parent test [OPTIONS]
        parent help [COMMAND]...
 
-Commands:
-  test  some
-  help  Print this message or the help of the given subcommand(s)
-
 Options:
       --parent <parent>  foo
   -h, --help             Print help (see more with '--help')
+
+parent test:
+      --child <child>  foo
+  -h, --help           Print help (see more with '--help')
+
+parent help:
+  [COMMAND]...  Print help for the subcommand(s)
 ";
     let cmd = Command::new("parent")
         .flatten_help(true)
@@ -3014,16 +3020,19 @@ Usage: parent [OPTIONS]
        parent test [OPTIONS]
        parent help [COMMAND]...
 
-Commands:
-  test  some
-  help  Print this message or the help of the given subcommand(s)
-
 Options:
       --parent <parent>
           bar
 
   -h, --help
           Print help (see a summary with '-h')
+
+parent test:
+      --child <child>  foo
+  -h, --help           Print help (see more with '--help')
+
+parent help:
+  [COMMAND]...  Print help for the subcommand(s)
 ";
     let cmd = Command::new("parent")
         .flatten_help(true)
@@ -3049,16 +3058,19 @@ Usage: parent [OPTIONS]
        parent test [OPTIONS]
        parent help [COMMAND]...
 
-Commands:
-  test  some
-  help  Print this message or the help of the given subcommand(s)
-
 Options:
       --parent <parent>
           bar
 
   -h, --help
           Print help (see a summary with '-h')
+
+parent test:
+      --child <child>  foo
+  -h, --help           Print help (see more with '--help')
+
+parent help:
+  [COMMAND]...  Print help for the subcommand(s)
 ";
     let cmd = Command::new("parent")
         .flatten_help(true)
@@ -3084,13 +3096,17 @@ Usage: parent [OPTIONS]
        parent test [OPTIONS]
        parent help [COMMAND]...
 
-Commands:
-  test  some
-  help  Print this message or the help of the given subcommand(s)
-
 Options:
       --parent <parent>  
   -h, --help             Print help
+
+parent test:
+      --child <child>    
+      --parent <parent>  
+  -h, --help             Print help
+
+parent help:
+  [COMMAND]...  Print help for the subcommand(s)
 ";
     let cmd = Command::new("parent")
         .flatten_help(true)
@@ -3110,13 +3126,16 @@ Usage: parent --parent <parent>
        parent --parent <parent> test --child <child>
        parent --parent <parent> help [COMMAND]...
 
-Commands:
-  test  some
-  help  Print this message or the help of the given subcommand(s)
-
 Options:
       --parent <parent>  
   -h, --help             Print help
+
+parent --parent <parent> test:
+      --child <child>  
+  -h, --help           Print help
+
+parent --parent <parent> help:
+  [COMMAND]...  Print help for the subcommand(s)
 ";
     let cmd = Command::new("parent")
         .flatten_help(true)
@@ -3136,13 +3155,16 @@ Usage: parent [OPTIONS]
        parent test [OPTIONS]
        parent help [COMMAND]...
 
-Commands:
-  test  some
-  help  Print this message or the help of the given subcommand(s)
-
 Options:
       --parent <parent>  
   -h, --help             Print help
+
+parent test:
+      --child <child>  
+  -h, --help           Print help
+
+parent help:
+  [COMMAND]...  Print help for the subcommand(s)
 ";
     let cmd = Command::new("parent")
         .flatten_help(true)
@@ -3177,13 +3199,16 @@ fn flatten_with_subcommand_required() {
 Usage: parent test [OPTIONS]
        parent help [COMMAND]...
 
-Commands:
-  test  some
-  help  Print this message or the help of the given subcommand(s)
-
 Options:
       --parent <parent>  
   -h, --help             Print help
+
+parent test:
+      --child <child>  
+  -h, --help           Print help
+
+parent help:
+  [COMMAND]...  Print help for the subcommand(s)
 ";
     let cmd = Command::new("parent")
         .flatten_help(true)
@@ -3204,13 +3229,16 @@ Usage: parent [OPTIONS]
        parent test [OPTIONS]
        parent help [COMMAND]...
 
-Commands:
-  test  some
-  help  Print this message or the help of the given subcommand(s)
-
 Options:
       --parent <parent>  
   -h, --help             Print help
+
+parent test:
+      --child <child>  
+  -h, --help           Print help
+
+parent help:
+  [COMMAND]...  Print help for the subcommand(s)
 ";
     let cmd = Command::new("parent")
         .flatten_help(true)
@@ -3242,15 +3270,24 @@ Usage: parent [OPTIONS]
        parent child3 [OPTIONS]
        parent help [COMMAND]...
 
-Commands:
-  child1  some 1
-  child2  some 2
-  child3  some 3
-  help    Print this message or the help of the given subcommand(s)
-
 Options:
       --parent <parent>  
   -h, --help             Print help
+
+parent child1:
+      --child1 <child>  
+  -h, --help            Print help
+
+parent child2:
+      --child2 <child>  
+  -h, --help            Print help
+
+parent child3:
+      --child3 <child>  
+  -h, --help            Print help
+
+parent help:
+  [COMMAND]...  Print help for the subcommand(s)
 ";
     let cmd = Command::new("parent")
         .flatten_help(true)
@@ -3314,15 +3351,24 @@ Usage: parent [OPTIONS]
        parent child3 [OPTIONS]
        parent help [COMMAND]...
 
-Commands:
-  child1  some 1
-  child2  some 2
-  child3  some 3
-  help    Print this message or the help of the given subcommand(s)
-
 Options:
       --parent <parent>  
   -h, --help             Print help
+
+parent child1:
+      --child1 <child>  
+  -h, --help            Print help
+
+parent child2:
+      --child2 <child>  
+  -h, --help            Print help
+
+parent child3:
+      --child3 <child>  
+  -h, --help            Print help
+
+parent help:
+  [COMMAND]...  Print help for the subcommand(s)
 ";
     let cmd = Command::new("parent")
         .flatten_help(true)