Collecting Multiple Values
Append / Collect Action
An append option collects repeated occurrences into a list. Each time the option appears, its value is added to the list rather than overwriting the previous value.
This is a common pattern for options like --include, --tag, or --define
where more than one value is expected.
Defining an append option
command.add_argument(
Argument("tag", help="Add a tag (repeatable)")
.long["tag"]().short["t"]().append()
)
myapp --tag alpha --tag beta --tag gamma
# tags = ["alpha", "beta", "gamma"]
myapp -t alpha -t beta
# tags = ["alpha", "beta"]
myapp --tag=alpha --tag=beta
# tags = ["alpha", "beta"]
myapp -talpha -tbeta
# tags = ["alpha", "beta"]
myapp
# tags = [] (empty list, not provided)
All value syntaxes (space-separated, equals, attached short) work with append options.
Retrieving
var tags = result.get_list("tag") # List[String]
for i in range(len(tags)):
print("tag:", tags[i])
get_list() returns an empty List[String] when the option was never provided.
Help output (Append)
Append options show a ... suffix to indicate they are repeatable:
-t, --tag <tag>... Add a tag (repeatable)
If a value name is set, it replaces the default placeholder:
command.add_argument(
Argument("include", help="Include path").long["include"]().short["I"]().value_name["DIR"]().append()
)
-I, --include DIR... Include path
Combining with choices
Choices validation is applied to each individual value:
command.add_argument(
Argument("env", help="Target environment")
.long["env"]().choice["dev"]().choice["staging"]().choice["prod"]().append()
)
myapp --env dev --env prod # OK
myapp --env dev --env local # Error: Invalid value 'local' for argument 'env'
Value Delimiter
A value delimiter lets users supply multiple values in a single argument
token by splitting on a delimiter character. For example,
--env dev,staging,prod is equivalent to --env dev --env staging --env prod.
This is similar to Go cobra’s StringSliceVar and Rust clap’s
value_delimiter.
Defining a delimiter option
command.add_argument(
Argument("env", help="Target environments")
.long["env"]().short["e"]().delimiter[","]()
)
Calling .delimiter[","]() automatically implies .append() — you do not need
to call both.
myapp --env dev,staging,prod
# envs = ["dev", "staging", "prod"]
myapp --env=dev,staging
# envs = ["dev", "staging"]
myapp -e dev,prod
# envs = ["dev", "prod"]
myapp --env dev,staging --env prod
# envs = ["dev", "staging", "prod"] (values accumulate across uses)
myapp --env single
# envs = ["single"] (no delimiter → one-element list)
myapp
# envs = [] (not provided → empty list)
Trailing delimiters are ignored — --env a,b, produces ["a", "b"], not
["a", "b", ""].
Retrieving (Delimiter)
var envs = result.get_list("env") # List[String]
for i in range(len(envs)):
print("env:", envs[i])
Combining with choices (Delimiter)
Choices are validated per piece after splitting:
command.add_argument(
Argument("env", help="Target environments")
.long["env"]().choice["dev"]().choice["staging"]().choice["prod"]().delimiter[","]()
)
myapp --env dev,prod # OK
myapp --env dev,local # Error: Invalid value 'local' for argument 'env'
Other delimiters
The allowed delimiters are , ; : |. When fullwidth correction is enabled
(the default), fullwidth equivalents in user input (e.g. , ; : |)
are auto-corrected before splitting:
command.add_argument(
Argument("path", help="Search paths")
.long["path"]().delimiter[";"]()
)
myapp --path "/usr/lib;/opt/lib;/home/lib"
# paths = ["/usr/lib", "/opt/lib", "/home/lib"]
Combining with append
When a delimiter option is used multiple times, all split values accumulate:
command.add_argument(
Argument("tag", help="Tags").long["tag"]().short["t"]().append().delimiter[","]()
)
myapp --tag a,b --tag c -t d,e
# tags = ["a", "b", "c", "d", "e"]
Multi-Value Options (nargs)
Some options need to consume multiple consecutive values per occurrence.
For example, a 2D point needs two values (--point 10 20), and an RGB
colour needs three (--rgb 255 128 0).
This is similar to Python argparse’s nargs=N and Rust clap’s num_args.
Defining a multi-value option
Use .number_of_values[N]() to specify how many values the option consumes:
command.add_argument(Argument("point", help="X Y coordinates").long["point"]().number_of_values[2]())
command.add_argument(Argument("rgb", help="RGB colour").long["rgb"]().short["c"]().number_of_values[3]())
.number_of_values[N]() automatically implies .append() — values are
retrieved with get_list().
myapp --point 10 20
# point = ["10", "20"]
myapp --rgb 255 128 0
# rgb = ["255", "128", "0"]
Repeated occurrences
Each occurrence consumes N more values, all accumulating in the same list:
myapp --point 1 2 --point 3 4
# point = ["1", "2", "3", "4"]
Short options
nargs works with short options too:
myapp -c 255 128 0
# rgb = ["255", "128", "0"]
Retrieving values
var result = command.parse()
var coords = result.get_list("point")
# coords[0] = "10", coords[1] = "20"
Choices validation
Choices are validated for each value individually:
command.add_argument(
Argument("route", help="Start and end").long["route"]().number_of_values[2]()
.choice["north"]().choice["south"]().choice["east"]().choice["west"]()
)
myapp --route north east # ✓ both valid
myapp --route north up # ✗ 'up' is not a valid choice
Help output (Multi-Value)
nargs options show the placeholder repeated N times:
options:
--point <point> <point> X Y coordinates
--rgb N N N RGB colour (with .value_name["N"]())
Regular append options show ... to indicate repeatability, while nargs
options show exactly N placeholders — making the expected arity clear.
Limitations
- Equals syntax is not supported:
--point=10 20will raise an error. Use space-separated values:--point 10 20. - Insufficient values: if fewer than N values remain on the command line, an error is raised with a clear message.
Key-Value Map Options
.map_option() collects key=value pairs into a dictionary.
The option is implicitly repeatable (implies .append()), and each
value is stored in both a Dict[String, String] map and the list.
command.add_argument(
Argument("define", help="Define a variable")
.long["define"]()
.short["D"]()
.map_option()
)
myapp --define CC=gcc -D CXX=g++
# result.get_map("define") → {"CC": "gcc", "CXX": "g++"}
Equals syntax is supported — --define=CC=gcc works.
The first = is consumed by argmojo’s --long=value splitting;
the remaining CC=gcc is treated as the raw value and split at the
next = to produce key CC and value gcc.
Value with embedded = — everything after the first = in the
raw value is the value part:
myapp --define PATH=/usr/bin:/bin
# key = "PATH", value = "/usr/bin:/bin"
Delimiter — combine with .delimiter[","]() to pass multiple
key-value pairs in a single token:
command.add_argument(
Argument("define", help="Define vars")
.long["define"]()
.map_option()
.delimiter[","]()
)
myapp --define CC=gcc,CXX=g++
# result.get_map("define") → {"CC": "gcc", "CXX": "g++"}
Retrieving values — use result.get_map(name) to get a
Dict[String, String] copy of all collected pairs:
var m = result.get_map("define")
# Access individual keys: m["CC"]
If the argument was not provided, get_map() returns an empty
dictionary just like get_list() returns an empty list.
Help placeholder — map options automatically show
<key=value> instead of the default <name> placeholder:
options:
-D, --define <key=value>... Define a variable