Introduce subcommand grouping into the command configuration to improve help

DougGregor · DougGregor · commit b01335522fad · 2024-06-02T16:37:57.000-07:00
Add optional support for grouping subcommands into named groups, to
help bring order to commands with many subcommands without requiring
additional structure. For example, here's the help for a
"subgroupings" command that has an ungrouped subcommand (m), and two
groups of subcommands ("broken" and "complicated").

    USAGE: subgroupings &lt;subcommand&gt;

    OPTIONS:
      -h, --help              Show help information.

    SUBCOMMANDS:
      m

    BROKEN SUBCOMMANDS:
      foo                     Perform some foo
      bar                     Perform bar operations

    COMPLICATED SUBCOMMANDS:
      n

      See 'subgroupings help &lt;subcommand&gt;' for detailed help.

To be able freely mix subcommands and subcommand groups, CommandConfiguration
has a new initializer that takes a result builder. The help output
above is created like this:

    struct WithSubgroups: ParsableCommand {
      static let configuration = CommandConfiguration(
        commandName: "subgroupings"
      ) {
        CommandGroup(name: "Broken") {
          Foo.self
          Bar.self
        }

        M.self

        CommandGroup(name: "Complicated") {
          N.self
        }
      }
    }

Each `CommandGroup` names a new group and is given commands (there are
no groups within groups). The other entries are arbitrary
ParsableCommands.

