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:
| Method | What 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:
| Method | What 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 |
Recommended Workflow
To ensure your CLI definition is free of developer errors:
- Compile your application (
mojo build …) — catches compile-time parameter errors (wrong colour names, invalid builder values, etc.). - 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=allwith--help. This exercises both compile-time and registration-time validation in one step. The CI workflow runspixi run package,pixi run test, andpixi run debug, so pull requests automatically catch both classes of errors.