Value Validation
Choices Validation
Restrict an option’s value to a fixed set of allowed strings. If the user provides a value not in the set, parsing fails with a clear error message.
command.add_argument(
Argument("log-level", help="Log level")
.long["log-level"]().choice["debug"]().choice["info"]().choice["warn"]().choice["error"]().default["info"]()
)
myapp --log-level debug # OK
myapp --log-level trace # Error: Invalid value 'trace' for argument 'log-level'
# (choose from 'debug', 'info', 'warn', 'error')
In help text, choices are shown automatically:
--log-level {debug,info,warn,error} Log level
Combining with short options and attached values:
myapp -ldebug # (if short name is "l") OK
myapp -l trace # Error, same as above
Tip
You need to pass the
List[String]with^(ownership transfer) or.copy()(a new copy) becauseList[String]is not implicitly copyable in Mojo. This design choice avoids unnecessary copying.
Positional Argument Count Validation
ArgMojo ensures that the user does not provide more positional arguments than defined. Extra positional values trigger an error.
command.add_argument(Argument("pattern", help="Search pattern").positional().required())
# Only 1 positional arg is defined.
myapp "hello" # OK
myapp "hello" extra1 extra2 # Error: Too many positional arguments: expected 1, got 3
With two positional args defined:
command.add_argument(Argument("pattern", help="Search pattern").positional().required())
command.add_argument(Argument("path", help="Search path").positional().default["."]())
myapp "hello" ./src # OK — pattern = "hello", path = "./src"
myapp "hello" ./src /tmp # Error: Too many positional arguments: expected 2, got 3
Numeric Range Validation
Constrain a numeric argument to an inclusive [min, max] range
with .range[min, max](). The validation is applied after parsing,
so the value is still stored as a string; atol() is used internally
to convert and compare.
command.add_argument(
Argument("port", help="Listening port")
.long["port"]()
.range[1, 65535]()
)
myapp --port 8080 # OK
myapp --port 0 # Error: Value 0 for '--port' is out of range [1, 65535]
myapp --port 70000 # Error: Value 70000 for '--port' is out of range [1, 65535]
Boundary values — both min and max are inclusive:
myapp --port 1 # OK
myapp --port 65535 # OK
Append / list values — when combined with .append() or
.delimiter[","](), every collected value is validated individually:
command.add_argument(
Argument("port", help="Ports").long["port"]().append().range[1, 100]()
)
myapp --port 50 --port 101
# Error: Value 101 for '--port' is out of range [1, 100]
Range Clamping (.clamp())
By default, an out-of-range value causes a hard error. If you prefer a gentler
approach, chain .clamp() after .range[min, max]() to adjust the value to
the nearest boundary and print a warning instead of failing.
command.add_argument(
Argument("level", help="Compression level (0–9)")
.long["level"]()
.range[0, 9]()
.clamp()
)
myapp --level 5 # OK — level = 5
myapp --level 20 # Warning, level = 9 (clamped to max)
myapp --level -3 # Warning, level = 0 (clamped to min)
The warning looks like:
warning: '--level' value 20 is out of range [0, 9], clamped to 9
With append mode — each collected value is clamped individually:
command.add_argument(
Argument("port", help="Ports").long["port"]().append().range[1, 100]().clamp()
)
myapp --port 50 --port 200 --port 0
# warning: '--port' value 200 is out of range [1, 100], clamped to 100
# warning: '--port' value 0 is out of range [1, 100], clamped to 1
# Result: ports = [50, 100, 1]
Without .clamp() — the existing behaviour is unchanged; an out-of-range
value raises an error:
myapp --port 200
# Error: Value 200 for '--port' is out of range [1, 100]