feat(clap): Support custom help headings for subcommands

- Add support for custom help headings for subcommands
- Allows grouping subcommands under custom headings in help output
- Implement `get_subcommand_custom_help_headings` to collect custom headings
- Update `HelpTemplate` to iterate and display subcommands under custom headings
- Update `Usage` to include subcommands with custom headings in usage string

Author: gortavoher

clap_builder/src/builder/command.rs

@@ -27,6 +27,7 @@ use crate::output::fmt::Stream;
 use crate::output::{fmt::Colorizer, write_help, Usage};
 use crate::parser::{ArgMatcher, ArgMatches, Parser};
 use crate::util::ChildGraph;
+use crate::util::FlatSet;
 use crate::util::{color::ColorChoice, Id};
 use crate::{Error, INTERNAL_ERROR_MSG};
 
@@ -4427,6 +4428,12 @@ impl Command {
         }
     }
 
+    pub(crate) fn get_subcommand_custom_help_headings(&self) -> FlatSet<&str> {
+        self.get_subcommands()
+            .filter_map(|sc| sc.get_help_heading())
+            .collect::<FlatSet<_>>()
+    }
+
     fn _do_parse(
         &mut self,
         raw_args: &mut clap_lex::RawArgs,

clap_builder/src/output/help_template.rs

@@ -389,7 +389,7 @@ impl HelpTemplate<'_, '_> {
             .collect::<Vec<_>>();
         let subcmds = self.cmd.has_visible_subcommands();
 
-        let custom_headings = self
+        let custom_arg_headings = self
             .cmd
             .get_arguments()
             .filter_map(|arg| arg.get_help_heading())
@@ -434,8 +434,8 @@ impl HelpTemplate<'_, '_> {
             let _ = write!(self.writer, "{header}{help_heading}:{header:#}\n",);
             self.write_args(&non_pos, "Options", option_sort_key);
         }
-        if !custom_headings.is_empty() {
-            for heading in custom_headings {
+        if !custom_arg_headings.is_empty() {
+            for heading in custom_arg_headings {
                 let args = self
                     .cmd
                     .get_arguments()
@@ -891,50 +891,49 @@ impl HelpTemplate<'_, '_> {
             );
         }
 
-        let custom_headings = self
-            .cmd
-            .get_subcommands()
-            .filter_map(|cmd| cmd.get_help_heading())
-            .collect::<FlatSet<_>>();
+        let custom_sc_headings = self.cmd.get_subcommand_custom_help_headings();
 
-        // Write commands that have no custom heading
-        for (_, subcommand) in ord_v
-            .iter()
-            .filter(|item| item.1.get_help_heading().is_none())
-            .filter(|item| item.1.get_name() != "help")
-        {
-            self.write_flat_subcommand(subcommand, first);
-        }
+        // Commands under default heading
+        self.write_flat_subcommands_under_heading(&ord_v, None, first, false);
 
         // Commands under custom headings
-        if !custom_headings.is_empty() {
-            for heading in custom_headings {
-                let cmds = self
-                    .cmd
-                    .get_subcommands()
-                    .filter(|sc| {
-                        if let Some(help_heading) = sc.get_help_heading() {
-                            return help_heading == heading;
-                        }
-                        false
-                    })
-                    .filter(|sc| should_show_subcommand(sc))
-                    .collect::<Vec<_>>();
-
-                if !cmds.is_empty() {
-                    for (_, subcommand) in ord_v
-                        .clone()
-                        .into_iter()
-                        .filter(|item| item.1.get_help_heading() == Some(heading))
-                    {
-                        self.write_flat_subcommand(subcommand, first);
-                    }
-                }
-            }
+        for heading in custom_sc_headings {
+            self.write_flat_subcommands_under_heading(&ord_v, Some(heading), first, false);
         }
 
         // Help command
-        for (_, subcommand) in ord_v.iter().filter(|item| item.1.get_name() == "help") {
+        self.write_flat_subcommands_under_heading(&ord_v, None, first, true);
+    }
+
+    fn write_flat_subcommands_under_heading(
+        &mut self,
+        ord_v: &BTreeMap<(usize, &str), &Command>,
+        heading: Option<&str>,
+        first: &mut bool,
+        include_help: bool,
+    ) {
+        debug!("help_template::write subcommand under heading: `{heading:?}`");
+        // If a custom heading is set ignore the include help flag
+        let bt: Vec<(&(usize, &str), &&Command)> = if heading.is_some() {
+            ord_v
+                .iter()
+                .filter(|item| item.1.get_help_heading() == heading)
+                .collect()
+        } else {
+            ord_v
+                .iter()
+                .filter(|item| item.1.get_help_heading() == heading)
+                .filter(|item| {
+                    if include_help {
+                        item.1.get_name() == "help"
+                    } else {
+                        item.1.get_name() != "help"
+                    }
+                })
+                .collect()
+        };
+
+        for (_, subcommand) in bt {
             self.write_flat_subcommand(subcommand, first);
         }
     }
@@ -988,7 +987,6 @@ impl HelpTemplate<'_, '_> {
         debug!("HelpTemplate::write_subcommands");
         use std::fmt::Write as _;
         let literal = &self.styles.get_literal();
-        let header = &self.styles.get_header();
 
         // The shortest an arg can legally be is 2 (i.e. '-x')
         let mut longest = 2;
@@ -1006,9 +1004,6 @@ impl HelpTemplate<'_, '_> {
             if let Some(long) = subcommand.get_long_flag() {
                 let _ = write!(styled, ", {literal}--{long}{literal:#}",);
             }
-            // if subcommand.get_help_heading().is_some() {
-            //     has_heading = true;
-            // }
             longest = longest.max(styled.display_width());
             ord_v.insert((subcommand.get_display_order(), styled), subcommand);
         }
@@ -1017,63 +1012,44 @@ impl HelpTemplate<'_, '_> {
 
         let next_line_help = self.will_subcommands_wrap(cmd.get_subcommands(), longest);
 
-        let custom_headings = self
-            .cmd
-            .get_subcommands()
-            .filter_map(|cmd| cmd.get_help_heading())
-            .collect::<FlatSet<_>>();
+        let custom_sc_headings = self.cmd.get_subcommand_custom_help_headings();
+
+        // User commands without heading
+        self.write_subcommands_under_heading(&ord_v, None, next_line_help, longest);
+
+        // User commands with heading
+        for heading in custom_sc_headings {
+            self.write_subcommands_under_heading(&ord_v, Some(heading), next_line_help, longest);
+        }
+    }
+
+    fn write_subcommands_under_heading(
+        &mut self,
+        ord_v: &BTreeMap<(usize, StyledStr), &Command>,
+        heading: Option<&str>,
+        next_line_help: bool,
+        longest: usize,
+    ) {
+        debug!("help_template::write subcommand under heading: `{heading:?}`");
+        use std::fmt::Write as _;
+        let header = &self.styles.get_header();
+
+        if let Some(heading) = heading {
+            self.writer.push_str("\n\n");
+            let _ = write!(self.writer, "{header}{heading}:{header:#}\n",);
+        }
 
-        // First for the commands that don't have a heading
         for (i, (sc_str, sc)) in ord_v
             .clone()
             .into_iter()
-            .filter(|item| item.1.get_help_heading().is_none())
+            .filter(|item| item.1.get_help_heading() == heading)
             .enumerate()
         {
-            debug!("Processing without heading {}", sc.get_name());
             if 0 < i {
                 self.writer.push_str("\n");
             }
             self.write_subcommand(sc_str.1, sc, next_line_help, longest);
         }
-
-        // Commands under custom headings
-        if !custom_headings.is_empty() {
-            for heading in custom_headings {
-                let cmds = self
-                    .cmd
-                    .get_subcommands()
-                    .filter(|sc| {
-                        if let Some(help_heading) = sc.get_help_heading() {
-                            return help_heading == heading;
-                        }
-                        false
-                    })
-                    .filter(|sc| should_show_subcommand(sc))
-                    .collect::<Vec<_>>();
-
-                if !cmds.is_empty() {
-                    self.writer.push_str("\n\n");
-                    let _ = write!(self.writer, "{header}{heading}:{header:#}\n",);
-                    for (i, (sc_str, sc)) in ord_v
-                        .clone()
-                        .into_iter()
-                        .filter(|item| item.1.get_help_heading() == Some(heading))
-                        .enumerate()
-                    {
-                        debug!(
-                            "Processing with heading: name {}, heading {}",
-                            sc.get_name(),
-                            heading
-                        );
-                        if 0 < i {
-                            self.writer.push_str("\n");
-                        }
-                        self.write_subcommand(sc_str.1, sc, next_line_help, longest);
-                    }
-                }
-            }
-        }
     }
 
     /// Will use next line help on writing subcommands.

clap_builder/src/output/usage.rs

@@ -113,13 +113,10 @@ impl Usage<'_> {
             }
             let mut cmd = self.cmd.clone();
             cmd.build();
-          
+
             let mut first = true;
             // Get the custom headings
-            let custom_headings = cmd
-                .get_subcommands()
-                .filter_map(|sc| sc.get_help_heading())
-                .collect::<FlatSet<_>>();
+            let custom_sc_headings = cmd.get_subcommand_custom_help_headings();
 
             // Write commands without headings
             for sub in cmd
@@ -140,7 +137,7 @@ impl Usage<'_> {
             }
 
             // Write commands with headings
-            for heading in custom_headings {
+            for heading in custom_sc_headings {
                 for sub in cmd
                     .get_subcommands()
                     .filter(|c| !c.is_hide_set())