mirror of
https://github.com/TangentFoxy/argparse.git
synced 2025-07-27 18:42:20 +00:00
20c14453fd
Also auto-add an alias with dashes in place of underscores if an alias has an underscore.
302 lines
9.1 KiB
ReStructuredText
302 lines
9.1 KiB
ReStructuredText
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.
|
|
|
|
.. code-block:: lua
|
|
:linenos:
|
|
|
|
parser:option "--normal-option"
|
|
parser:option "--deprecated-option"
|
|
:hidden(true)
|
|
|
|
.. code-block:: none
|
|
|
|
$ lua script.lua --help
|
|
|
|
.. code-block:: none
|
|
|
|
Usage: script.lua [-h] [--normal-option <normal_option>]
|
|
|
|
Options:
|
|
-h, --help Show this help message and exit.
|
|
--normal-option <normal_option>
|
|
|
|
.. code-block:: none
|
|
|
|
$ lua script.lua --deprecated-option value
|
|
|
|
.. code-block:: lua
|
|
|
|
{
|
|
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.
|
|
|
|
.. code-block:: lua
|
|
:linenos:
|
|
|
|
parser:option "--server"
|
|
:hidden_name "--from"
|
|
|
|
.. code-block:: none
|
|
|
|
$ lua script.lua --help
|
|
|
|
.. code-block:: none
|
|
|
|
Usage: script.lua [-h] [--server <server>]
|
|
|
|
Options:
|
|
-h, --help Show this help message and exit.
|
|
--server <server>
|
|
|
|
.. code-block:: none
|
|
|
|
$ lua script.lua --server foo
|
|
$ lua script.lua --from foo
|
|
|
|
.. code-block:: lua
|
|
|
|
{
|
|
server = "foo"
|
|
}
|
|
|
|
Setting argument placeholder
|
|
----------------------------
|
|
|
|
For options and arguments, ``argname`` property controls the placeholder for the argument in the usage message.
|
|
|
|
.. code-block:: lua
|
|
:linenos:
|
|
|
|
parser:option "-f" "--from"
|
|
:argname "<server>"
|
|
|
|
.. code-block:: none
|
|
|
|
$ lua script.lua --help
|
|
|
|
.. code-block:: none
|
|
|
|
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.
|
|
|
|
.. code-block:: lua
|
|
:linenos:
|
|
|
|
parser:option "--pair"
|
|
:args(2)
|
|
:argname {"<key>", "<value>"}
|
|
|
|
.. code-block:: none
|
|
|
|
$ lua script.lua --help
|
|
|
|
.. code-block:: none
|
|
|
|
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.
|
|
|
|
.. code-block:: lua
|
|
:linenos:
|
|
|
|
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)
|
|
|
|
.. code-block:: none
|
|
|
|
$ lua script.lua --help
|
|
|
|
.. code-block:: none
|
|
|
|
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.
|
|
|
|
.. code-block:: lua
|
|
:linenos:
|
|
|
|
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.")
|
|
|
|
.. code-block:: none
|
|
|
|
$ lua script.lua --help
|
|
|
|
.. code-block:: none
|
|
|
|
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``.
|
|
|
|
.. code-block:: lua
|
|
:linenos:
|
|
|
|
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())
|
|
|
|
.. code-block:: none
|
|
|
|
$ lua script.lua
|
|
|
|
.. code-block:: none
|
|
|
|
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).
|
|
|
|
.. code-block:: lua
|
|
:linenos:
|
|
|
|
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.")
|
|
|
|
.. code-block:: none
|
|
|
|
$ lua script.lua --help
|
|
|
|
.. code-block:: none
|
|
|
|
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.
|