This structure is only cosmetic, and only affects help generation by
providing more structure for the reader. It doesn't impact existing
clients, who can still reason about the flattened list of subcommands
if they prefer.
diff --git a/Sources/ArgumentParser/Parsable Types/CommandConfiguration.swift b/Sources/ArgumentParser/Parsable Types/CommandConfiguration.swift
@@ -47,8 +47,22 @@ public struct CommandConfiguration: Sendable {
   public var shouldDisplay: Bool
   
   /// An array of the types that define subcommands for this command.
-  public var subcommands: [ParsableCommand.Type]
-  
+  ///
+  /// This property "flattens" the grouping structure of the subcommands.
+  /// Use 'groupedSubcommands' to retain the grouping structure.
+  public var subcommands: [ParsableCommand.Type] {
+    get {
+      groupedSubcommands.flatMap { $0.flattenedSubcommands }
+    }
+
+    set {
+      groupedSubcommands = newValue.map { Subcommand.single($0) }
+    }
+  }
+
+  /// The list of subcommands and subcommand groups.
+  public var groupedSubcommands: [Subcommand]
+
   /// The default command type to run if no subcommand is given.
   public var defaultSubcommand: ParsableCommand.Type?
   
@@ -62,6 +76,58 @@ public struct CommandConfiguration: Sendable {
   /// or `commandName` itself if provided.
   public var aliases: [String]
 
+  /// Creates the configuration for a command.
+  ///
+  /// - Parameters:
+  ///   - commandName: The name of the command to use on the command line. If
+  ///     `commandName` is `nil`, the command name is derived by converting
+  ///     the name of the command type to hyphen-separated lowercase words.
+  ///   - abstract: A one-line description of the command.
+  ///   - usage: A custom usage description for the command. When you provide
+  ///     a non-`nil` string, the argument parser uses `usage` instead of
+  ///     automatically generating a usage description. Passing an empty string
+  ///     hides the usage string altogether.
+  ///   - discussion: A longer description of the command.
+  ///   - version: The version number for this command. When you provide a
+  ///     non-empty string, the argument parser prints it if the user provides
+  ///     a `--version` flag.
+  ///   - shouldDisplay: A Boolean value indicating whether the command
+  ///     should be shown in the extended help display.
+  ///   - subcommands: An array of the types that define subcommands for the
+  ///     command.
+  ///   - defaultSubcommand: The default command type to run if no subcommand
+  ///     is given.
+  ///   - helpNames: The flag names to use for requesting help, when combined
+  ///     with a simulated Boolean property named `help`. If `helpNames` is
+  ///     `nil`, the names are inherited from the parent command, if any, or
+  ///     are `-h` and `--help`.
+  ///   - aliases: An array of aliases for the command's name. All of the aliases
+  ///     MUST not match the actual command name, whether that be the derived name
+  ///     if `commandName` is not provided, or `commandName` itself if provided.
+  public init(
+    commandName: String? = nil,
+    abstract: String = "",
+    usage: String? = nil,
+    discussion: String = "",
+    version: String = "",
+    shouldDisplay: Bool = true,
+    defaultSubcommand: ParsableCommand.Type? = nil,
+    helpNames: NameSpecification? = nil,
+    aliases: [String] = [],
+    @SubcommandsBuilder groupedSubcommands: () -> [Subcommand]
+  ) {
+    self.commandName = commandName
+    self.abstract = abstract
+    self.usage = usage
+    self.discussion = discussion
+    self.version = version
+    self.shouldDisplay = shouldDisplay
+    self.groupedSubcommands = groupedSubcommands()
+    self.defaultSubcommand = defaultSubcommand
+    self.helpNames = helpNames
+    self.aliases = aliases
+  }
+
   /// Creates the configuration for a command.
   ///
   /// - Parameters:
@@ -108,7 +174,7 @@ public struct CommandConfiguration: Sendable {
     self.discussion = discussion
     self.version = version
     self.shouldDisplay = shouldDisplay
-    self.subcommands = subcommands
+    self.groupedSubcommands = subcommands.map { .single($0) }
     self.defaultSubcommand = defaultSubcommand
     self.helpNames = helpNames
     self.aliases = aliases
@@ -136,7 +202,7 @@ public struct CommandConfiguration: Sendable {
     self.discussion = discussion
     self.version = version
     self.shouldDisplay = shouldDisplay
-    self.subcommands = subcommands
+    self.groupedSubcommands = subcommands.map { .single($0) }
     self.defaultSubcommand = defaultSubcommand
     self.helpNames = helpNames
     self.aliases = aliases
diff --git a/Sources/ArgumentParser/Parsable Types/CommandGroup.swift b/Sources/ArgumentParser/Parsable Types/CommandGroup.swift
@@ -0,0 +1,36 @@
+//===----------------------------------------------------------*- swift -*-===//
+//
+// This source file is part of the Swift Argument Parser open source project
+//
+// Copyright (c) 2020 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+//
+//===----------------------------------------------------------------------===//
+
+/// A set of commands grouped together under a common name.
+public struct CommandGroup: Sendable {
+  /// The name of the command group that will be displayed in help.
+  public let name: String
+
+  /// The list of subcommands that are part of this group.
+  public let subcommands: [ParsableCommand.Type]
+
+  /// Create a command group.
+  public init(
+    name: String,
+    @CommandsBuilder subcommands: () -> [ParsableCommand.Type]
+  ) {
+    self.name = name
+    self.subcommands = subcommands()
+  }
+}
+
+/// Result builder that forms a list of commands.
+@resultBuilder
+public struct CommandsBuilder {
+  public static func buildBlock(_ commands: ParsableCommand.Type...) -> [ParsableCommand.Type] {
+      return commands
+  }
+}
diff --git a/Sources/ArgumentParser/Parsable Types/SubcommandsBuilder.swift b/Sources/ArgumentParser/Parsable Types/SubcommandsBuilder.swift
@@ -0,0 +1,45 @@
+//===----------------------------------------------------------*- swift -*-===//
+//
+// This source file is part of the Swift Argument Parser open source project
+//
+// Copyright (c) 2020 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+//
+//===----------------------------------------------------------------------===//
+
+/// Build a set of subcommands which can potentially be grouped.
+@resultBuilder
+public struct SubcommandsBuilder {
+  public static func buildExpression(_ single: ParsableCommand.Type) -> Subcommand {
+    return .single(single)
+  }
+
+  public static func buildExpression(_ group: CommandGroup) -> Subcommand {
+    return .group(group)
+  }
+
+  public static func buildBlock(_ subcommands: Subcommand...) -> [Subcommand] {
+      return subcommands
+  }
+}
+
+/// Describes a single subcommand or a group thereof.
+public enum Subcommand: Sendable {
+  case single(ParsableCommand.Type)
+  case group(CommandGroup)
+}
+
+extension Subcommand {
+  /// Return a flattened list of all of the subcommands in this tree where the
+  /// group structure has been eliminated.
+  var flattenedSubcommands: [ParsableCommand.Type] {
+    switch self {
+    case .single(let command):
+      return [command]
+    case .group(let group):
+      return group.subcommands
+    }
+  }
+}
diff --git a/Sources/ArgumentParser/Usage/HelpGenerator.swift b/Sources/ArgumentParser/Usage/HelpGenerator.swift
@@ -52,7 +52,8 @@ internal struct HelpGenerator {
       case subcommands
       case options
       case title(String)
-      
+      case groupedSubcommands(String)
+
       var description: String {
         switch self {
         case .positionalArguments:
@@ -63,6 +64,8 @@ internal struct HelpGenerator {
           return "Options"
         case .title(let name):
           return name
+        case .groupedSubcommands(let name):
+          return "\(name) Subcommands"
         }
       }
     }
@@ -211,34 +214,73 @@ internal struct HelpGenerator {
     }
     
     let configuration = commandStack.last!.configuration
-    let subcommandElements: [Section.Element] =
-      configuration.subcommands.compactMap { command in
-        guard command.configuration.shouldDisplay else { return nil }
-        var label = command._commandName
-        for alias in command.configuration.aliases {
-            label += ", \(alias)"
+
+    // Create section for a grouping of subcommands.
+    func subcommandSection(
+      header: Section.Header, 
+      subcommands: [ParsableCommand.Type]
+    ) -> Section {
+      let subcommandElements: [Section.Element] =
+        subcommands.compactMap { command in
+          guard command.configuration.shouldDisplay else { return nil }
+          var label = command._commandName
+          for alias in command.configuration.aliases {
+              label += ", \(alias)"
+          }
+          if command == configuration.defaultSubcommand {
+              label += " (default)"
+          }
+          return Section.Element(
+            label: label,
+            abstract: command.configuration.abstract)
+      }
+
+      return Section(header: header, elements: subcommandElements)
+    }
+
+    // Sections for all of the grouped subcommands.
+    let groupedSubcommands: [Section] = configuration.groupedSubcommands
+      .compactMap { subcommand in
+        switch subcommand {
+        case .single(_):
+          return nil
+
+        case .group(let group):
+          return subcommandSection(
+            header: .groupedSubcommands(group.name),
+            subcommands: group.subcommands
+          )
         }
-        if command == configuration.defaultSubcommand {
-            label += " (default)"
+      }
+
+    // Section for the ungrouped subcommands.
+    let ungroupedSubcommands: Section = subcommandSection(
+      header: .subcommands,
+      subcommands: configuration.groupedSubcommands.compactMap {
+        switch $0 {
+        case .single(let command):
+          return command
+
+        case .group(_):
+          return nil
         }
-        return Section.Element(
-          label: label,
-          abstract: command.configuration.abstract)
-    }
-    
+      }
+    )
+
     // Combine the compiled groups in this order:
     // - arguments
     // - named sections
     // - options/flags
-    // - subcommands
+    // - grouped subcommands
+    // - ungrouped 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),
-    ]
+      ungroupedSubcommands
+    ] + groupedSubcommands
   }
   
   func usageMessage() -> String {
@@ -247,8 +289,12 @@ internal struct HelpGenerator {
   }
   
   var includesSubcommands: Bool {
-    guard let subcommandSection = sections.first(where: { $0.header == .subcommands })
-      else { return false }
+    guard let subcommandSection = sections.first(where: { 
+      switch $0.header {
+      case .groupedSubcommands(_), .subcommands: return true
+      case .options, .positionalArguments, .title(_): return false
+      }
+    }) else { return false }
     return !subcommandSection.elements.isEmpty
   }
   
diff --git a/Tests/ArgumentParserUnitTests/HelpGenerationTests.swift b/Tests/ArgumentParserUnitTests/HelpGenerationTests.swift
@@ -514,6 +514,44 @@ extension HelpGenerationTests {
     
     """)
   }
+
+  struct WithSubgroups: ParsableCommand {
+    static let configuration = CommandConfiguration(
+      commandName: "subgroupings"
+    ) {
+      CommandGroup(name: "Broken") {
+        Foo.self
+        Bar.self
+      }
+
+      M.self
+
+      CommandGroup(name: "Complicated") {
+        N.self
+      }
+    }
+  }
+
+  func testHelpSubcommandGroups() throws {
+    AssertHelp(.default, for: WithSubgroups.self, equals: """
+    USAGE: subgroupings <subcommand>
+
+    OPTIONS:
+      -h, --help              Show help information.
+
+    SUBCOMMANDS:
+      m
+
+    BROKEN SUBCOMMANDS:
+      foo                     Perform some foo
+      bar                     Perform bar operations
+
+    COMPLICATED SUBCOMMANDS:
+      n
+
+      See 'subgroupings help <subcommand>' for detailed help.
+    """)
+  }
 }
 
 extension HelpGenerationTests {
