mirror of
https://github.com/TangentFoxy/argparse.git
synced 2025-07-28 11:02:20 +00:00
Update documentation [ci skip]
This commit is contained in:
Peter Melnichenko
266
docsrc/messages.rst
Normal file
266
docsrc/messages.rst
Normal file
@@ -0,0 +1,266 @@
|
||||
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 [--normal-option <normal_option>] [-h]
|
||||
|
||||
Options:
|
||||
--normal-option <normal_option>
|
||||
-h, --help Show this help message and exit.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ lua script.lua --deprecated-option value
|
||||
|
||||
.. code-block:: lua
|
||||
|
||||
{
|
||||
deprecated_option = "value"
|
||||
}
|
||||
|
||||
|
||||
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 [-f <server>] [-h]
|
||||
|
||||
Options:
|
||||
-f <server>, --from <server>
|
||||
-h, --help Show this help message and exit.
|
||||
|
||||
``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 [--pair <key> <value>] [-h]
|
||||
|
||||
Options:
|
||||
--pair <key> <value>
|
||||
-h, --help Show this help message and exit.
|
||||
|
||||
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 [-v] [--use-colors] [--encoding <encoding>]
|
||||
[--compression-level <compression_level>]
|
||||
[--skip-broken-chunks] [--version] [-h]
|
||||
|
||||
Configuring output format:
|
||||
-v, --verbose
|
||||
--use-colors
|
||||
--encoding <encoding>
|
||||
|
||||
Configuring processing:
|
||||
--compression-level <compression_level>
|
||||
--skip-broken-chunks
|
||||
|
||||
Other options:
|
||||
--version
|
||||
-h, --help Show this help message and exit.
|
||||
|
||||
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 [-f <foo>] [-b <bar>] [-h]
|
||||
|
||||
Options:
|
||||
-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.
|
||||
-h, --help Show this help message and exit.
|
||||
|
||||
``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 [--foo <foo>] [--bar <bar>]
|
||||
[--baz <baz>] [--qux <qux>] [-h]
|
||||
|
||||
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 [--foo <foo>] [--bar <bar>] [--baz <baz>]
|
||||
[--qux <qux>] [-h]
|
||||
|
||||
Options:
|
||||
|
||||
--foo <foo> Set foo.
|
||||
|
||||
--bar <bar> Set bar.
|
||||
|
||||
--baz <baz> Set baz.
|
||||
|
||||
--qux <qux> Set qux.
|
||||
|
||||
-h, --help Show this help message and exit.
|
||||
Reference in New Issue
Block a user