Show hidden args/opts/flags with --help-hidden (#412)

- Make ArgumentSet(_:visibility:) filter correctly
  The ArgumentSet initializer was previously only filtering out option
  groups with visibility lower than requested. With this change, the
  resulting ArgumentSet only includes values that are valid for display.
  In addition, this moves the visibility parameter out of
  UsageGenerator.synopsis(); that type needs to have the correct
  visibility level at initialization.

- Mark non-parsed properties as private
  This applies to properties that are defined without a property
  wrapper. This kind of property should never be included in the help,
  since they aren't included in the command-line tool's UI.

Author: natecook1000

Sources/ArgumentParser/Parsable Types/ParsableArguments.swift

@@ -270,7 +270,6 @@ extension ArgumentSetProvider {
 
 extension ArgumentSet {
   init(_ type: ParsableArguments.Type, visibility: ArgumentVisibility) {
-    
     #if DEBUG
     do {
       try type._validate()
@@ -296,17 +295,12 @@ extension ArgumentSet {
           return parsed.argumentSet(for: key)
         } else {
           // Save a non-wrapped property as is
-          var definition = ArgumentDefinition(
-            key: InputKey(rawValue: codingKey),
-            kind: .default,
-            parser: { _ in nil },
-            default: nilOrValue(child.value),
-            completion: .default)
-          definition.help.updateArgumentHelp(help: .hidden)
-          return ArgumentSet(definition)
+          return ArgumentSet(
+            ArgumentDefinition(unparsedKey: codingKey, default: nilOrValue(child.value)))
         }
       }
-    self.init(sets: a)
+    self.init(
+      a.joined().filter { $0.help.visibility.isAtLeastAsVisible(as: visibility) })
   }
 }
 

Sources/ArgumentParser/Parsing/ArgumentSet.swift

@@ -190,6 +190,23 @@ extension ArgumentDefinition {
   }
 }
 
+extension ArgumentDefinition {
+  /// Creates an argument definition for a property that isn't parsed from the
+  /// command line.
+  ///
+  /// This initializer is used for any property defined on a `ParsableArguments`
+  /// type that isn't decorated with one of ArgumentParser's property wrappers.
+  init(unparsedKey: String, default defaultValue: Any?) {
+    self.init(
+      key: InputKey(rawValue: unparsedKey),
+      kind: .default,
+      parser: { _ in nil },
+      default: defaultValue,
+      completion: .default)
+    help.updateArgumentHelp(help: .private)
+  }
+}
+
 // MARK: - Parsing from SplitArguments
 extension ArgumentSet {
   /// Parse the given input for this set of defined arguments.

Sources/ArgumentParser/Usage/HelpGenerator.swift

@@ -106,7 +106,8 @@ internal struct HelpGenerator {
     if let usage = currentCommand.configuration.usage {
       self.usage = usage
     } else {
-      var usage = UsageGenerator(toolName: toolName, definition: [currentArgSet]).synopsis
+      var usage = UsageGenerator(toolName: toolName, definition: [currentArgSet])
+        .synopsis
       if !currentCommand.configuration.subcommands.isEmpty {
         if usage.last != " " { usage += " " }
         usage += "<subcommand>"
@@ -140,7 +141,7 @@ internal struct HelpGenerator {
     /// more elements at a time.
     var args = commandStack.argumentsForHelp(visibility: visibility)[...]
     while let arg = args.popFirst() {
-      guard arg.help.visibility.base == .default else { continue }
+      assert(arg.help.visibility.isAtLeastAsVisible(as: visibility))
 
       let synopsis: String
       let description: String
@@ -154,7 +155,6 @@ internal struct HelpGenerator {
 
         synopsis = groupedArgs
           .lazy
-          .filter { $0.help.visibility.base == .default }
           .map { $0.synopsisForHelp }
           .joined(separator: "/")
 
@@ -172,9 +172,7 @@ internal struct HelpGenerator {
           .filter { !$0.isEmpty }
           .joined(separator: " ")
       } else {
-        synopsis = arg.help.visibility.base == .default
-          ? arg.synopsisForHelp
-          : ""
+        synopsis = arg.synopsisForHelp
 
         let defaultValue = arg.help.defaultValue.flatMap { $0.isEmpty ? nil : "(default: \($0))" }
         description = [arg.help.abstract, defaultValue]

Sources/ArgumentParser/Usage/UsageGenerator.swift

@@ -22,10 +22,10 @@ extension UsageGenerator {
     self.init(toolName: toolName, definition: definition)
   }
 
-  init(toolName: String, parsable: ParsableArguments) {
+  init(toolName: String, parsable: ParsableArguments, visibility: ArgumentVisibility) {
     self.init(
       toolName: toolName,
-      definition: ArgumentSet(type(of: parsable), visibility: .default))
+      definition: ArgumentSet(type(of: parsable), visibility: visibility))
   }
 
   init(toolName: String, definition: [ArgumentSet]) {
@@ -38,9 +38,7 @@ extension UsageGenerator {
   ///
   /// In `roff`.
   var synopsis: String {
-    // Filter out options that should not be displayed.
-    var options = definition
-      .filter { $0.help.visibility.base == .default }
+    var options = Array(definition)
     switch options.count {
     case 0:
       return toolName

Tests/ArgumentParserUnitTests/HelpGenerationTests.swift

@@ -72,11 +72,6 @@ extension HelpGenerationTests {
 
             """)
 
-#if !os(Linux)
-    XCTExpectFailure("""
-            The following test fails to properly generate the help-hidden
-            message properly because help-hidden is not fully supported yet.
-            """)
     AssertHelp(.hidden, for: B.self, equals: """
             USAGE: b --name <name> [--title <title>] [<hidden-name>] [--hidden-title <hidden-title>] [--hidden-flag] [--hidden-inverted-flag] [--no-hidden-inverted-flag]
 
@@ -93,7 +88,6 @@ extension HelpGenerationTests {
               -h, --help              Show help information.
 
             """)
-#endif
   }
 
   struct C: ParsableArguments {

Tests/ArgumentParserUnitTests/UsageGenerationTests.swift

@@ -15,6 +15,17 @@ import XCTest
 final class UsageGenerationTests: XCTestCase {
 }
 
+func _testSynopsis<T: ParsableArguments>(
+  _ type: T.Type,
+  visibility: ArgumentVisibility = .default,
+  expected: String,
+  file: StaticString = #file,
+  line: UInt = #line
+) {
+  let help = UsageGenerator(toolName: "example", parsable: T(), visibility: visibility)
+  XCTAssertEqual(help.synopsis, expected, file: file, line: line)
+}
+
 // MARK: -
 
 extension UsageGenerationTests {
@@ -32,8 +43,7 @@ extension UsageGenerationTests {
   }
 
   func testSynopsis() {
-    let help = UsageGenerator(toolName: "bar", parsable: A())
-    XCTAssertEqual(help.synopsis, "bar --first-name <first-name> --title <title>")
+    _testSynopsis(A.self, expected: "example --first-name <first-name> --title <title>")
   }
 
   struct B: ParsableArguments {
@@ -42,8 +52,7 @@ extension UsageGenerationTests {
   }
 
   func testSynopsisWithOptional() {
-    let help = UsageGenerator(toolName: "bar", parsable: B())
-    XCTAssertEqual(help.synopsis, "bar [--first-name <first-name>] [--title <title>]")
+    _testSynopsis(B.self, expected: "example [--first-name <first-name>] [--title <title>]")
   }
 
   struct C: ParsableArguments {
@@ -52,8 +61,7 @@ extension UsageGenerationTests {
   }
 
   func testFlagSynopsis() {
-    let help = UsageGenerator(toolName: "bar", parsable: C())
-    XCTAssertEqual(help.synopsis, "bar [--log] [--verbose ...]")
+    _testSynopsis(C.self, expected: "example [--log] [--verbose ...]")
   }
 
   struct D: ParsableArguments {
@@ -62,8 +70,7 @@ extension UsageGenerationTests {
   }
 
   func testPositionalSynopsis() {
-    let help = UsageGenerator(toolName: "bar", parsable: D())
-    XCTAssertEqual(help.synopsis, "bar <first-name> [<title>]")
+    _testSynopsis(D.self, expected: "example <first-name> [<title>]")
   }
 
   struct E: ParsableArguments {
@@ -78,8 +85,7 @@ extension UsageGenerationTests {
   }
 
   func testSynopsisWithDefaults() {
-    let help = UsageGenerator(toolName: "bar", parsable: E())
-    XCTAssertEqual(help.synopsis, "bar [--name <name>] [--count <count>] [<arg>]")
+    _testSynopsis(E.self, expected: "example [--name <name>] [--count <count>] [<arg>]")
   }
 
   struct F: ParsableArguments {
@@ -88,8 +94,7 @@ extension UsageGenerationTests {
   }
 
   func testSynopsisWithRepeats() {
-    let help = UsageGenerator(toolName: "bar", parsable: F())
-    XCTAssertEqual(help.synopsis, "bar [--name <name> ...] [<name-counts> ...]")
+    _testSynopsis(F.self, expected: "example [--name <name> ...] [<name-counts> ...]")
   }
 
   struct G: ParsableArguments {
@@ -101,8 +106,7 @@ extension UsageGenerationTests {
   }
 
   func testSynopsisWithCustomization() {
-    let help = UsageGenerator(toolName: "bar", parsable: G())
-    XCTAssertEqual(help.synopsis, "bar [--file-path <path>] <user-home-path>")
+    _testSynopsis(G.self, expected: "example [--file-path <path>] <user-home-path>")
   }
 
   struct H: ParsableArguments {
@@ -111,8 +115,8 @@ extension UsageGenerationTests {
   }
 
   func testSynopsisWithHidden() {
-    let help = UsageGenerator(toolName: "bar", parsable: H())
-    XCTAssertEqual(help.synopsis, "bar")
+    _testSynopsis(H.self, expected: "example")
+    _testSynopsis(H.self, visibility: .hidden, expected: "example [--first-name <first-name>] [<title>]")
   }
 
   struct I: ParsableArguments {
@@ -135,8 +139,7 @@ extension UsageGenerationTests {
   }
 
   func testSynopsisWithDefaultValueAndTransform() {
-    let help = UsageGenerator(toolName: "bar", parsable: I())
-    XCTAssertEqual(help.synopsis, "bar [--color <color>]")
+    _testSynopsis(I.self, expected: "example [--color <color>]")
   }
 
   struct J: ParsableArguments {
@@ -146,8 +149,7 @@ extension UsageGenerationTests {
   }
 
   func testSynopsisWithTransform() {
-    let help = UsageGenerator(toolName: "bar", parsable: J())
-    XCTAssertEqual(help.synopsis, "bar --req <req> [--opt <opt>]")
+    _testSynopsis(J.self, expected: "example --req <req> [--opt <opt>]")
   }
 
   struct K: ParsableArguments {
@@ -158,8 +160,7 @@ extension UsageGenerationTests {
   }
 
   func testSynopsisWithMultipleCustomNames() {
-    let help = UsageGenerator(toolName: "bar", parsable: K())
-    XCTAssertEqual(help.synopsis, "bar [--remote <remote>]")
+    _testSynopsis(K.self, expected: "example [--remote <remote>]")
   }
 
   struct L: ParsableArguments {
@@ -170,8 +171,7 @@ extension UsageGenerationTests {
   }
 
   func testSynopsisWithSingleDashLongNameFirst() {
-    let help = UsageGenerator(toolName: "bar", parsable: L())
-    XCTAssertEqual(help.synopsis, "bar [-remote <remote>]")
+    _testSynopsis(L.self, expected: "example [-remote <remote>]")
   }
 
   struct M: ParsableArguments {
@@ -193,8 +193,18 @@ extension UsageGenerationTests {
   }
 
   func testSynopsisWithTooManyOptions() {
-    let help = UsageGenerator(toolName: "foo", parsable: M())
-    XCTAssertEqual(help.synopsis,
-                   "foo [<options>] --option <option> <input> [<output>]")
+    _testSynopsis(M.self, expected: "example [<options>] --option <option> <input> [<output>]")
+  }
+  
+  struct N: ParsableArguments {
+    @Flag var a: Bool = false
+    @Flag var b: Bool = false
+    var title = "defaulted value"
+    var decode = false
+  }
+  
+  func testNonwrappedValues() {
+    _testSynopsis(N.self, expected: "example [--a] [--b]")
+    _testSynopsis(N.self, visibility: .hidden, expected: "example [--a] [--b]")
   }
 }