args

Declarative command-line argument parsing.

parse and with take the options, arguments, and subcommands to accept as positional spec items, written with - list syntax. Each item is a dictionary whose first key gives both its kind and its name: flag:, opt:, arg:, or cmd:.

args.parse
  help: Overall description
  - flag: verbose
  - opt: format
    short: f
    default: gz
  - arg: file
  - cmd: deploy
    - arg: service
    do |p|
      echo "Deploying $(p.deploy.service)"

An item's name becomes a field of the resulting Args, with hyphens converted to underscores: dry-run is read as p.dry_run.

Types

Type	Description
`Args`	Parsed arguments, as returned by `parse` and passed to a `Handler`.
`Error`	Error thrown when argument parsing fails.
`Help`	Help requested during argument parsing.
`ArgSpec`	A positional argument.
`CmdSpec`	A subcommand.
`FlagSpec`	A boolean flag, set to `true` when present on the command line.
`Handler`	A handler, called by `with` with the parsed arguments.
`OptSpec`	A named option that takes a value.
`SpecItem`	An item of an argument specification.

`ArgSpec = Dict[{arg: Str, ?parse: (Str) -> Value, ?default: Value, ?divider: Bool, ?collect: Bool, ?values: Iterable[Value], ?help: Str}]`

A positional argument.

Key	Meaning
`arg`	Name
`parse`	Parser applied to the raw value
`default`	Value when absent. Without one, the argument is required
`divider`	Stop interpreting later arguments as options or flags
`collect`	Collect all remaining arguments in an array. Last argument only
`values`	Allowed values
`help`	Description shown in `--help` output

`CmdSpec = Dict[{cmd: Str, ?help: Str, ?usage: Str, ...SpecItem | Handler}]`

A subcommand.

Its positional entries are the subcommand's own spec items and, optionally, its handler.

Key	Meaning
`cmd`	Name
`help`	Description shown in `--help` output
`usage`	Replacement for the generated `Usage:` line

When a subcommand is matched, the result's cmd field is its name as a symbol, such as :deploy: or :build_docs:, and its own fields are in a nested Args at p[p.cmd]. The result's handler field is the matched handler.

`FlagSpec = Dict[{flag: Str, ?long: Str | nil, ?short: Str, ?default: Bool, ?divider: Bool, ?env: Str, ?help: Str}]`

A boolean flag, set to true when present on the command line.

Key	Meaning
`flag`	Name
`long`	`--long` name. Defaults to the name; `nil` disables it
`short`	Single-character shorthand, such as `v` for `-v`
`default`	Value when absent. Defaults to `false`
`divider`	Stop interpreting later arguments as options or flags
`env`	Environment variable consulted when the flag is absent
`help`	Description shown in `--help` output

`Handler = ((Args) -> Value)`

A handler, called by with with the parsed arguments.

`OptSpec = Dict[{opt: Str, ?long: Str | nil, ?short: Str, ?parse: (Str) -> Value, ?default: Value, ?divider: Bool, ?env: Str, ?collect: Bool, ?meta: Str, ?values: Iterable[Value], ?help: Str}]`

A named option that takes a value.

Key	Meaning
`opt`	Name
`long`	`--long` name. Defaults to the name; `nil` disables it
`short`	Single-character shorthand, such as `f` for `-f`
`parse`	Parser applied to the raw value
`default`	Value when absent. Without one, the option is required
`divider`	Stop interpreting later arguments as options or flags
`env`	Environment variable consulted when the option is absent
`collect`	Accept the option several times and collect the values in an array
`meta`	Placeholder shown in help output. Defaults to the uppercased name
`values`	Allowed values
`help`	Description shown in `--help` output

`SpecItem = (FlagSpec | OptSpec | ArgSpec | CmdSpec)`

An item of an argument specification.

Functions

`parse ...spec … -> Args`

Parses command-line arguments according to a spec.

Parameters

Name	Type	Description
`:args?`	`Iterable[Str]`	Arguments to parse. Defaults to `shell.args`.
`:program?`	`Str`	Program name shown in help output and error messages.
`:help?`	`Str`	Description shown below the usage line in `--help` output.
`:usage?`	`Str`	Replacement for the generated `Usage:` line, after the program name.
`...spec`	`(SpecItem \| Handler)`	Spec items, and optionally a handler for the top level.

`:program`

Defaults to shell.program: the stem of the script filename for scripts, or the module name for modules.

Returns

The parsed arguments. When help is requested, their help field holds the rendered help text and parsing stops early.

Errors

Error for an unknown option, a missing required argument, or an invalid value. --help and -h do not raise.

Example

let p = args.parse
  - opt: format
    short: f
    default: gz
    help: Output compression format
  - arg: file
    help: Input file

echo "format=$(p.format) file=$(p.file)"

`with ...spec … -> Value`

Parses arguments and calls the matched handler with the result.

Suited to a script's top level.

Parameters

Name	Type	Description
`:args?`	`Iterable[Str]`	Arguments to parse. Defaults to `shell.args`.
`:exit?`	`Bool`	Print errors or help and exit. When `false`, raise `Error` or `Help` instead.
`:program?`	`Str`	Program name shown in help output and error messages.
`:help?`	`Str`	Description shown below the usage line in `--help` output.
`:usage?`	`Str`	Replacement for the generated `Usage:` line, after the program name.
`...spec`	`(SpecItem \| Handler)`	Spec items, and optionally a handler for the top level.

`:program`

Defaults to shell.program: the stem of the script filename for scripts, or the module name for modules.

Returns

The handler's result, or the parsed arguments when there is no handler.

Example

args.with
  help: Deploy or roll back a service.
  - cmd: deploy
    - arg: service
      help: Service name
    do |p|
      echo "Deploying $(p.deploy.service)"
  - cmd: rollback
    - arg: service
    do |p|
      echo "Rolling back $(p.rollback.service)"