Configuring 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.
When using the autogenerated usage and help messages, there are several ways to adjust them.
Hiding arguments, options, and commands from messages¶
If hidden
property for an argument, an option or a command is set to true
,
it is not included into help and usage messages, but otherwise works normally.
1 2 3 | parser:option "--normal-option"
parser:option "--deprecated-option"
:hidden(true)
|
$ lua script.lua --help
Usage: script.lua [-h] [--normal-option <normal_option>]
Options:
-h, --help Show this help message and exit.
--normal-option <normal_option>
$ lua script.lua --deprecated-option value
{
deprecated_option = "value"
}
Hiding option and command aliases¶
Hidden aliases can be added to an option or command by setting the
hidden_name
property. Its value is interpreted in the same way as the
name
property.
1 2 | parser:option "--server"
:hidden_name "--from"
|
$ lua script.lua --help
Usage: script.lua [-h] [--server <server>]
Options:
-h, --help Show this help message and exit.
--server <server>
$ lua script.lua --server foo
$ lua script.lua --from foo
{
server = "foo"
}
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 [-h] [-f <server>]
Options:
-h, --help Show this help message and exit.
-f <server>, --from <server>
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 [-h] [--pair <key> <value>]
Options:
-h, --help Show this help message and exit.
--pair <key> <value>
Grouping elements¶
:group(name, ...)
method of parsers and commands puts passed arguments, options, and commands into
a named group with its own section in the help message. Elements outside any groups are put into a default section.
1 2 3 4 5 6 7 8 9 10 11 12 13 | parser:group("Configuring output format",
parser:flag "-v --verbose",
parser:flag "--use-colors",
parser:option "--encoding"
)
parser:group("Configuring processing",
parser:option "--compression-level",
parser:flag "--skip-broken-chunks"
)
parser:flag "--version"
:action(function() print("script.lua 1.0.0") os.exit(0) end)
|
$ lua script.lua --help
Usage: script.lua [-h] [-v] [--use-colors] [--encoding <encoding>]
[--compression-level <compression_level>]
[--skip-broken-chunks] [--version]
Configuring output format:
-v, --verbose
--use-colors
--encoding <encoding>
Configuring processing:
--compression-level <compression_level>
--skip-broken-chunks
Other options:
-h, --help Show this help message and exit.
--version
Help message line wrapping¶
If help_max_width
property of a parser or a command is set, when generating its help message, argparse will automatically
wrap lines, attempting to fit into given number of columns. This includes wrapping lines in parser description and epilog
and descriptions of arguments, options, and commands.
Line wrapping preserves existing line endings and only splits overly long input lines.
When breaking a long line, it replicates indentation of the line in the continuation lines.
Additionally, if the first non-space token in a line is *
, +
, or -
, the line is considered a list item,
and the continuation lines are aligned with the first word after the list item marker.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | parser:help_max_width(80)
parser:option "-f --foo"
:description("Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor " ..
"incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation " ..
"ullamco laboris nisi ut aliquip ex ea commodo consequat.\n" ..
"The next paragraph is indented:\n" ..
" Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. " ..
"Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.")
parser:option "-b --bar"
:description("Here is a list:\n"..
"* Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor...\n" ..
"* Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip...\n" ..
"* Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.")
|
$ lua script.lua --help
Usage: script.lua [-h] [-f <foo>] [-b <bar>]
Options:
-h, --help Show this help message and exit.
-f <foo>, Lorem ipsum dolor sit amet, consectetur adipiscing
--foo <foo> elit, sed do eiusmod tempor incididunt ut labore et
dolore magna aliqua. Ut enim ad minim veniam, quis
nostrud exercitation ullamco laboris nisi ut aliquip ex
ea commodo consequat.
The next paragraph is indented:
Duis aute irure dolor in reprehenderit in voluptate
velit esse cillum dolore eu fugiat nulla pariatur.
Excepteur sint occaecat cupidatat non proident, sunt
in culpa qui officia deserunt mollit anim id est
laborum.
-b <bar>, Here is a list:
--bar <bar> * Lorem ipsum dolor sit amet, consectetur adipiscing
elit, sed do eiusmod tempor...
* Ut enim ad minim veniam, quis nostrud exercitation
ullamco laboris nisi ut aliquip...
* Duis aute irure dolor in reprehenderit in voluptate
velit esse cillum dolore eu fugiat nulla pariatur.
help_max_width
property is inherited by commands.
Configuring help and usage message layout¶
Several other parser and command properties can be used to tweak help and usage message format.
Like help_max_width
, all of them are inherited by commands when set on the parser or a parent command.
usage_max_width
property sets maximum width of the usage string. Default is 70
.
usage_margin
property sets margin width used when line wrapping long usage strings. Default is 7
.
1 2 3 4 5 6 7 8 9 | parser:usage_max_width(50)
:usage_margin(#"Usage: script.lua ")
parser:option "--foo"
parser:option "--bar"
parser:option "--baz"
parser:option "--qux"
print(parser:get_usage())
|
$ lua script.lua
Usage: script.lua [-h] [--foo <foo>] [--bar <bar>]
[--baz <baz>] [--qux <qux>]
Help message for a group of arguments, options, or commands is organized into two columns, with usage
template on the left side and descriptions on the right side.
help_usage_margin
property sets horizontal offset for the first column (3
by default).
help_description_margin
property sets horizontal offset for the second column (25
by default).
help_vertical_space
property sets number of extra empty lines to put between descriptions for different elements
within a group (0
by default).
1 2 3 4 5 6 7 8 | parser:help_usage_margin(2)
:help_description_margin(17)
:help_vertical_space(1)
parser:option("--foo", "Set foo.")
parser:option("--bar", "Set bar.")
parser:option("--baz", "Set baz.")
parser:option("--qux", "Set qux.")
|
$ lua script.lua --help
Usage: script.lua [-h] [--foo <foo>] [--bar <bar>] [--baz <baz>]
[--qux <qux>]
Options:
-h, --help Show this help message and exit.
--foo <foo> Set foo.
--bar <bar> Set bar.
--baz <baz> Set baz.
--qux <qux> Set qux.