refactor(help): Improve subcommand help display

- Refactor subcommand help display to group subcommands under custom headings.
- Use a FlatSet to collect unique custom headings from subcommands.
- Iterate through the headings and display associated subcommands.
- Remove the previous implementation of `write_subcommand_under_heading`.

Author: gortavoher

clap_builder/src/output/help_template.rs

@@ -938,10 +938,11 @@ 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;
-        let mut has_heading = false;
+        // let mut has_heading = false;
         let mut ord_v = BTreeMap::new();
         for subcommand in cmd
             .get_subcommands()
@@ -956,9 +957,9 @@ 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;
-            }
+            // 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);
         }
@@ -967,6 +968,12 @@ impl HelpTemplate<'_, '_> {
 
         let next_line_help = self.will_subcommands_wrap(cmd.get_subcommands(), longest);
 
+        let command_custom_headings = self
+            .cmd
+            .get_subcommands()
+            .filter_map(|cmd| cmd.get_help_heading())
+            .collect::<FlatSet<_>>();
+
         // First for the commands that don't have a heading
         for (i, (sc_str, sc)) in ord_v
             .clone()
@@ -981,72 +988,45 @@ impl HelpTemplate<'_, '_> {
             self.write_subcommand(sc_str.1, sc, next_line_help, longest);
         }
 
-        if has_heading {
-            self.write_subcommand_under_heading(cmd, next_line_help, longest);
-        }
-    }
-
-    /// Writes help with headings for subcommands of a Parser Object to the wrapped stream.
-    fn write_subcommand_under_heading(
-        &mut self,
-        cmd: &Command,
-        next_line_help: bool,
-        longest: usize,
-    ) {
-        debug!("HelpTemplate::write_subcommands_under_heading");
-        use std::fmt::Write as _;
-        let literal = &self.styles.get_literal();
-
-        let mut ord_v = BTreeMap::new();
-        let mut headings = BTreeMap::new();
-        let mut next_heading_ord = 0_usize;
-        for subcommand in cmd
-            .get_subcommands()
-            .filter(|subcommand| should_show_subcommand(subcommand))
-            .filter(|subcommand| subcommand.get_help_heading().is_some())
-        {
-            let mut styled = StyledStr::new();
-            let name = subcommand.get_name();
-            let _ = write!(styled, "{literal}{name}{literal:#}",);
-            if let Some(short) = subcommand.get_short_flag() {
-                let _ = write!(styled, ", {literal}-{short}{literal:#}",);
-            }
-            if let Some(long) = subcommand.get_long_flag() {
-                let _ = write!(styled, ", {literal}--{long}{literal:#}",);
-            }
-            let heading = subcommand.get_help_heading().unwrap();
-            let heading_ord = if let Some(ho) = headings.get(heading) {
-                *ho
-            } else {
-                next_heading_ord += 1;
-                headings.insert(heading, next_heading_ord);
-                next_heading_ord
-            };
-
-            ord_v.insert(
-                (heading_ord, subcommand.get_display_order(), styled),
-                subcommand,
-            );
-        }
-
-        let header = &self.styles.get_header();
-        let mut current_heading = "";
+        if !command_custom_headings.is_empty() {
+            for heading in command_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<_>>();
 
-        for (sc_str, sc) in ord_v
-            .into_iter()
-            .filter(|item| item.1.get_help_heading().is_some())
-        {
-            debug!("Processing with heading {}", sc.get_name());
-            self.writer.push_str("\n");
-            if sc.get_help_heading().unwrap() != current_heading {
-                current_heading = sc.get_help_heading().unwrap();
-                debug!("Heading changed; print new heading {}.", current_heading);
-                self.writer.push_str("\n");
-                let _ = write!(self.writer, "{header}{current_heading}:{header:#}\n",);
+                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);
+                    }
+                }
             }
-
-            self.write_subcommand(sc_str.2, sc, next_line_help, longest);
         }
+        // if has_heading {
+        //     self.write_subcommand_under_heading(cmd, next_line_help, longest);
+        // }
     }
 
     /// Will use next line help on writing subcommands.