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

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 20 will 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