API Reference

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.

:error_format(fmt_string: str) -> ArgParser

Sets the format string for error messages printed to stderr.

The default format string is "error: {}". The {} placeholder contains the content of the error message.

Returns the parser to enable chaining.

:exit_on_error(enable: bool) -> ArgParser

Toggles the exit_on_error flag.

If this boolean flag is true (the default), the :parse() method will exit with an error message and a non-zero status code if the command-line arguments are invalid or if a callback function for a command panics.
If this boolean flag is false, the :parse() method will return an err instead of exiting.

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() -> ArgParser|err

Parses the program's command line arguments. Returns the parser to enable chaining.

If exit_on_error is true, exits with an error message if the command line arguments are invalid or if a command callback panics.
If exit_on_error is false, returns an err if the command line arguments are invalid or if a command callback panics.

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

:parse_args(args: vec[str]|tup[str]) -> ArgParser|err

Like :parse() but parses a vec or tup of string arguments instead of the program's command line arguments.

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 positonal arguments as a vec of strings.

Command Setup

: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.

: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.

The callback function's return value will be stored in the parent's .command_return_value field.

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.
.command_return_value: any: If a command was found, and if that command had a callback function, this field stores the callback function's return value, otherwise null.