Add hidden property, unlisting elements from usage and help

spec/help_spec.lua

@@ -182,4 +182,46 @@ Options:
       assert.equal([[
 I don't like your format of help messages]], parser:get_help())
    end)
+
+   it("does not mention hidden arguments, options, and commands", function()
+      local parser = Parser "foo"
+      parser:argument "normal"
+      parser:argument "deprecated"
+         :args "?"
+         :hidden(true)
+      parser:flag "--feature"
+      parser:flag "--misfeature"
+         :hidden(true)
+      parser:command "good"
+      parser:command "okay"
+      parser:command "never-use-this-one"
+         :hidden(true)
+
+      assert.equal([[
+Usage: foo [--feature] [-h] <normal> <command> ...
+
+Arguments:
+   normal
+
+Options:
+   --feature
+   -h, --help            Show this help message and exit.
+
+Commands:
+   good
+   okay]], parser:get_help())
+   end)
+
+   it("omits categories if all elements are hidden", function()
+      local parser = Parser "foo"
+         :add_help(false)
+      parser:argument "deprecated"
+         :args "?"
+         :hidden(true)
+      parser:flag "--misfeature"
+         :hidden(true)
+
+      assert.equal([[
+Usage: foo]], parser:get_help())
+   end)
 end)

spec/usage_spec.lua

@@ -116,6 +116,42 @@ Usage: foo <first> <second-and-third> <second-and-third>
       )
    end)
 
+   it("omits usage for hidden arguments and options", function()
+      local parser = Parser "foo"
+         :add_help(false)
+      parser:flag "-d" "--deprecated"
+         :hidden(true)
+      parser:flag "-n" "--not-deprecated"
+      parser:argument "normal"
+      parser:argument "deprecated"
+         :args "?"
+         :hidden(true)
+
+      assert.equal(
+         [=[Usage: foo [-n] <normal>]=],
+         parser:get_usage()
+      )
+   end)
+
+   it("omits usage for mutexes if all elements are hidden", function()
+      local parser = Parser "foo"
+         :add_help(false)
+      parser:mutex(
+         parser:flag "--misfeature"
+            :hidden(true),
+         parser:flag "--no-misfeature"
+            :action "store_false"
+            :target "misfeature"
+            :hidden(true)
+      )
+      parser:flag "--feature"
+
+      assert.equal(
+         [=[Usage: foo [--feature]]=],
+         parser:get_usage()
+      )
+   end)
+
    it("usage messages for commands are correct after several invocations", function()
       local parser = Parser "foo"
          :add_help(false)

src/argparse.lua

@@ -262,6 +262,7 @@ local Command = class({
    typechecked("handle_options", "boolean"),
    typechecked("action", "function"),
    typechecked("command_target", "string"),
+   typechecked("hidden", "boolean"),
    add_help
 }, Parser)
 
@@ -283,6 +284,7 @@ local Argument = class({
    typechecked("defmode", "string"),
    typechecked("show_default", "boolean"),
    typechecked("argname", "string", "table"),
+   typechecked("hidden", "boolean"),
    option_action,
    option_init
 })
@@ -304,6 +306,7 @@ local Option = class({
    typechecked("show_default", "boolean"),
    typechecked("overwrite", "boolean"),
    typechecked("argname", "string", "table"),
+   typechecked("hidden", "boolean"),
    option_action,
    option_init
 }, Argument)
@@ -625,7 +628,7 @@ function Parser:get_usage()
       local buf = {}
 
       for _, element in ipairs(mutex) do
-         if not added_elements[element] then
+         if not element._hidden and not added_elements[element] then
             if getmetatable(element) == Option or element == main_argument then
                table.insert(buf, element:_get_usage())
                added_elements[element] = true
@@ -641,7 +644,7 @@ function Parser:get_usage()
    end
 
    local function add_element(element)
-      if not added_elements[element] then
+      if not element._hidden and not added_elements[element] then
          add(element:_get_usage())
          added_elements[element] = true
       end
@@ -750,13 +753,15 @@ function Parser:get_help()
    local labels = {"Arguments:", "Options:", "Commands:"}
 
    for i, elements in ipairs{self._arguments, self._options, self._commands} do
-      if #elements > 0 then
       local buf = {labels[i]}
 
       for _, element in ipairs(elements) do
+         if not element._hidden then
             table.insert(buf, make_two_columns(element:_get_label(), element:_get_description()))
          end
+      end
 
+      if #buf > 1 then
          table.insert(blocks, table.concat(buf, "\n"))
       end
    end