[core] Implement command aliases by forfudan · Pull Request #5 · forfudan/argmojo

forfudan · 2026-03-02T19:37:12Z

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).

Copilot

Pull request overview

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).

Changes:

Add command_aliases() method on Command to register alternate dispatch names for subcommands
Rename parse_args() → parse_arguments(), help_on_no_args() → help_on_no_arguments(), .nargs() → .number_of_values(), and nargs_count → num_values across all source, test, example, and documentation files
Update shell completion generators (bash, zsh, fish) and help output to include aliases

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
`src/argmojo/command.mojo`	Core changes: `_command_aliases` field, `command_aliases()` builder, `_find_subcommand()` alias support, alias in help/completions/typo suggestions, API renames
`src/argmojo/argument.mojo`	Rename `nargs_count` → `num_values`, `nargs()` → `number_of_values()`
`tests/test_subcommands.mojo`	New Step 5 alias tests; `parse_args` → `parse_arguments` rename throughout
`tests/test_parse.mojo`	`parse_args` → `parse_arguments` rename
`tests/test_help.mojo`	Rename `nargs()` → `number_of_values()`, `parse_args` → `parse_arguments`, test function rename
`tests/test_persistent.mojo`	`parse_args` → `parse_arguments` rename
`tests/test_groups.mojo`	`parse_args` → `parse_arguments` rename
`tests/test_extras.mojo`	`parse_args` → `parse_arguments`, `nargs()` → `number_of_values()` rename
`tests/test_collect.mojo`	`parse_args` → `parse_arguments`, `nargs()` → `number_of_values()` rename
`tests/test_negative_numbers.mojo`	`parse_args` → `parse_arguments` rename
`tests/test_typo_suggestions.mojo`	`parse_args` → `parse_arguments` rename
`examples/mgrep.mojo`	`nargs()` → `number_of_values()`, `help_on_no_args()` → `help_on_no_arguments()`
`examples/mgit.mojo`	`help_on_no_args()` → `help_on_no_arguments()`, alias registration for clone/commit/branch/diff/stash
`docs/user_manual.md`	Update API references
`docs/changelog.md`	Document alias feature and API rename
`docs/argmojo_overall_planning.md`	Naming conventions section, feature table updates, planning notes

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-02T19:49:32Z

src/argmojo/command.mojo

+                # Build label: "name" or "name, alias1, alias2".
+                var label = self.subcommands[i].name
+                for _ai in range(len(self.subcommands[i]._command_aliases)):
+                    label += ", " + self.subcommands[i]._command_aliases[_ai]
+                var plain = String("  ") + label
+                var colored = String("  ") + arg_color + label + reset_code


The new alias feature adds behavior to help output (showing "clone, cl" inline) and to all three shell completion generators (bash, zsh, fish), but there are no tests covering these behaviors. Given that test_help.mojo and test_completion.mojo already have comprehensive tests for related behaviors (e.g., subcommand display in help, and subcommand-level completions), tests for the following should be added:

Help output shows aliases inline (e.g., "clone, cl" appears in the help text).

Fish completion script includes alias entries.

Zsh completion script includes alias entries.

Bash completion script includes alias pattern (e.g., clone|cl)).

Copilot · 2026-03-02T19:49:32Z

src/argmojo/argument.mojo

@@ -419,7 +419,7 @@ struct Argument(Copyable, Movable, Stringable, Writable):
        Returns:
            Self with nargs and append mode set.


The return description in the docstring still says "Self with nargs and append mode set." after renaming from nargs() to number_of_values(). It should be updated to say "Self with num_values and append mode set." to stay consistent with the renamed field and method.

Suggested change

Self with nargs and append mode set.

Self with num_values and append mode set.

Copilot · 2026-03-02T19:49:32Z

src/argmojo/command.mojo

@@ -1365,9 +1397,11 @@ struct Command(Copyable, Movable, Stringable, Writable):
        # Exact subcommand name match → dispatch.


The inline comment "# Exact subcommand name match → dispatch." at line 1397 is now misleading because _find_subcommand() also matches aliases (not just exact primary names). The comment should be updated to reflect that it matches primary names or aliases.

Suggested change

# Exact subcommand name match → dispatch.

# Exact subcommand (name or alias) match → dispatch.

Copilot · 2026-03-02T19:49:33Z

src/argmojo/command.mojo

                var sub_names = List[String]()
                for _si2 in range(len(self.subcommands)):
                    if not self.subcommands[_si2]._is_help_subcommand:
                        sub_names.append(self.subcommands[_si2].name)
