Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Developer Validation

ArgMojo provides two layers of validation to catch developer mistakes as early as possible — before end users ever see them.

Compile-Time Validation

All Argument builder methods that accept fixed, known values use compile-time parameters (StringLiteral). The Mojo compiler rejects invalid values during mojo build, so the binary is never produced:

# ✓ Valid — compiles successfully
Argument("verbose", help="Verbose output").long["verbose"]().short["v"]().flag()

# ✗ Compile error — "REED" is not a valid colour name
command.header_color["REED"]()   # caught by comptime assert at compile time

Methods validated at compile time include:

MethodWhat is checked
.long[name]()Long option name is a StringLiteral
.short[ch]()Short option character is a StringLiteral
.choice[val]()Choice value is a StringLiteral
.default[val]()Default value is a StringLiteral
.value_name[name]()Value placeholder is a StringLiteral
.max[N]()Count ceiling is a positive Int
.number_of_values[N]()Value count is a positive Int
.range[min, max]()Range bounds are valid Int values
header_color[name]()Colour name is one of the accepted names
argument_color[name]()Same as above
warn_color[name]()Same as above
error_color[name]()Same as above
response_file_max_depth[N]()Depth is a positive Int

Runtime Registration Validation

Some Command-level methods accept argument names as strings to define group constraints or relationships. Because the set of registered arguments is built dynamically at runtime (via add_argument()), these names cannot be validated at compile time.

Instead, ArgMojo validates them at registration time — the moment you call the method, not when the end user provides input. If any name does not match a registered argument, an Error is raised immediately:

var command = Command("myapp", "A sample application")
command.add_argument(Argument("json", help="JSON output").long["json"]().flag())
command.add_argument(Argument("yaml", help="YAML output").long["yaml"]().flag())

# ✓ Valid — both names are registered
command.one_required(["json", "yaml"])

# ✗ Runtime Error — "ymal" is not a registered argument
# Error: one_required(): unknown argument 'ymal'
command.one_required(["json", "ymal"])   # typo caught on first execution

This error fires every time the program starts, during command construction, regardless of what arguments the end user passes. The developer sees it on their very first mojo run.

Methods validated at registration time:

MethodWhat is checked
mutually_exclusive(names)All names exist in self.args
required_together(names)All names exist in self.args
one_required(names)All names exist in self.args
required_if(target, condition)Both names exist in self.args
implies(trigger, implied)Both names exist, implied is a flag/count, no cycles

To ensure your CLI definition is free of developer errors:

  1. Compile your application (mojo build …) — catches compile-time parameter errors (wrong colour names, invalid builder values, etc.).
  2. Run the executable once (even without arguments) — catches registration-time errors (typos in argument names passed to group constraints).

Note that a single mojo run is enough (it sequentially builds and then executes the binary).

ArgMojo contributors: the repository provides pixi run debug, which packages the library and runs every example under -D ASSERT=all with --help. This exercises both compile-time and registration-time validation in one step. The CI workflow runs pixi run package, pixi run test, and pixi run debug, so pull requests automatically catch both classes of errors.