ArgMojo v0.2.0

20260228 (v0.2.0)

ArgMojo v0.2.0 is a major release that transforms the library from a single-command parser into a full subcommand-capable CLI framework. It introduces hierarchical subcommands with automatic dispatch, persistent (global) flags with bidirectional sync, negative number passthrough, colored error messages, custom tips, and significant help/UX improvements. The public API is also refined: Arg → Argument (old name kept as alias). Two complete example CLIs (grep and git) replace the previous demo.

ArgMojo v0.2.0 is compatible with Mojo v0.26.1.

⭐️ New in v0.2.0

Subcommands:

1. Implement full subcommand support with add_subcommand() API, hierarchical dispatch, and nested subcommands (e.g., git remote add).
2. Auto-register a help subcommand so that app help <command> works out of the box; opt out with disable_help_subcommand().
3. 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.
4. Add subcommand and subcommand_result fields on ParseResult with has_subcommand_result() / get_subcommand_result() accessors.

Persistent flags:

1. Add .persistent() builder method on Argument to mark a flag as global.
2. Persistent args are automatically injected into child commands and support bidirectional sync: flags set before the subcommand push down to the child, and flags set after the subcommand bubble up to the root.
3. Detect conflicting long/short names between parent persistent args and child local args at registration time (add_subcommand() raises an error).

Negative number passthrough:

1. Recognize negative numeric tokens like -3.14 or -42 as positional values instead of unknown short options.
2. Add allow_negative_numbers() opt-in on Command for explicit control.

Custom tips:

1. Add add_tip() API on Command to attach user-defined tips that render as a dedicated section at the bottom of help output.

Error handling:

1. Colored error and warning messages — ANSI-styled stderr output for all parse errors.
2. Unknown subcommand error now lists all available commands.
3. Errors inside child parse are prefixed with the full command path (e.g., git remote add: ...).

🦋 Changed in v0.2.0

API rename:

1. Rename Arg struct to Argument. The old name is kept as alias for convenience.
2. Rename source files: arg.mojo → argument.mojo, result.mojo → parse_result.mojo.

Help & UX improvements:

1. Add a "Commands" section to help output listing available subcommands with aligned descriptions.
2. Show <COMMAND> placeholder in the usage line for commands that have subcommands.
3. Display persistent flags under a "Global Options" heading in child help.
4. Show the full command path in child help and error messages (e.g., Usage: git remote add [OPTIONS] NAME URL).

Internal refactoring:

1. Extract _apply_defaults() and _validate() into private helper methods on Command, enabling clean reuse for both root and child parsing.

📚 Documentation and testing in v0.2.0

• Add two complete example CLIs: examples/grep.mojo (single-command, demonstrating all argument features) and examples/git.mojo (subcommand-based, with nested subcommands and persistent flags).
• Add tests/test_subcommands.mojo covering data model, dispatch, help subcommand, persistent flags, allow-positional guard, and error handling.
• Add tests/test_negative_numbers.mojo.
• Add tests/test_persistent.mojo.
• Update user manual (docs/user_manual.md) to cover all new features.