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[R, I, O]	Parsed arguments, as returned by parse and passed to a Handler.
Error	Raised when argument parsing fails.
Help	Raised by with when help is requested and exit is false.
ArgSpec	A positional argument.
CmdSpec[R, I, O]	A subcommand.
FlagSpec	A boolean flag, set to true when present on the command line.
Handler[R, I, O]	A handler, called by with with the parsed arguments and its caller's strand input and output.
OptSpec	A named option that takes a value.
SpecItem[R, I, O]	An item of an argument specification.

ArgSpec = BaseDict[{…}]

A positional argument.

Item	Type	Description
arg	Str	Name
?parse	(Str) -> Value	Parser applied to the raw value
?default	Value	Value when absent. Without one, the argument is required
?divider	Bool	Stop interpreting later arguments as options or flags
?collect	Bool	Collect all remaining arguments in an array. Last argument only
?values	Iterable[Value]	Allowed values
?help	Str	Description shown in --help output

CmdSpec[R, I, O] = BaseDict[{…}]

A subcommand.

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.

Item	Type	Description
cmd	Str	Name
?help	Str	Description shown in --help output
?usage	Str	Replacement for the generated Usage: line
?divider	Bool	Pass every later argument, options included, verbatim to the subcommand's positional arguments
*	SpecItem[R, I, O] | Handler[R, I, O]	The subcommand's own spec items and, optionally, its handler

FlagSpec = BaseDict[{…}]

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

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

Handler[R, I, O] = ((Args[R, I, O], <I, >O) -> R)

A handler, called by with with the parsed arguments and its caller's strand input and output.

OptSpec = BaseDict[{…}]

A named option that takes a value.

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

SpecItem[R, I, O] = (FlagSpec | OptSpec | ArgSpec | CmdSpec[R, I, O])

An item of an argument specification.

Functions

parse[R, I, O] ...spec … -> Args[R, I, O]

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[R, I, O] | Handler[R, I, O])	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[R, I, O] ...spec … -> R

Parses arguments and calls the matched handler with the result.

Suited to a script's top level. By default, requested help is printed and the script exits with status 0; a parse error is printed with its hint and the script exits with status 1.

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[R, I, O] | Handler[R, I, O])	Spec items, and optionally a handler for the top level.
<	I
>	O

:program

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

Returns

The handler's result.

Errors

Exception	Condition
Error	With exit: false: as for parse, or no command where one is required
Help	With exit: false: help was requested
ValueError	The matched command has 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)"