Defining Arguments
Positional Arguments
Positional arguments are matched by order, not by name. They do not start
with - or --.
command.add_argument(Argument("pattern", help="Search pattern").positional().required())
command.add_argument(Argument("path", help="Search path").positional().default["."]())
myapp "hello" ./src
# ↑ ↑
# pattern path
Positional arguments are assigned in the order they are registered with
add_argument(). If fewer values are provided than defined arguments, the
remaining ones use their default values (if any). If more are provided, an error
is raised (see
Positional Argument Count Validation).
Retrieving:
var pattern = result.get_string("pattern") # "hello"
var path = result.get_string("path") # "./src"
Long Options
Long options start with -- and can receive a value in two ways:
| Syntax | Example | Description |
|---|---|---|
--key value | --output result.txt | Space-separated value. |
--key=value | --output=result.txt | Equals-separated value. |
command.add_argument(Argument("output", help="Output file").long["output"]())
myapp --output result.txt
myapp --output=result.txt
Both forms produce the same result:
result.get_string("output") # "result.txt"
Short Options
Short options use a single dash followed by a single character.
command.add_argument(
Argument("output", help="Output file").long["output"]().short["o"]()
)
myapp -o result.txt # space-separated
myapp -oresult.txt # attached value (see §9)
A short name is typically defined alongside a long name, but can also be used alone.
Compile-time validation. Both
.long["x"]()and.short["x"]()accept aStringLiteralparameter..shortenforces that the name is exactly one character;.longenforces that the name is non-empty and does not start with-. Invalid names are caught at compile time — the program will not compile.
Boolean Flags
A flag is a boolean option that takes no value. It is False by default and
becomes True when present.
command.add_argument(
Argument("verbose", help="Enable verbose output")
.long["verbose"]().short["v"]().flag()
)
myapp --verbose # verbose = True
myapp -v # verbose = True
myapp # verbose = False (default)
Retrieving: (Flags)
var verbose = result.get_flag("verbose") # Bool
Default Values
When an argument is not provided on the command line, its default value (if any) is used.
command.add_argument(
Argument("format", help="Output format")
.long["format"]().short["f"]().default["table"]()
)
command.add_argument(
Argument("path", help="Search path").positional().default["."]()
)
myapp "hello" # format = "table", path = "."
myapp "hello" --format csv # format = "csv", path = "."
myapp "hello" ./src # format = "table", path = "./src"
Works for every kind of argument, and the default always lands where that argument’s own accessor reads it:
| Argument kind | Default is read back with | Example |
|---|---|---|
| plain option | get_string() / get_int() | .default["table"]() |
| positional | get_string() | .default["."]() |
.flag() | get_flag() | .default["true"]() |
.count() | get_count() | .default["2"]() |
.append() | get_list() | .default["x"]() |
.map_option() | get_map() | .default["A=1"]() |
A default that does not fit its argument is rejected when you call
add_argument(), rather than when your user runs the program. A .flag()
default must be a boolean literal (true/false, 1/0, yes/no,
on/off); a .count() default must be an integer; a .map_option() default
must be in key=value form; and if the argument has .choice[](), the default
must be one of those choices.
Keep in mind that a default is not user input. was_provided() returns False
for it, and it never satisfies a group constraint on its own — though it does
satisfy .required() on the argument that carries it.
Required Arguments
Mark an argument as required to make parsing fail when it is absent.
command.add_argument(
Argument("pattern", help="Search pattern").positional().required()
)
myapp "hello" # OK
myapp # Error: Required argument 'pattern' was not provided
Typically used for positional arguments. Named options can also be marked required.
Aliases
Register alternative long names for an argument with .alias[](). The alias is
validated at compile time (same rules as .long[](): not empty, no - prefix,
no =). Chain multiple calls for several aliases.
.alias[]()was called.alias_name[]()until Mojo v1.1.0 freed thealiaskeyword, and thealias=parameter ofOption,FlagandCountwas calledalias_name=. The old spellings were deprecated in ArgMojo v0.9.0 and removed in v0.10.0; replace.alias_name[with.alias[andalias_name=withalias=.
command.add_argument(
Argument("colour", help="Colour theme")
.long["colour"]()
.alias["color"]()
)
myapp --colour red # OK — colour = "red"
myapp --color red # OK — resolved via alias, colour = "red"
Prefix matching applies to aliases as well. When both the
primary name and an alias share a prefix, _find_by_long deduplicates
so the match is never ambiguous within a single argument.
Multiple aliases are supported by chaining:
command.add_argument(
Argument("output", help="Output format")
.long["output"]()
.alias["out"]().alias["fmt"]()
)