14.6.1 Command Line Parser Construction🔗ℹ

The Parser.parse method returns a map representing the final parse state. If ~init is provided as an option form, the result of the body sequence produces a map to serve as the parser’s initial state.

Unless ~no_builtin is provided as an option, then --help/-h and -- flag support is implicitly added to the content_exprs.

The result of content_expr must be either

• a Flag object, usually as produced by cmdline.flag;

• a Multi, OnceEach, or OnceAny set of flags, usually as produced by cmdline.multi, cmdline.once_any, or cmdline.once_each;

• a Handler object for arguments after all flags, usually produced by cmdline.args;

• a Text object, usually produced by cmdline.help; or

• or a list of otherwise valid content_expr results, including nested lists.

Arguments to the flag are described by subsequent args. If maybe_ellipsis after the args is ..., then the last arg can be repeated any number of times, and its binding is a repetition. When an arg has as, then the identifier before as is used as the argument name in help text, while the identifier after as is bound to the argument value for use in a body sequence at the end of the cmdline.flag body. If annot is included, it should recognize allowed strings, and it might convert an allowed string to a different representation like the String.to_int annotation.

After options, an optional body sequence can be provided. If this body sequence is non-empty, then it is responsible for updating the parser’s state via cmdline.state; the result of the body sequence is ignored. If the body sequence is empty, then a body is created automatically:

• The body will update the current parser state with a new value for key, where key is the value produced by an expr or body sequence if a ~key option if provided. If ~key is not provided, then key is a symbol derived from the initial flag_string by dropping the leading - or + for a short-form flag or the leading two -s or +s of a long-form flag.

• If the flag’s arg ... maybe_ellipsis allows multiple arguments, then received arguments are combined in a list to add to the parser state key. If a single argument is allowed, the received argument will be added directly to the parser state. If no arguments are allowed, then #true will be added to the parser state.

• If the ~multi option is specified or if the cmdline.flag form appears syntactically with a cmdline.multi form, then key is updated in the parser state by adding to the end of an existing list value in the map, starting with the empty list if key is not in the map. Otherwise, any existing value of key is replaced with a new value.

The ~alias option can provide additional flag_strings that serve as an alias for the flag. Typically, the main flag is short-form and an alias is long-form or vice versa.

The ~help option provides text to show with the flag in help output. The string produced by the expr or body sequence in ~help can contain newline characters, and space is added to the start of lines as needed.

The ~key option specifies a key used for a default flag body, if one is created. The key is not used if the cmdline.flag form has a non-empty body sequence.

The ~init option provides an expr or body sequence that must produce a map. The keys and values of the map are added to the parser’s initial state map. Keys must be distinct across all flag handlers for a parser.

The ~multi option causes a parser using the flag to allow multiple instances of the flag in a command line. If ~multi is not present, but the the cmdline.flag form is syntactically within a cmdline.multi form, then ~multi mode is automatically enabled. Otherwise, the flag can appear at most once within a command line. A flag without ~multi can be used in cmdline.multi to allow it multiple times, but the default flag body sequence (if generated) depends only on whether the ~multi option is present or a syntactically enclosing cmdline.multi form is present.

The ~final option causes all arguments that appears after he flag to be treated as non-flag arguments. This is the behavior of the builtin -- flag, and it is rarely needed for other flags.

Combines a set of flags and constrains the way that the flags can appear in a command line. Flags grouped with cmdline.multi can be used any number of times. Flags grouped with cmdline.once_each can be used a single time each. Flags grouped with cmdline.once_any can be used a single time and only when no other flag in the same set is used.

The result of a content_expr can be a Flag, as usually produced by cmdline.flag, a set of flags that already have the new set’s property, or a list of otherwise acceptable content_expr results (including nested lists).

The set of options for cmdline.args is more limited than cmdline.flags, since it does not include flag string or flag-specific help text.

The body sequence implements argument parsing the same way as for cmdline.flag. If the body sequence is empty, the default implementation always maps #'args to a list of arguments, even if that list is always empty or always contains only one item.

A parser state map is immutable, but cmdline.state acts like a mutable variable. The mutable variable backing cmdline.state is specific to one evaluation of a handler body, so mutations to cmdline.state after the handler body returns cannot affect the result state of a parse.

The cmdline.state[key_expr] := val_expr form is allowed even though cmdline.state refers to an immutable map. It is a shorthand for an assignment to cmdline.state:

cmdline.state := cmdline.state ++ { key_expr: val_expr }

Helps text can be intermingled with flags in a form like cmdline.parse, and the text will be rendered in the same relative order as the flag and help-text implementations.

If ~after_options is provided as an option and the help text is after all flags and other help text, then it is placed after the builtin flags when those flags are not disabled (e.g., using ~no_builtin in cmdline.parse). If ~after_notation is provided as an option, then the help text is place even later, after a description of flag notation. Without ~after_options or ~after_options, trailing help text is rendered after all other text and flags, but before the help text for builtin options.