Add help_vertical_space Parser property

Sets number of extra newlines to insert between help strings
for different elements within a help group. Inherited by commands.

CHANGELOG.md

@@ -13,6 +13,9 @@
 * Added `:group(name, ...)` method to Parser and Command objects, allowing
   custom grouping of arguments, options, and commands in autogenerated
   help string.
+* Added `help_vertical_space` property for configuring number of extra
+  newlines between help strings for different arguments and options in
+  autogenerated help string.
 
 ### Improvements
 

spec/help_spec.lua

@@ -385,4 +385,82 @@ Some commands:
 Other commands:
    another-command]], parser:get_help())
    end)
+
+   it("allows spacing out element help blocks more with help_vertical_space", function()
+      local parser = Parser "foo"
+         :help_vertical_space(1)
+
+      parser:argument "arg1"
+         :description "Argument number one."
+      parser:argument "arg2"
+         :description "Argument number two."
+
+      parser:flag "-p"
+         :description "This is a thing."
+      parser:option "-f --foo"
+         :description [[
+And this things uses many lines.
+Because it has lots of complex behaviour.
+That needs documenting.]]
+
+      assert.equal([[
+Usage: foo [-p] [-f <foo>] [-h] <arg1> <arg2>
+
+Arguments:
+
+   arg1                  Argument number one.
+
+   arg2                  Argument number two.
+
+Options:
+
+   -p                    This is a thing.
+
+      -f <foo>,          And this things uses many lines.
+   --foo <foo>           Because it has lots of complex behaviour.
+                         That needs documenting.
+
+   -h, --help            Show this help message and exit.]], parser:get_help())
+   end)
+
+   it("inherits help_vertical_space in commands", function()
+      local parser = Parser "foo"
+         :help_vertical_space(1)
+
+      local cmd1 = parser:command "cmd1"
+         :help_vertical_space(2)
+
+      cmd1:flag("-a", "Do a thing.")
+      cmd1:flag("-b", "Do b thing.")
+
+      local cmd2 = parser:command "cmd2"
+
+      cmd2:flag("-c", "Do c thing.")
+      cmd2:flag("-d", "Do d thing.")
+
+      assert.equal([[
+Usage: foo cmd1 [-a] [-b] [-h]
+
+Options:
+
+
+   -a                    Do a thing.
+
+
+   -b                    Do b thing.
+
+
+   -h, --help            Show this help message and exit.]], cmd1:get_help())
+
+      assert.equal([[
+Usage: foo cmd2 [-c] [-d] [-h]
+
+Options:
+
+   -c                    Do c thing.
+
+   -d                    Do d thing.
+
+   -h, --help            Show this help message and exit.]], cmd2:get_help())
+   end)
 end)

src/argparse.lua

@@ -246,6 +246,7 @@ local Parser = class({
    typechecked("handle_options", "boolean"),
    typechecked("action", "function"),
    typechecked("command_target", "string"),
+   typechecked("help_vertical_space", "number"),
    add_help
 })
 
@@ -263,6 +264,7 @@ local Command = class({
    typechecked("handle_options", "boolean"),
    typechecked("action", "function"),
    typechecked("command_target", "string"),
+   typechecked("help_vertical_space", "number"),
    typechecked("hidden", "boolean"),
    add_help
 }, Parser)
@@ -312,6 +314,24 @@ local Option = class({
    option_init
 }, Argument)
 
+function Parser:_inherit_property(name, default)
+   local element = self
+
+   while true do
+      local value = element["_" .. name]
+
+      if value ~= nil then
+         return value
+      end
+
+      if not element._parent then
+         return default
+      end
+
+      element = element._parent
+   end
+end
+
 function Argument:_get_argument_list()
    local buf = {}
    local i = 1
@@ -826,7 +846,7 @@ local function get_group_types(group)
    return types
 end
 
-local function add_group_help(blocks, added_elements, label, elements)
+function Parser:_add_group_help(blocks, added_elements, label, elements)
    local buf = {label}
 
    for _, element in ipairs(elements) do
@@ -837,7 +857,7 @@ local function add_group_help(blocks, added_elements, label, elements)
    end
 
    if #buf > 1 then
-      table.insert(blocks, table.concat(buf, "\n"))
+      table.insert(blocks, table.concat(buf, ("\n"):rep(self:_inherit_property("help_vertical_space", 0) + 1)))
    end
 end
 
@@ -885,7 +905,7 @@ function Parser:get_help()
       local type_groups = groups_by_type[default_group.type]
 
       for _, group in ipairs(type_groups) do
-         add_group_help(blocks, added_elements, group.name .. ":", group)
+         self:_add_group_help(blocks, added_elements, group.name .. ":", group)
       end
 
       local default_label = default_group.name .. ":"
@@ -894,7 +914,7 @@ function Parser:get_help()
          default_label = "Other " .. default_label:gsub("^.", string.lower)
       end
 
-      add_group_help(blocks, added_elements, default_label, default_group.elements)
+      self:_add_group_help(blocks, added_elements, default_label, default_group.elements)
    end
 
    if self._epilog then