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

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) because List[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]