Miscellaneous

Generating and overwriting help and usage messages

The usage and help messages of parsers and commands can be generated on demand using :get_usage() and :get_help() methods, and overridden using help and usage properties.

Overwriting default help option

If the property add_help of a parser is set to false, no help option will be added to it. Otherwise, the value of the field will be used to configure it.

1
2
local parser = argparse()
   :add_help "/?"
$ lua script.lua /?
Usage: script.lua [/?]

Options:
   /?                    Show this help message and exit.

Setting argument placeholder

For options and arguments, argname property controls the placeholder for the argument in the usage message.

1
2
parser:option "-f" "--from"
   :argname "<server>"
$ lua script.lua --help
Usage: script.lua [-f <server>] [-h]

Options:
   -f <server>, --from <server>
   -h, --help            Show this help message and exit.

argname can be an array of placeholders.

1
2
3
parser:option "--pair"
   :args(2)
   :argname {"<key>", "<value>"}
$ lua script.lua --help
Usage: script.lua [--pair <key> <value>] [-h]

Options:
   --pair <key> <value>
   -h, --help            Show this help message and exit.

Disabling option handling

When handle_options property of a parser or a command is set to false, all options will be passed verbatim to the argument list, as if the input included double-hyphens.

1
2
3
4
5
parser:handle_options(false)
parser:argument "input"
   :args "*"
parser:option "-f" "--foo"
   :args "*"
$ lua script.lua bar -f --foo bar
{
   input = {"bar", "-f", "--foo", "bar"}
}

Prohibiting overuse of options

By default, if an option is invoked too many times, latest invocations overwrite the data passed earlier.

1
parser:option "-o --output"
$ lua script.lua -oFOO -oBAR
{
   output = "BAR"
}

Set overwrite property to false to prohibit this behavior.

1
2
parser:option "-o --output"
   :overwrite(false)
$ lua script.lua -oFOO -oBAR
Usage: script.lua [-o <output>] [-h]

Error: option '-o' must be used at most 1 time

Parsing algorithm

argparse interprets command line arguments in the following way:

Argument Interpretation
foo An argument of an option or a positional argument.
--foo An option.
--foo=bar An option and its argument. The option must be able to take arguments.
-f An option.
-abcdef Letters are interpreted as options. If one of them can take an argument, the rest of the string is passed to it.
-- The rest of the command line arguments will be interpreted as positional arguments.

Property lists

Parser properties

Properties that can be set as arguments when calling or constructing a parser, in this order:

Property Type
name String
description String
epilog String

Other properties:

Property Type
usage String
help String
require_command Boolean
handle_options Boolean
add_help Boolean or string or table

Command properties

Properties that can be set as arguments when calling or constructing a command, in this order:

Property Type
name String
description String
epilog String

Other properties:

Property Type
target String
usage String
help String
require_command Boolean
handle_options Boolean
action Function
add_help Boolean or string or table

Argument properties

Properties that can be set as arguments when calling or constructing an argument, in this order:

Property Type
name String
description String
default String
convert Function or table
args Number or string

Other properties:

Property Type
target String
defmode String
show_default Boolean
argname String or table

Option and flag properties

Properties that can be set as arguments when calling or constructing an option or a flag, in this order:

Property Type
name String
description String
default String
convert Function or table
args Number or string
count Number or string

Other properties:

Property Type
target String
defmode String
show_default Boolean
overwrite Booleans
argname String or table
action Function