+                        for _ai2 in range(
+                            len(self.subcommands[_si2]._command_aliases)
+                        ):
+                            sub_names.append(
+                                self.subcommands[_si2]._command_aliases[_ai2]
+                            )
                var suggestion = _suggest_similar(arg, sub_names)


The PR adds aliases to the subcommand typo suggestion candidates (so that typing "clon" could suggest "clone" or "cl"), but there is no test covering this behavior. Given that test_typo_suggestions.mojo has tests for subcommand typo suggestions, a test like "test_typo_subcommand_alias_suggests" that verifies a near-miss of a subcommand alias triggers a useful suggestion would complete the coverage for this new behavior.

Copilot · 2026-03-02T19:49:33Z

docs/argmojo_overall_planning.md

 | Persistent (global) flags          | —        | —     | ✓     | ✓    | git `--no-pager` etc.  | **Done**      |
-| Subcommand aliases                 | —        | —     | ✓     | ✓    |                        | Phase 5       |
+| Suggest on typo (Levenshtein)      | ✓ (3.14) | —     | ✓     | ✓    |                        | **Done**      |
+| Subcommand aliases                 | —        | —     | ✓     | ✓    | ✅ Done                 | Phase 5       |


In the feature table on line 63, the "Subcommand aliases" row has "✅ Done" in the "Example" column (which is meant to list existing tools that have the feature, not status) and still shows "Phase 5" in the "Status" column. Based on all other rows with completed features, the status column should read "Done" now that the feature is implemented. The "Example" cell should be reverted to a reference to similar tools (cobra/clap), not a completion note.

Suggested change

| Subcommand aliases | — | — | ✓ | ✓ | ✅ Done | Phase 5 |

| Subcommand aliases | — | — | ✓ | ✓ | cobra, clap | **Done** |

Copilot · 2026-03-02T19:49:33Z

src/argmojo/command.mojo

+    var _command_aliases: List[String]
+    """Alternate names for this command when used as a subcommand.
+    Add entries via ``command_aliases()``.  Aliases are matched during
+    subcommand dispatch but are not shown as separate entries in help."""


The field docstring says aliases are "not shown as separate entries in help," but the actual implementation (and the command_aliases() method docstring) shows them inline next to the primary name (e.g., "clone, cl"). The field docstring should be updated to reflect the actual behavior to avoid confusion. It should say something like "Aliases are not shown as separate entries; they appear inline next to the primary name."

Suggested change

subcommand dispatch but are not shown as separate entries in help."""

subcommand dispatch and are not shown as separate entries in help;

instead, they appear inline next to the primary name (e.g., "clone, cl")."""

forfudan added 4 commits March 2, 2026 13:30

command aliases

4ef6308

Rename aliases -> command_aliases

bd0b0a1

Rename some functions to be more specific

83de47e

Rename nargs -> number_of_values for explicity

f9cf448

forfudan requested a review from Copilot March 2, 2026 19:37

Copilot started reviewing on behalf of forfudan March 2, 2026 19:37 View session

Copilot AI reviewed Mar 2, 2026

View reviewed changes

Address comments

cb3f1e6

forfudan merged commit 6e4d491 into main Mar 2, 2026
2 checks passed

forfudan deleted the update branch March 2, 2026 20:31

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[core] Implement command aliases#5

[core] Implement command aliases#5
forfudan merged 5 commits intomainfrom
update

forfudan commented Mar 2, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 2, 2026

Uh oh!

Copilot AI Mar 2, 2026

Uh oh!

Copilot AI Mar 2, 2026

Uh oh!

Copilot AI Mar 2, 2026

Uh oh!

Copilot AI Mar 2, 2026

Uh oh!

Copilot AI Mar 2, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		@@ -419,7 +419,7 @@ struct Argument(Copyable, Movable, Stringable, Writable):
		Returns:
		Self with nargs and append mode set.

	Self with nargs and append mode set.
	Self with num_values and append mode set.

		@@ -1365,9 +1397,11 @@ struct Command(Copyable, Movable, Stringable, Writable):
		# Exact subcommand name match → dispatch.

	# Exact subcommand name match → dispatch.
	# Exact subcommand (name or alias) match → dispatch.

	\| Subcommand aliases \| — \| — \| ✓ \| ✓ \| ✅ Done \| Phase 5 \|
	\| Subcommand aliases \| — \| — \| ✓ \| ✓ \| cobra, clap \| Done \|

	subcommand dispatch but are not shown as separate entries in help."""
	subcommand dispatch and are not shown as separate entries in help;
	instead, they appear inline next to the primary name (e.g., "clone, cl")."""

Conversation

forfudan commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

forfudan commented Mar 2, 2026 •

edited

Loading