Add API for titling an option group

Sources/ArgumentParser/Documentation.docc/Articles/CustomizingHelp.md

@@ -74,7 +74,7 @@ OPTIONS:
   -h, --help              Show help information.
 ```
 
-### Controlling Argument Visibility
+## Controlling Argument Visibility
 
 You can specify the visibility of any argument, option, or flag.
 
@@ -141,3 +141,56 @@ OPTIONS:
                           Use advanced security. (experimental)
   -h, --help              Show help information.
 ```
+
+## Grouping Arguments in the Help Screen
+
+When you provide a title in an `@OptionGroup` declaration, that type's 
+properties are grouped together under your title in the help screen. 
+For example, this command bundles similar arguments together under a 
+"Build Options" title:
+
+```swift
+struct BuildOptions: ParsableArguments {
+    @Option(help: "A setting to pass to the compiler.")
+    var compilerSetting: [String] = []
+
+    @Option(help: "A setting to pass to the linker.")
+    var linkerSetting: [String] = []
+}
+
+struct Example: ParsableCommand {
+    @Argument(help: "The input file to process.")
+    var inputFile: String
+
+    @Flag(help: "Show extra output.")
+    var verbose: Bool = false
+
+    @Option(help: "The path to a configuration file.")
+    var configFile: String?
+
+    @OptionGroup(title: "Build Options")
+    var buildOptions: BuildOptions
+}
+```
+
+This grouping is reflected in the command's help screen:
+
+```
+% example --help
+USAGE: example <input-file> [--verbose] [--config-file <config-file>] [--compiler-setting <compiler-setting> ...] [--linker-setting <linker-setting> ...]
+
+ARGUMENTS:
+  <input-file>            The input file to process.
+
+BUILD OPTIONS:
+  --compiler-setting <compiler-setting>
+                          A setting to pass to the compiler.
+  --linker-setting <linker-setting>
+                          A setting to pass to the linker.
+
+OPTIONS:
+  --verbose               Show extra output.
+  --config-file <config-file>
+                          The path to a configuration file.
+  -h, --help              Show help information.
+```

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 { parentKey in
-      return ArgumentSet(Value.self, visibility: .private, parent: .key(parentKey))
+      var args = ArgumentSet(Value.self, visibility: .private, parent: .key(parentKey))
+      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/DumpHelpGenerator.swift

@@ -126,6 +126,7 @@ fileprivate extension ArgumentInfoV0 {
     self.init(
       kind: kind,
       shouldDisplay: argument.help.visibility.base == .default,
+      sectionTitle: argument.help.parentTitle.nonEmpty,
       isOptional: argument.help.options.contains(.isOptional),
       isRepeating: argument.help.options.contains(.isRepeating),
       names: argument.names.map(ArgumentInfoV0.NameInfoV0.init),

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,10 @@ internal struct HelpGenerator {
 
     var positionalElements: [Section.Element] = []
     var optionElements: [Section.Element] = []
+
+    // Simulate an ordered dictionary using a dictionary and array for ordering.
+    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 +190,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 +216,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)
+    }
+  }
+}

Sources/ArgumentParser/Utilities/StringExtensions.swift

@@ -132,7 +132,6 @@ extension StringProtocol where SubSequence == Substring {
   ///     // 3
   ///     "bar".editDistance(to: "baz")
   ///     // 1
-
   func editDistance(to target: String) -> Int {
     let rows = self.count
     let columns = target.count
@@ -239,4 +238,8 @@ extension StringProtocol where SubSequence == Substring {
     guard lines.count == 2 else { return lines.joined(separator: "") }
     return "\(lines[0])\n\(lines[1].indentingEachLine(by: n))"
   }
+
+  var nonEmpty: Self? {
+    isEmpty ? nil : self
+  }
 }

Sources/ArgumentParserToolInfo/ToolInfo.swift

@@ -122,6 +122,9 @@ public struct ArgumentInfoV0: Codable, Hashable {
 
   /// Argument should appear in help displays.
   public var shouldDisplay: Bool
+  /// Custom name of argument's section.
+  public var sectionTitle: String?
+
   /// Argument can be omitted.
   public var isOptional: Bool
   /// Argument can be specified multiple times.
@@ -147,6 +150,7 @@ public struct ArgumentInfoV0: Codable, Hashable {
   public init(
     kind: KindV0,
     shouldDisplay: Bool,
+    sectionTitle: String?,
     isOptional: Bool,
     isRepeating: Bool,
     names: [NameInfoV0]?,
@@ -160,6 +164,8 @@ public struct ArgumentInfoV0: Codable, Hashable {
     self.kind = kind
 
     self.shouldDisplay = shouldDisplay
+    self.sectionTitle = sectionTitle
+
     self.isOptional = isOptional
     self.isRepeating = isRepeating
 

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

Tests/ArgumentParserUnitTests/DumpHelpGenerationTests.swift

@@ -50,10 +50,24 @@ extension DumpHelpGenerationTests {
     var argWithDefaultValue: Int = 1
   }
 
+  struct Options: ParsableArguments {
+    @Flag var verbose = false
+    @Option var name: String
+  }
+
+  struct B: ParsableCommand {
+    @OptionGroup(title: "Other")
+    var options: Options
+  }
+
   public func testDumpA() throws {
     try AssertDump(for: A.self, equals: Self.aDumpText)
   }
 
+  public func testDumpB() throws {
+    try AssertDump(for: B.self, equals: Self.bDumpText)
+  }
+
   public func testDumpExampleCommands() throws {
     struct TestCase {
       let expected: String
@@ -233,6 +247,75 @@ extension DumpHelpGenerationTests {
 }
 """
 
+  static let bDumpText: String = """
+{
+  "command" : {
+    "arguments" : [
+      {
+        "isOptional" : true,
+        "isRepeating" : false,
+        "kind" : "flag",
+        "names" : [
+          {
+            "kind" : "long",
+            "name" : "verbose"
+          }
+        ],
+        "preferredName" : {
+          "kind" : "long",
+          "name" : "verbose"
+        },
+        "sectionTitle" : "Other",
+        "shouldDisplay" : true,
+        "valueName" : "verbose"
+      },
+      {
+        "isOptional" : false,
+        "isRepeating" : false,
+        "kind" : "option",
+        "names" : [
+          {
+            "kind" : "long",
+            "name" : "name"
+          }
+        ],
+        "preferredName" : {
+          "kind" : "long",
+          "name" : "name"
+        },
+        "sectionTitle" : "Other",
+        "shouldDisplay" : true,
+        "valueName" : "name"
+      },
+      {
+        "abstract" : "Show help information.",
+        "isOptional" : true,
+        "isRepeating" : false,
+        "kind" : "flag",
+        "names" : [
+          {
+            "kind" : "short",
+            "name" : "h"
+          },
+          {
+            "kind" : "long",
+            "name" : "help"
+          }
+        ],
+        "preferredName" : {
+          "kind" : "long",
+          "name" : "help"
+        },
+        "shouldDisplay" : true,
+        "valueName" : "help"
+      }
+    ],
+    "commandName" : "b"
+  },
+  "serializationVersion" : 0
+}
+"""
+
   static let mathDumpText: String = """
 {
   "command" : {