[core] Implement command aliases (#5)

This PR implements command aliases for the ArgMojo CLI argument parsing
library. It also renames several API methods for consistency
(`parse_args()` → `parse_arguments()`, `help_on_no_args()` →
`help_on_no_arguments()`, `.nargs()` → `.number_of_values()`,
`nargs_count` field → `num_values`).

Author: forfudan

docs/argmojo_overall_planning.md

@@ -14,6 +14,7 @@ ArgMojo v0.2.0 is compatible with Mojo v0.26.1.
 1. Auto-register a `help` subcommand so that `app help <command>` works out of the box; opt out with `disable_help_subcommand()`.
 1. Add `allow_positional_with_subcommands()` guard — prevents accidental mixing of positional args and subcommands on the same `Command`, following the cobra/clap convention. Requires explicit opt-in.
 1. Add `subcommand` and `subcommand_result` fields on `ParseResult` with `has_subcommand_result()` / `get_subcommand_result()` accessors.
+1. Add `command_aliases()` builder method for subcommand short names (e.g., `clone` → `cl`). Aliases dispatch to the canonical subcommand, appear in help output, shell completions, and typo suggestions.
 
 **Persistent flags:**
 
@@ -102,7 +103,7 @@ ArgMojo v0.1.0 is compatible with Mojo v0.26.1.
 
 1. Append / collect action — `--tag x --tag y` collects repeated options into a list with `.append()`.
 1. Value delimiter — `--env dev,staging,prod` splits by delimiter into a list with `.delimiter(",")`.
-1. Multi-value options (nargs) — `--point 10 20` consumes N consecutive values with `.nargs(N)`.
+1. Multi-value options (nargs) — `--point 10 20` consumes N consecutive values with `.number_of_values(N)`.
 1. Key-value map option — `--define key=value` builds a `Dict` with `.key_value()`.
 
 **Help & display:**

docs/changelog.md

@@ -87,14 +87,14 @@ fn main() raises:
 
 ---
 
-**`parse()` vs `parse_args()`**
+**`parse()` vs `parse_arguments()`**
 
 - **`command.parse()`** reads the real command-line via `sys.argv()`.
-- **`command.parse_args(args)`** accepts a `List[String]` — useful for testing without a real binary. Note that `args[0]` is expected to be the program name and will be skipped, so the actual arguments should start from index 1.
+- **`command.parse_arguments(args)`** accepts a `List[String]` — useful for testing without a real binary. Note that `args[0]` is expected to be the program name and will be skipped, so the actual arguments should start from index 1.
 
 ### Reading Parsed Results
 
-After calling `command.parse()` or `command.parse_args()`, you get a `ParseResult` with these typed accessors:
+After calling `command.parse()` or `command.parse_arguments()`, you get a `ParseResult` with these typed accessors:
 
 | Method                      | Returns        | Description                                       |
 | --------------------------- | -------------- | ------------------------------------------------- |
@@ -659,14 +659,14 @@ This is similar to Python argparse's `nargs=N` and Rust clap's `num_args`.
 
 **Defining a multi-value option**
 
-Use `.nargs(N)` to specify how many values the option consumes:
+Use `.number_of_values(N)` to specify how many values the option consumes:
 
 ```mojo
-command.add_argument(Argument("point", help="X Y coordinates").long("point").nargs(2))
-command.add_argument(Argument("rgb", help="RGB colour").long("rgb").short("c").nargs(3))
+command.add_argument(Argument("point", help="X Y coordinates").long("point").number_of_values(2))
+command.add_argument(Argument("rgb", help="RGB colour").long("rgb").short("c").number_of_values(3))
 ```
 
-`.nargs(N)` automatically implies `.append()` — values are stored in
+`.number_of_values(N)` automatically implies `.append()` — values are stored in
 `ParseResult.lists` and retrieved with `get_list()`.
 
 ---
@@ -720,7 +720,7 @@ Choices are validated for **each** value individually:
 ```mojo
 var dirs: List[String] = ["north", "south", "east", "west"]
 command.add_argument(
-    Argument("route", help="Start and end").long("route").nargs(2).choices(dirs^)
+    Argument("route", help="Start and end").long("route").number_of_values(2).choices(dirs^)
 )
 ```
 
@@ -1490,6 +1490,37 @@ app.disable_help_subcommand()
 
 This can be called before or after `add_subcommand()`. If called after, the auto-added `help` entry is removed.
 
+### Subcommand Aliases
+
+You can register short aliases for subcommands with `command_aliases()`. When the user types an alias, ArgMojo dispatches to the canonical subcommand and stores the **canonical name** (not the alias) in `result.subcommand`.
+
+```mojo
+var clone = Command("clone", "Clone a repository")
+var aliases: List[String] = ["cl"]
+clone.command_aliases(aliases^)
+app.add_subcommand(clone^)
+```
+
+```bash
+app cl https://example.com/repo.git   # dispatches to "clone"
+app clone https://example.com/repo.git # still works
+```
+
+```mojo
+var result = app.parse()
+print(result.subcommand)  # always "clone", even if user typed "cl"
+```
+
+Aliases appear in help output alongside the primary name:
+
+```
+Commands:
+  clone, cl    Clone a repository
+  commit, ci   Record changes to the repository
+```
+
+Aliases are also included in shell-completion scripts and typo suggestions.
+
 ### Unknown Subcommand Error
 
 When the root command has subcommands registered **and `allow_positional_with_subcommands()` has not been called**, an unrecognised token triggers an error listing available commands:
@@ -1531,7 +1562,7 @@ app.add_argument(Argument("fallback", help="Fallback").positional())
 
 # "foo" doesn't match any subcommand → treated as positional
 var args: List[String] = ["app", "foo"]
-var result = app.parse_args(args)
+var result = app.parse_arguments(args)
 print(result.positionals[0])  # "foo"
 ```
 
@@ -1759,13 +1790,13 @@ After printing help, the program exits cleanly with exit code 0.
 
 **Show Help When No Arguments Provided**
 
-Use `help_on_no_args()` to automatically display help when the user invokes
+Use `help_on_no_arguments()` to automatically display help when the user invokes
 the command with no arguments (like `git`, `docker`, or `cargo`):
 
 ```mojo
 var command = Command("myapp", "My application")
 command.add_argument(Argument("file", help="Input file").long("file").required())
-command.help_on_no_args()
+command.help_on_no_arguments()
 var result = command.parse()
 ```
 

docs/user_manual.md

@@ -93,7 +93,9 @@ fn main() raises:
         .long("recurse-submodules")
         .flag()
     )
-    clone.help_on_no_args()
+    clone.help_on_no_arguments()
+    var clone_aliases: List[String] = ["cl"]
+    clone.command_aliases(clone_aliases^)
     app.add_subcommand(clone^)
 
     # ── init ─────────────────────────────────────────────────────────────
@@ -184,6 +186,8 @@ fn main() raises:
         .long("cleanup-mode")
         .deprecated("Use --cleanup instead")
     )
+    var commit_aliases: List[String] = ["ci"]
+    commit.command_aliases(commit_aliases^)
     app.add_subcommand(commit^)
 
     # ── push ─────────────────────────────────────────────────────────────
@@ -320,14 +324,14 @@ fn main() raises:
         .short("f")
         .flag()
     )
-    remote_add.help_on_no_args()
+    remote_add.help_on_no_arguments()
     remote.add_subcommand(remote_add^)
 
     var remote_remove = Command("remove", "Remove a remote")
     remote_remove.add_argument(
         Argument("name", help="Remote name to remove").positional().required()
     )
-    remote_remove.help_on_no_args()
+    remote_remove.help_on_no_arguments()
     remote.add_subcommand(remote_remove^)
 
     var remote_rename = Command("rename", "Rename a remote")
@@ -337,21 +341,23 @@ fn main() raises:
     remote_rename.add_argument(
         Argument("new", help="New remote name").positional().required()
     )
-    remote_rename.help_on_no_args()
+    remote_rename.help_on_no_arguments()
     remote.add_subcommand(remote_rename^)
 
     var remote_show = Command("show", "Show information about a remote")
     remote_show.add_argument(
         Argument("name", help="Remote name").positional().required()
     )
-    remote_show.help_on_no_args()
+    remote_show.help_on_no_arguments()
     remote.add_subcommand(remote_show^)
 
-    remote.help_on_no_args()
+    remote.help_on_no_arguments()
     app.add_subcommand(remote^)
 
     # ── branch ───────────────────────────────────────────────────────────
     var branch = Command("branch", "List, create, or delete branches")
+    var branch_aliases: List[String] = ["br"]
+    branch.command_aliases(branch_aliases^)
     branch.add_argument(Argument("name", help="Branch name").positional())
     branch.add_argument(
         Argument("delete", help="Delete a branch")
@@ -381,6 +387,8 @@ fn main() raises:
 
     # ── diff ─────────────────────────────────────────────────────────────
     var diff = Command("diff", "Show changes between commits, trees, etc.")
+    var diff_aliases: List[String] = ["di"]
+    diff.command_aliases(diff_aliases^)
     diff.add_argument(Argument("path", help="Path to diff").positional())
     diff.add_argument(
         Argument("staged", help="Show staged changes").long("staged").flag()
@@ -449,6 +457,8 @@ fn main() raises:
 
     # ── stash ────────────────────────────────────────────────────────────
     var stash = Command("stash", "Stash changes in working directory")
+    var stash_aliases: List[String] = ["st"]
+    stash.command_aliases(stash_aliases^)
     stash.add_argument(
         Argument("stash-message", help="Stash message")
         .long("message")
@@ -469,7 +479,7 @@ fn main() raises:
     app.add_subcommand(stash^)
 
     # ── Show help when invoked with no arguments ─────────────────────────
-    app.help_on_no_args()
+    app.help_on_no_arguments()
 
     # ── Parse & display ──────────────────────────────────────────────────
     var result = app.parse()

examples/mgit.mojo

@@ -148,7 +148,7 @@ fn main() raises:
         Argument("context", help="Print B lines before and A lines after match")
         .long("context")
         .short("C")
-        .nargs(2)
+        .number_of_values(2)
         .metavar("N")
     )
 
@@ -242,7 +242,7 @@ fn main() raises:
     app.add_tip('Use quotes for patterns with spaces: grep "fn main" ./src')
 
     # ── Show help when invoked with no arguments ─────────────────────────
-    app.help_on_no_args()
+    app.help_on_no_arguments()
 
     # ── Parse & display ──────────────────────────────────────────────────
     var result = app.parse()

examples/mgrep.mojo

@@ -44,7 +44,7 @@ struct Argument(Copyable, Movable, Stringable, Writable):
     _ = Argument("env", help="...").long("env").delimiter(",")
 
     # Multi-value  (--point 1 2 → ["1","2"])  →  result.get_list("point")
-    _ = Argument("point", help="...").long("point").nargs(2)
+    _ = Argument("point", help="...").long("point").number_of_values(2)
 
     # Numeric range validation  →  result.get_int("port")
     _ = Argument("port", help="...").long("port").range(1, 65535)
@@ -96,7 +96,7 @@ struct Argument(Copyable, Movable, Stringable, Writable):
     """If True, repeated uses collect values into a list (e.g., --tag x --tag y)."""
     var delimiter_char: String
     """If non-empty, each value is split by this delimiter into multiple list entries."""
-    var nargs_count: Int
+    var num_values: Int
     """Number of values to consume per occurrence (0 means single-value mode)."""
     var range_min: Int
     """Minimum allowed value (inclusive) for numeric range validation."""
@@ -143,7 +143,7 @@ struct Argument(Copyable, Movable, Stringable, Writable):
         self.is_negatable = False
         self.is_append = False
         self.delimiter_char = ""
-        self.nargs_count = 0
+        self.num_values = 0
         self.range_min = 0
         self.range_max = 0
         self.has_range = False
@@ -176,7 +176,7 @@ struct Argument(Copyable, Movable, Stringable, Writable):
         self.is_negatable = copy.is_negatable
         self.is_append = copy.is_append
         self.delimiter_char = copy.delimiter_char
-        self.nargs_count = copy.nargs_count
+        self.num_values = copy.num_values
         self.range_min = copy.range_min
         self.range_max = copy.range_max
         self.has_range = copy.has_range
@@ -209,7 +209,7 @@ struct Argument(Copyable, Movable, Stringable, Writable):
         self.is_negatable = move.is_negatable
         self.is_append = move.is_append
         self.delimiter_char = move.delimiter_char^
-        self.nargs_count = move.nargs_count
+        self.num_values = move.num_values
         self.range_min = move.range_min
         self.range_max = move.range_max
         self.has_range = move.has_range
@@ -404,11 +404,11 @@ struct Argument(Copyable, Movable, Stringable, Writable):
         self.is_append = True
         return self^
 
-    fn nargs(var self, n: Int) -> Self:
+    fn number_of_values(var self, n: Int) -> Self:
         """Sets the number of values consumed per occurrence.
 
         When set, each use of the option consumes exactly ``n``
-        consecutive arguments.  For example, ``.nargs(2)`` on
+        consecutive arguments.  For example, ``.number_of_values(2)`` on
         ``--point`` causes ``--point 1 2`` to collect ``["1", "2"]``.
         Implies ``.append()`` so values are stored in
         ``ParseResult.lists``.
@@ -417,9 +417,9 @@ struct Argument(Copyable, Movable, Stringable, Writable):
             n: Number of values to consume (must be ≥ 2).
 
         Returns:
-            Self with nargs and append mode set.
+            Self with num_values and append mode set.
         """
-        self.nargs_count = n
+        self.num_values = n
         self.is_append = True
         return self^