@eryx/argparse ModuleImperative command-line argument parser.
Supports positional arguments, flags, options with values, subcommands,
and merged short flags. A built-in --help/-h flag is registered by
default and can be customised or disabled.
local argparse = require("@eryx/argparse")
local parser = argparse.Parser.new("mytool", "A handy CLI")
parser:addPositional("file", "string", nil, true, "Input file")
parser:addFlag("verbose", "v", "Enable verbose output")
parser:addOption("port", "p", "number", 8080, nil, "Port to listen on")
local run = parser:addSubCommand("run", "Run a script")
run:addPositional("script", "string", nil, true, "Script to run")
local config = parser:parse()
A command-line parser that can be configured with positional arguments, boolean flags, key-value options, and subcommands.
Every new parser comes with a built-in --help/-h flag. Use
Parser.disableHelp to remove it or Parser.setHelpHandler to replace its
behaviour.
The program or subcommand name shown in help text.
One-line summary printed below the usage line.
Text printed at the very end of help output.
Registered positional arguments, in order.
Registered boolean flags.
Registered key-value options.
Registered subcommands, keyed by name.
Mutually exclusive groups of flag/option names.
Whether the built-in --help / -h behavior is active.
The function invoked when --help is parsed.
Creates a new Parser.
The parser starts with a built-in --help/-h flag that prints
generated help text and exits.
The program or subcommand name shown in usage text.
One-line summary printed below the usage line.
Text printed at the very end of help output.
A new parser ready to be configured.
Registers a subcommand under this parser.
When the subcommand name is encountered during parsing, all remaining arguments are delegated to the subcommand's parser. The subcommand's result table is stored under its name in the parent result.
The subcommand name (must not collide with an existing subcommand).
One-line summary shown in help text.
Text printed at the end of the subcommand's help.
The new subcommand parser, ready to be configured.
Removes the built-in --help/-h flag and sets the help handler to
a no-op. After calling this, --help and -h are free to be
re-registered as custom flags or options.
Replaces the built-in help behaviour with a custom handler.
The handler receives the parser so it can call Parser.generateHelp or
inspect registered arguments. The built-in --help/-h flag remains
registered; only the action changes.
parser:setHelpHandler(function(p)
io.write(p:generateHelp())
os.exit(2)
end)
A function called when --help or -h is parsed.
Registers a positional argument.
Positional arguments are consumed left-to-right in the order they are added. Required positionals must come before any optional ones.
If a default is provided the positional is automatically optional.
To make a positional optional with no default, pass nil for default
and false for required.
Set variadic to true to let the positional consume all remaining
arguments. Variadic positionals must be the final positional.
Key used in the result table.
"string" or "number" - numeric values are coerced automatically.
Default value when omitted. Implies optional when non-nil.
Whether the argument must be provided. Defaults to true unless a default is given.
Human-readable text shown in help output.
Whether this positional should consume all remaining values.
Registers a boolean flag (true when present, false when absent).
Flags can be combined in short form: -vh sets both -v and -h.
The --long name (without dashes).
Optional single-character -s alias.
Human-readable text shown in help output.
Registers a key-value option.
Options consume the next argument (or the =-separated value) as their
value. In merged short form the last character is treated as the option
and everything after it (or the next argument) is the value:
-vp 8080 sets -v (flag) and -p 8080 (option).
If a default is provided the option is automatically optional.
To make an option optional with no default, pass nil for default
and false for required.
settings.multiple = true allows an option to be repeated and collects
its values into an array. settings.arity controls how many values each
occurrence consumes.
The --long name (without dashes).
Optional single-character -s alias.
"string" or "number" - numeric values are coerced automatically.
Default value when omitted. Implies optional when non-nil.
Whether the option must be provided. Defaults to true unless a default is given.
Human-readable text shown in help output.
Optional parser settings such as multiple and arity.
Registers a mutually exclusive group of flags/options by long name.
At most one name in the group may be present during parsing. If required
is true, exactly one member must be present.
Returns shell completion candidates for the parser after consuming the provided fully-typed arguments.
This is intentionally conservative: if the parser is currently waiting for an option value it returns no candidates so the shell can fall back to filename or custom value completion.
Generates a shell completion script for this parser.
Supports "bash", "zsh", "fish", and "powershell", and generates
subcommand-aware completions for commands and flags/options.
Builds a human-readable help string from the parser's current configuration, including usage line, description, arguments, subcommands, flags, options, and epilog.
The formatted help text.
Parses command-line arguments against this parser's configuration.
Parsing supports:
--verbose, --port 8080, --port=8080.-v, -p 8080.-vh expands to -v -h.
The last character may be an option: -vp 8080 -> -v flag + -p 8080 option.If the built-in --help flag is set, the help handler is invoked
before required-argument validation, so mytool --help always works.
Argument list to parse. Defaults to os.cliargs().
A table mapping argument names to their parsed values.