Add API for titling an option group

Sources/ArgumentParser/Parsable Properties/OptionGroup.swift

@@ -36,6 +36,9 @@ public struct OptionGroup<Value: ParsableArguments>: Decodable, ParsedWrapper {
   // FIXME: Adding this property works around the crasher described in
   // https://github.com/apple/swift-argument-parser/issues/338
   internal var _dummy: Bool = false
+
+  /// The title to use in the help screen for this option group.
+  public var title: String = ""
 
   internal init(_parsedValue: Parsed<Value>) {
     self._parsedValue = _parsedValue
@@ -62,12 +65,27 @@ public struct OptionGroup<Value: ParsableArguments>: Decodable, ParsedWrapper {
   }
 
   /// Creates a property that represents another parsable type, using the
-  /// specified visibility.
-  public init(visibility: ArgumentVisibility = .default) {
+  /// specified title and visibility.
+  ///
+  /// - Parameters:
+  ///   - title: A title for grouping this option group's members in your
+  ///     command's help screen. If `title` is empty, the members will be
+  ///     displayed alongside the other arguments, flags, and options declared
+  ///     by your command.
+  ///   - visibility: The visibility to use for the entire option group.
+  public init(
+    title: String = "",
+    visibility: ArgumentVisibility = .default
+  ) {
     self.init(_parsedValue: .init { _ in
-      ArgumentSet(Value.self, visibility: .private)
+      var args = ArgumentSet(Value.self, visibility: .private)
+      args.content.withEach {
+        $0.help.parentTitle = title
+      }
+      return args
     })
     self._visibility = visibility
+    self.title = title
   }
 
   /// The value presented by this property wrapper.
@@ -111,3 +129,15 @@ extension OptionGroup {
     self.init(visibility: .default)
   }
 }
+
+// MARK: Deprecated
+
+extension OptionGroup {
+  @_disfavoredOverload
+  @available(*, deprecated, renamed: "init(title:visibility:)")
+  public init(
+    visibility _visibility: ArgumentVisibility = .default
+  ) {
+    self.init(title: "", visibility: _visibility)
+  }
+}

Sources/ArgumentParser/Parsing/ArgumentDefinition.swift

@@ -54,6 +54,7 @@ struct ArgumentDefinition {
     var discussion: String
     var valueName: String
     var visibility: ArgumentVisibility
+    var parentTitle: String
 
     init(
       allValues: [String],
@@ -72,6 +73,7 @@ struct ArgumentDefinition {
       self.discussion = help?.discussion ?? ""
       self.valueName = help?.valueName ?? ""
       self.visibility = help?.visibility ?? .default
+      self.parentTitle = ""
     }
   }
 

Sources/ArgumentParser/Usage/HelpGenerator.swift

@@ -51,6 +51,7 @@ internal struct HelpGenerator {
       case positionalArguments
       case subcommands
       case options
+      case title(String)
 
       var description: String {
         switch self {
@@ -60,6 +61,8 @@ internal struct HelpGenerator {
           return "Subcommands"
         case .options:
           return "Options"
+        case .title(let name):
+          return name
         }
       }
     }
@@ -136,6 +139,8 @@ internal struct HelpGenerator {
 
     var positionalElements: [Section.Element] = []
     var optionElements: [Section.Element] = []
+    var titledSections: [String: [Section.Element]] = [:]
+    var sectionTitles: [String] = []
 
     /// Start with a full slice of the ArgumentSet so we can peel off one or
     /// more elements at a time.
@@ -183,9 +188,15 @@ internal struct HelpGenerator {
       }
 
       let element = Section.Element(label: synopsis, abstract: description, discussion: arg.help.discussion)
-      if case .positional = arg.kind {
+      switch (arg.kind, arg.help.parentTitle) {
+      case (_, let sectionTitle) where !sectionTitle.isEmpty:
+        if !titledSections.keys.contains(sectionTitle) {
+          sectionTitles.append(sectionTitle)
+        }
+        titledSections[sectionTitle, default: []].append(element)
+      case (.positional, _):
         positionalElements.append(element)
-      } else {
+      default:
         optionElements.append(element)
       }
     }
@@ -203,8 +214,16 @@ internal struct HelpGenerator {
           abstract: command.configuration.abstract)
     }
 
+    // Combine the compiled groups in this order:
+    // - arguments
+    // - named sections
+    // - options/flags
+    // - subcommands
     return [
       Section(header: .positionalArguments, elements: positionalElements),
+    ] + sectionTitles.map { name in
+      Section(header: .title(name), elements: titledSections[name, default: []])
+    } + [
       Section(header: .options, elements: optionElements),
       Section(header: .subcommands, elements: subcommandElements),
     ]

Sources/ArgumentParser/Utilities/CollectionExtensions.swift

@@ -14,3 +14,13 @@ extension Collection {
     isEmpty ? replacement() : self
   }
 }
+
+extension MutableCollection {
+  mutating func withEach(_ body: (inout Element) throws -> Void) rethrows {
+    var i = startIndex
+    while i < endIndex {
+      try body(&self[i])
+      formIndex(after: &i)
+    }
+  }
+}

Tests/ArgumentParserUnitTests/CMakeLists.txt

@@ -4,6 +4,7 @@ add_library(UnitTests
   HelpGenerationTests.swift
   HelpGenerationTests+AtArgument.swift
   HelpGenerationTests+AtOption.swift
+  HelpGenerationTests+GroupName.swift
   NameSpecificationTests.swift
   SplitArgumentTests.swift
   StringSnakeCaseTests.swift