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.

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"
}

Setting argument placeholder

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

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.

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.

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.

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.

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).

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.