Add aliases support for sub commands

Examples/math/Math.swift

@@ -64,8 +64,9 @@ extension Math {
     }
 
     struct Multiply: ParsableCommand {
-        static let configuration =
-            CommandConfiguration(abstract: "Print the product of the values.")
+        static let configuration = CommandConfiguration(
+            abstract: "Print the product of the values.",
+            aliases: ["mul"])
 
         @OptionGroup var options: Options
 
@@ -92,7 +93,8 @@ extension Math.Statistics {
     struct Average: ParsableCommand {
         static let configuration = CommandConfiguration(
             abstract: "Print the average of the values.",
-            version: "1.5.0-alpha")
+            version: "1.5.0-alpha",
+            aliases: ["avg"])
 
         enum Kind: String, ExpressibleByArgument, CaseIterable {
             case mean, median, mode

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

@@ -28,7 +28,7 @@ OPTIONS:
   -h, --help              Show help information.
 
 SUBCOMMANDS:
-  average                 Print the average of the values.
+  average, avg            Print the average of the values.
   stdev                   Print the standard deviation of the values.
   quantiles               Print the quantiles of the values (TBD).
 
@@ -84,8 +84,9 @@ extension Math {
     }
 
     struct Multiply: ParsableCommand {
-        static let configuration
-            = CommandConfiguration(abstract: "Print the product of the values.")
+        static let configuration = CommandConfiguration(
+            abstract: "Print the product of the values.",
+            aliases: ["mul"])
 
         @OptionGroup var options: Math.Options
 
@@ -97,6 +98,17 @@ extension Math {
 }
 ```
 
+One thing to note is the aliases parameter for `CommandConfiguration`. This is useful for subcommands
+to define alternative names that can be used to invoke them. In this case we've defined a shorthand
+for multiply named mul, so you could invoke the `Multiply` command for our program by either of the below:
+
+```
+% math multiply 10 15 7
+1050
+% math mul 10 15 7
+1050
+```
+
 Next, we'll define `Statistics`, the third subcommand of `Math`. The `Statistics` command specifies a custom command name (`stats`) in its configuration, overriding the default derived from the type name (`statistics`). It also declares two additional subcommands, meaning that it acts as a forked branch in the command tree, and not a leaf.
 
 ```swift
@@ -116,7 +128,8 @@ Let's finish our subcommands with the `Average` and `StandardDeviation` types. E
 extension Math.Statistics {
     struct Average: ParsableCommand {
         static let configuration = CommandConfiguration(
-            abstract: "Print the average of the values.")
+            abstract: "Print the average of the values.",
+            aliases: ["avg"])
 
         enum Kind: String, ExpressibleByArgument {
             case mean, median, mode

Sources/ArgumentParser/Documentation.docc/Extensions/CommandConfiguration.md

@@ -4,7 +4,7 @@
 
 ### Creating a Configuration
 
-- ``init(commandName:abstract:usage:discussion:version:shouldDisplay:subcommands:defaultSubcommand:helpNames:)``
+- ``init(commandName:abstract:usage:discussion:version:shouldDisplay:subcommands:defaultSubcommand:helpNames:aliases:)``
 
 ### Customizing the Help Screen
 
@@ -23,4 +23,4 @@
 - ``commandName``
 - ``version``
 - ``shouldDisplay``
-
+- ``aliases``

Sources/ArgumentParser/Parsable Types/CommandConfiguration.swift

@@ -54,7 +54,14 @@ public struct CommandConfiguration: Sendable {
 
   /// Flag names to be used for help.
   public var helpNames: NameSpecification?
-
+
+  /// An array of aliases for the command's name.
+  ///
+  /// All of the aliases MUST not match the actual command's name,
+  /// whether that be the derived name if `commandName` is not provided,
+  /// or `commandName` itself if provided.
+  public var aliases: [String]
+
   /// Creates the configuration for a command.
   ///
   /// - Parameters:
@@ -80,6 +87,9 @@ public struct CommandConfiguration: Sendable {
   ///     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 = "",
@@ -89,7 +99,8 @@ public struct CommandConfiguration: Sendable {
     shouldDisplay: Bool = true,
     subcommands: [ParsableCommand.Type] = [],
     defaultSubcommand: ParsableCommand.Type? = nil,
-    helpNames: NameSpecification? = nil
+    helpNames: NameSpecification? = nil,
+    aliases: [String] = []
   ) {
     self.commandName = commandName
     self.abstract = abstract
@@ -100,6 +111,7 @@ public struct CommandConfiguration: Sendable {
     self.subcommands = subcommands
     self.defaultSubcommand = defaultSubcommand
     self.helpNames = helpNames
+    self.aliases = aliases
   }
 
   /// Creates the configuration for a command with a "super-command".
@@ -114,7 +126,8 @@ public struct CommandConfiguration: Sendable {
     shouldDisplay: Bool = true,
     subcommands: [ParsableCommand.Type] = [],
     defaultSubcommand: ParsableCommand.Type? = nil,
-    helpNames: NameSpecification? = nil
+    helpNames: NameSpecification? = nil,
+    aliases: [String] = []
   ) {
     self.commandName = commandName
     self._superCommandName = _superCommandName
@@ -126,11 +139,37 @@ public struct CommandConfiguration: Sendable {
     self.subcommands = subcommands
     self.defaultSubcommand = defaultSubcommand
     self.helpNames = helpNames
+    self.aliases = aliases
   }
 }
 
 extension CommandConfiguration {
-  @available(*, deprecated, message: "Use the memberwise initializer with the usage parameter.")
+  @available(*, deprecated, message: "Use the memberwise initializer with the aliases parameter.")
+  public init(
+    commandName: String? = nil,
+    abstract: String = "",
+    usage: String? = nil,
+    discussion: String = "",
+    version: String = "",
+    shouldDisplay: Bool = true,
+    subcommands: [ParsableCommand.Type] = [],
+    defaultSubcommand: ParsableCommand.Type? = nil,
+    helpNames: NameSpecification? = nil
+  ) {
+    self.init(
+      commandName: commandName,
+      abstract: abstract,
+      usage: usage,
+      discussion: discussion,
+      version: version,
+      shouldDisplay: shouldDisplay,
+      subcommands: subcommands,
+      defaultSubcommand: defaultSubcommand,
+      helpNames: helpNames,
+      aliases: [])
+  }
+
+  @available(*, deprecated, message: "Use the memberwise initializer with the usage and aliases parameters.")
   public init(
     commandName _commandName: String?,
     abstract: String,
@@ -150,6 +189,7 @@ extension CommandConfiguration {
       shouldDisplay: shouldDisplay,
       subcommands: subcommands,
       defaultSubcommand: defaultSubcommand,
-      helpNames: helpNames)
+      helpNames: helpNames,
+      aliases: [])
   }
 }

Sources/ArgumentParser/Parsing/ArgumentSet.swift

@@ -495,7 +495,10 @@ struct LenientParser {
         // parsing to skip over unrecognized input, but if the current
         // command or the matched subcommand captures all remaining input,
         // then we want to break out of parsing at this point.
-        if let matchedSubcommand = subcommands.first(where: { $0._commandName == argument }) {
+        let matchedSubcommand = subcommands.first(where: { 
+          $0._commandName == argument || $0.configuration.aliases.contains(argument) 
+        })
+        if let matchedSubcommand {
           if !matchedSubcommand.includesPassthroughArguments && defaultCapturesForPassthrough {
             continue ArgumentLoop
           } else if matchedSubcommand.includesPassthroughArguments {

Sources/ArgumentParser/Parsing/CommandParser.swift

@@ -41,11 +41,13 @@ struct CommandParser {
       self.commandTree = try Tree(root: rootCommand)
     } catch Tree<ParsableCommand.Type>.InitializationError.recursiveSubcommand(let command) {
       fatalError("The ParsableCommand \"\(command)\" can't have itself as its own subcommand.")
+    } catch Tree<ParsableCommand.Type>.InitializationError.aliasMatchingCommand(let command) {
+      fatalError("The ParsableCommand \"\(command)\" can't have an alias with the same name as the command itself.")
     } catch {
       fatalError("Unexpected error: \(error).")
     }
     self.currentNode = commandTree
-    
+
     // A command tree that has a depth greater than zero gets a `help`
     // subcommand.
     if !commandTree.isLeaf {

Sources/ArgumentParser/Usage/HelpGenerator.swift

@@ -215,6 +215,9 @@ internal struct HelpGenerator {
       configuration.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)"
         }

Sources/ArgumentParser/Utilities/Tree.swift

@@ -85,7 +85,9 @@ extension Tree where Element == ParsableCommand.Type {
   }
 
   func firstChild(withName name: String) -> Tree? {
-    children.first(where: { $0.element._commandName == name })
+      children.first(where: {
+          $0.element._commandName == name || $0.element.configuration.aliases.contains(name)
+      })
   }
 
   convenience init(root command: ParsableCommand.Type) throws {
@@ -94,11 +96,16 @@ extension Tree where Element == ParsableCommand.Type {
       if subcommand == command {
         throw InitializationError.recursiveSubcommand(subcommand)
       }
+      // We don't allow an alias that has the same name as the command itself.
+      if subcommand.configuration.aliases.contains(subcommand._commandName) {
+        throw InitializationError.aliasMatchingCommand(subcommand)
+      }
       try addChild(Tree(root: subcommand))
     }
   }
 
   enum InitializationError: Error {
     case recursiveSubcommand(ParsableCommand.Type)
+    case aliasMatchingCommand(ParsableCommand.Type)
   }
 }