arguments API

pub struct Args { const name: text, const version: text, const description: text, usage: text, bug_address: text, epilog: text, const options: vector<Arg>, const results: vector<text?>, positionals: vector<text>, help_enabled: boolean, help_idx: integer, version_idx: integer, want_help: boolean, want_version: boolean, err: text }

A command-line parser and, after parse, its result. Declare the options with flag, option, required and optional on the value create returns, call parse on the program's arguments, then read the answers with has, get, get_or and get_int, and the words that were not options from positionals. ok and error_msg report a command line that does not fit the declarations; help and version_text render the texts the user asked for with --help and --version.

pub fn create(name: text, version: text, description: text) -> Args

Start an empty parser. The three strings are what help() and version_text() render — nothing else reads them, so they are for the user and not for the parsing.

pub fn flag(self: Args, opt_short: text, opt_long: text, desc: text)

A boolean flag (--verbose / -v).

pub fn option(self: Args, opt_short: text, opt_long: text, arg_name: text, desc: text)

A value option the user may leave out (--output FILE); get answers null when it was not given. arg_name is the metavar shown in help.

pub fn required(self: Args, opt_short: text, opt_long: text, arg_name: text, desc: text)

A required value option: parse fails if it is absent.

pub fn optional(self: Args, opt_short: text, opt_long: text, arg_name: text, desc: text)

An optional-argument option: its value attaches only via = / glued form (--color=auto, -cauto); given bare (--color) it is present with value "".

pub fn set_usage(self: Args, synopsis: text)

Set the positional synopsis for the usage line (e.g. "[FILE...]").

pub fn set_bug_address(self: Args, address: text)

Set the "Report bugs to <addr>." help footer.

pub fn set_epilog(self: Args, epilog: text)

Set free text printed after the option list in help.

pub fn enable_help(self: Args)

Opt-in: register --help/-h and --version/-V, so parse records them and help() lists them. A short form goes to your own option whenever one claims the letter, declared before this call or after it. Nothing is auto-printed — the caller checks wants_help() / wants_version().

pub fn parse(self: Args, argv: vector<text>) -> boolean

Parse a command line against the declared options. Answers false on a usage error (see ok/error_msg); afterwards flags read through has, value options through get, and every non-option word lands in positionals in order.

pub fn has(self: Args, name: text) -> boolean

Was this option given? Ask by the LONG name whatever the user typed — a short, a prefix and the full name all land on the same option — or by the short name for an option declared without a long one. The question to ask a flag; get on one answers "true" or null.

pub fn get(self: Args, name: text) -> text?

The option's value, or null when it was not given. get_or and get_int are this with the absent case already handled, and are usually what you want.

pub fn get_or(self: Args, name: text, fallback: text) -> text

The option's value, or fallback when unset.

pub fn get_int(self: Args, name: text) -> integer?

The option's value parsed as an integer, or null when unset or non-numeric.

pub fn ok(self: Args) -> boolean

Did the parse succeed? The same answer parse returned, available later — so a caller that dropped the return value can still ask.

pub fn error_msg(self: Args) -> text

What went wrong, in GNU wording and ready to print. Empty when nothing did. Pair it with try_help(), which is the second line of that pair.

pub fn wants_help(self: Args) -> boolean

Did the user ask for --help? A SUCCESSFUL parse sets this, so check it before acting on the options — otherwise --help runs the program.

pub fn wants_version(self: Args) -> boolean

The same for --version; print version_text() and stop.

pub fn version_text(self: Args) -> text

The conventional one-line version banner, built from what create was told.

pub fn try_help(self: Args) -> text

The GNU "Try '<prog> --help' …" hint to print alongside a parse error.

pub fn help(self: Args) -> text

Render a GNU-format help screen from the declared options.