clap-rs#5819 - for current version

Author: Kamuno

clap_builder/src/builder/command.rs

@@ -101,9 +101,11 @@ pub struct Command {
     subcommands: Vec<Command>,
     groups: Vec<ArgGroup>,
     current_help_heading: Option<Str>,
+    current_subcommand_help_heading: Option<Str>,
     current_disp_ord: Option<usize>,
     subcommand_value_name: Option<Str>,
     subcommand_heading: Option<Str>,
+    subcommand_help_heading: Option<Option<Str>>,
     external_value_parser: Option<super::ValueParser>,
     long_help_exists: bool,
     deferred: Option<fn(Command) -> Command>,
@@ -490,6 +492,7 @@ impl Command {
             subcmd.disp_ord.get_or_insert(current);
             *current_disp_ord = current + 1;
         }
+        subcmd.subcommand_help_heading.get_or_insert_with(|| self.current_subcommand_help_heading.clone());
         self.subcommands.push(subcmd);
         self
     }
@@ -2295,6 +2298,32 @@ impl Command {
         self
     }
 
+        /// Set the default section heading for future subcommands.
+    ///
+    /// This will be used for any subcommand that hasn't had [`Command::subcommand_help_heading`] called.
+    ///
+    /// This is useful if the default `Commands` heading is
+    /// not specific enough for one's use case.
+    ///
+    /// [`Command::subcommand`]: Command::subcommand()
+    /// [`Command::subcommand_help_heading`]: crate::Command::subcommand_help_heading()
+    #[inline]
+    #[must_use]
+    pub fn next_subcommand_help_heading(mut self, heading: impl IntoResettable<Str>) -> Self {
+        self.current_subcommand_help_heading = heading.into_resettable().into_option();
+        self
+    }
+
+        /// Get the custom section heading specified via [`Command::next_subcommand_help_heading`].
+    ///
+    /// [`Command::subcommand_help_heading`]: Command::subcommand_help_heading()
+    #[inline]
+    pub fn get_next_subcommand_help_heading(&self) -> Option<&str> {
+        self.current_subcommand_help_heading.as_deref()
+    }
+
+
+
     /// Change the starting value for assigning future display orders for args.
     ///
     /// This will be used for any arg that hasn't had [`Arg::display_order`] called.
@@ -4889,6 +4918,14 @@ impl Command {
             .any(|sc| sc.name != "help" && !sc.is_set(AppSettings::Hidden))
     }
 
+    #[cfg(any(feature = "usage", feature = "help"))]
+    pub(crate) fn needs_commands_header(&self) -> bool {
+        self.subcommands
+            .iter()
+            .filter(|sc| !sc.is_set(AppSettings::Hidden))
+            .any(|sc| sc.subcommand_help_heading.is_none())
+    }
+
     /// Check if this subcommand can be referred to as `name`. In other words,
     /// check if `name` is the name of this subcommand or is one of its aliases.
     #[inline]
@@ -5131,6 +5168,8 @@ impl Default for Command {
             subcommands: Default::default(),
             groups: Default::default(),
             current_help_heading: Default::default(),
+            current_subcommand_help_heading: Default::default(),
+            subcommand_help_heading: Default::default(),
             current_disp_ord: Some(0),
             subcommand_value_name: Default::default(),
             subcommand_heading: Default::default(),

clap_builder/src/output/help_template.rs

@@ -409,7 +409,10 @@ impl HelpTemplate<'_, '_> {
                 .cmd
                 .get_subcommand_help_heading()
                 .unwrap_or(&default_help_heading);
-            let _ = write!(self.writer, "{header}{help_heading}:{header:#}\n",);
+            //let _ = write!(self.writer, "{header}{help_heading}:{header:#}\n",);
+            if self.cmd.needs_commands_header() {
+                let _ = write!(self.writer, "{header}{help_heading}:{header:#}\n",);
+            }
 
             self.write_subcommands(self.cmd);
         }
@@ -866,7 +869,7 @@ impl HelpTemplate<'_, '_> {
             .filter(|subcommand| should_show_subcommand(subcommand))
         {
             ord_v.insert(
-                (subcommand.get_display_order(), subcommand.get_name()),
+                (subcommand.get_subcommand_help_heading(), subcommand.get_display_order(), subcommand.get_name()),
                 subcommand,
             );
         }
@@ -934,18 +937,38 @@ impl HelpTemplate<'_, '_> {
                 let _ = write!(styled, ", {literal}--{long}{literal:#}",);
             }
             longest = longest.max(styled.display_width());
-            ord_v.insert((subcommand.get_display_order(), styled), subcommand);
+            ord_v.insert((subcommand.get_subcommand_help_heading(), subcommand.get_display_order(), styled), subcommand);
         }
 
         debug!("HelpTemplate::write_subcommands longest = {longest}");
 
         let next_line_help = self.will_subcommands_wrap(cmd.get_subcommands(), longest);
+        let mut current_help_heading: Option<&str> = None;
+        let mut help_heading_nl_needed = true;
 
         for (i, (sc_str, sc)) in ord_v.into_iter().enumerate() {
             if 0 < i {
                 self.writer.push_str("\n");
             }
-            self.write_subcommand(sc_str.1, sc, next_line_help, longest);
+
+            let opt_help_heading = sc_str.0;
+
+            if current_help_heading != opt_help_heading {
+                if let Some(help_heading) = opt_help_heading {
+                    let header = &self.styles.get_header();
+                    if help_heading_nl_needed {
+                        help_heading_nl_needed = false;
+                    } else {
+                        self.writer.push_str("\n");
+                    };
+                    let _ = write!(self.writer, "{header}{help_heading}:{header:#}\n",);
+                }
+                current_help_heading.replace(sc_str.0.unwrap());
+            } else {
+                help_heading_nl_needed = false;
+            }
+
+            self.write_subcommand(sc_str.clone().2, sc, next_line_help, longest);
         }
     }