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.
