Skip to content

ArgMojo v0.3.0

Choose a tag to compare

View all tags
@forfudan forfudan released this 05 Mar 11:45
· 43 commits to main since this release
v0.3.0
c3e00e9

20260305 (v0.3.0)

ArgMojo v0.3.0 adds shell completion, typo suggestions, mutual implication, hidden subcommands, NO_COLOR support, and several builder-method improvements. Internally the code is decomposed into smaller helpers and a new utils.mojo module; several API names are refined for consistency. Two breaking changes affect call sites that use nargs, max, or range (now compile-time parameters) and the renamed methods listed below.

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

⭐️ New in v0.3.0

  1. Implement shell completion script generation for Bash, Zsh, and Fish, with a built-in --completions <shell> flag that emits a ready-to-source script (PR #4).
  2. Allow disabling the built-in flag (disable_default_completions()), customising the trigger name (completions_name()), or exposing completions as a subcommand (completions_as_subcommand()) (PR #4).
  3. Add Levenshtein-distance based "did you mean ...?" suggestions for misspelled long options and subcommand names (PR #3).
  4. Implement command_aliases() on Command to register alternative names for subcommands. Aliases are shown in help, accepted during dispatch, and included in shell completions and typo suggestions (PR #5).
  5. Add .clamp() modifier for .range[min, max]() -- out-of-range values are adjusted to the nearest boundary with a warning instead of a hard error (PR #6).
  6. Move count-ceiling enforcement (.max[N]()) and range validation into the _validate() phase so all post-parse checks run in a single pass (PR #6).
  7. Parameterise .max[ceiling](), .range[min, max](), and .number_of_values[N]() as compile-time parameters, enabling build-time validation of invalid values (PR #8).
  8. Add Command.hidden() builder method. Hidden subcommands are excluded from help output, shell completions, "Available commands" error messages, and typo suggestions, while remaining dispatchable by exact name or alias (PR #9).
  9. Honour the NO_COLOR environment variable (any value, including empty). When set, all ANSI colour output from help, warning, and error messages is suppressed, following the no-color.org standard (PR #9).
  10. Add Command.implies(trigger, implied) to automatically set one argument when another is present. Supports chained implications (A -> B -> C) with cycle detection at registration time. Works with flags and count arguments, and integrates with existing constraints (required_if, mutually_exclusive) (PR #10).

🦋 Changed in v0.3.0

  1. parse_args() renamed to parse_arguments() (PR #5).
  2. help_on_no_args() renamed to help_on_no_arguments() (PR #5).
  3. .nargs() renamed to .number_of_values() and nargs_count field renamed to _number_of_values (PR #5).
  4. Several Argument and ParseResult attributes are now underscore-prefixed (private). Public builder methods are unchanged (PR #7).
  5. Decompose parse_args() into four sub-methods: _parse_long_option(), _parse_short_single(), _parse_short_merged(), _dispatch_subcommand() (PR #2).
  6. Decompose _generate_help() into five sub-methods: _help_usage_line(), _help_positionals_section(), _help_options_section(), _help_commands_section(), _help_tips_section() (PR #2).
  7. Extract ANSI colour constants and utility functions into a new internal module utils.mojo (PR #2).
  8. Rename example files to avoid confusion: git.mojo -> mgit.mojo, grep.mojo -> mgrep.mojo.
  9. Add examples/demo.mojo -- a comprehensive showcase of all ArgMojo features in a single CLI (PR #7).

📚 Documentation and testing in v0.3.0

  • Add tests/test_typo_suggestions.mojo covering Levenshtein-based suggestions (PR #3).
  • Add tests/test_completion.mojo with comprehensive tests for Bash, Zsh, and Fish script generation (PR #4).
  • Add tests/test_implies.mojo covering basic, chained, and multi-target implications, cycle detection, and constraint integration (PR #10).
  • Add builder method compatibility section to the user manual with an ASCII tree, Mermaid diagram, and compatibility table (PR #11).
  • Set up GitHub Actions workflow for automatic wiki synchronisation from docs/user_manual.md.
  • Update user manual to cover all new features.

What's Changed

  • [core] Refactor: decompose large methods & extract utils.mojo by @forfudan in #2
  • [core] Add typo-suggestion support via Levenshtein distance by @forfudan in #3
  • [core] Add shell completion support + built-in completion by @forfudan in #4
  • [core] Implement command aliases by @forfudan in #5
  • [core] Add range clamping + conduct ceiling and clamping at validation phase + warning message by @forfudan in #6
  • [core][demo] Provide a new demo + make some attributes private + rename some attributes and methods by @forfudan in #7
  • [core] Parameterize some arguments to enable compile-time check by @forfudan in #8
  • [core] Add hidden subcommands + NO-COLOR option by @forfudan in #9
  • [core] Add mutual implication functionality by @forfudan in #10
  • [doc] Add compatibility charts in user manual showing relationship between builder methods by @forfudan in #11

Full Changelog: v0.2.0...v0.3.0

Contributors

forfudan
Assets 2
Loading