• Setup
• Registering Flags and Options
• Parsing
• Retrieving Flag and Option Values
• Positional Arguments
• Command Setup
• Command Inspection

Setup

ArgParser()

Creates a new argument parser.

You can customize an ArgParser using the methods below:

:helptext() -> str?
:helptext(text: str) -> ArgParser

Gets or sets the parser's helptext string.

• If called with no arguments, returns the parser's helptext string.
• If called with a single argument, sets the parser's helptext string. Returns the parser to enable chaining.

Specifying a helptext string for a parser activates an automatic --help flag; also a -h shortcut unless registered by another option.

:version() -> str?
:version(text: str) -> ArgParser

Gets or sets the parser's version string.

• If called with no arguments, returns the parser's version string.
• If called with a single argument, sets the parser's version string. Returns the parser to enable chaining.

Specifying a version string for a parser activates an automatic --version flag; also a -v shortcut unless registered by another option.

:enable_help_command(enable: bool) -> ArgParser

Toggles the enable_help_command flag.

This boolean flag toggles support for an automatic help command that prints subcommand helptext. The value defaults to false but gets toggled automatically to true whenever a command is registered. You can use this switch to disable the feature if required.

Returns the parser to enable chaining.

Registering Flags and Options

You can register flags and options on an ArgParser using the methods below:

:flag(name: str) -> ArgParser

Registers a new flag.

• A flag is a boolean option that is either present or absent but takes no argument.
• The name parameter accepts an unlimited number of space-separated aliases and single-character shortcuts.

Returns the parser to enable chaining.

:option(name: str) -> ArgParser
:option(name: str, default: any) -> ArgParser
:option(name: str, default: any, parser: callable(str) -> any) -> ArgParser

Registers a new option.

• The name parameter accepts an unlimited number of space-separated aliases and single-character shortcuts.
• If you don't specify a default value for an option, its default value will be null.
• If you specify a parser for an option, it should be a callable that takes a single string argument (the option's value) and returns the parsed value. It can panic or return an err to indicate failure.
• You can specify the builtin function $i64 to parse an option's value as an integer or the builtin function $f64 to parse an option's value as a float.

Returns the parser to enable chaining.

Parsing

Call the :parse() method on the root ArgParser instance to parse the program's command line arguments:

:parse(args: iterable?[str] = null) -> err?

Parses a sequence of string arguments. If args is omitted, this method defaults to parsing the program's command line arguments.

Returns an err if parsing fails, otherwise null.

You only need to call this method on the root ArgParser instance; arguments for commands will be parsed automatically.

Retrieving Flag and Option Values

You can use any of a flag or option's registered aliases or shortcuts as the name parameter in the calls below.

:count(name) -> i64

Returns the number of times the specified flag or option was found.

:found(name) -> bool

Returns true if the specified flag or option was found, false if not.

:value(name) -> any

Returns the value of the specified option.

• Returns the option's default value if the option was not found.
• If multiple values were found, returns the final value to be parsed.

:values(name) -> vec

Returns the specified option's list of values. If the option was not found, the vector will be empty.

Positional Arguments

Positional arguments are appended to the parser's .args vector.

.args: vec[str]

Stores positional arguments as a vector of strings.

Command Setup

Register a new command on a parent ArgParser instance using the :command() method:

:command(name: str) -> ArgParser

Registers a new command on an ArgParser instance.

• The name parameter accepts an unlimited number of space-separated aliases for the command.
• Returns the command's ArgParser instance which can be used to register the command's help text, flags, options, and callback function.

Register a callback function for a command on the command's ArgParser instance using the :callback() method:

:callback(callback: callable(str, ArgParser) -> any) -> ArgParser

Sets the callback function for a command parser.

If the command is found, this function will be called with the command's name and ArgParser instance as arguments.

Returns the parser to enable chaining.

Command Inspection

If a command is found, the following fields are set on the command's parent ArgParser instance:

.command_name: str?

If a command was found, this field stores the command name, otherwise null.

.command_parser: ArgParser?

If a command was found, this field stores the command's ArgParser instance, otherwise null.