Replace createHelp and includeHidden (#405)

- Replaces `ArgumentSet.init(_:creatingHelp:includeHidden:)` with
  `ArgumentSet.init(_:visibility:)`. `visibility` intentionally does not
  have a default value to ensure that callers only have the correct
  arguments. As part of this change `includeHidden` has been replaced
  throughout the codebase with `visibility`. This change also fixes a
  bug where arguments with hidden `visibility` were being displayed in the
  generated command usage string.

Author: rauhul

Sources/ArgumentParser/Completions/BashCompletionsGenerator.swift

@@ -122,14 +122,16 @@ struct BashCompletionsGenerator {
 
   /// Returns the option and flag names that can be top-level completions.
   fileprivate static func generateArgumentWords(_ commands: [ParsableCommand.Type]) -> [String] {
-    commands.argumentsForHelp().flatMap { $0.bashCompletionWords() }
+    commands
+      .argumentsForHelp(visibility: .default)
+      .flatMap { $0.bashCompletionWords() }
   }
 
   /// Returns additional top-level completions from positional arguments.
   ///
   /// These consist of completions that are defined as `.list` or `.custom`.
   fileprivate static func generateArgumentCompletions(_ commands: [ParsableCommand.Type]) -> [String] {
-    ArgumentSet(commands.last!)
+    ArgumentSet(commands.last!, visibility: .default)
       .compactMap { arg -> String? in
         guard arg.isPositional else { return nil }
 
@@ -156,7 +158,7 @@ struct BashCompletionsGenerator {
 
   /// Returns the case-matching statements for supplying completions after an option or flag.
   fileprivate static func generateOptionHandlers(_ commands: [ParsableCommand.Type]) -> String {
-    ArgumentSet(commands.last!)
+    ArgumentSet(commands.last!, visibility: .default)
       .compactMap { arg -> String? in
         let words = arg.bashCompletionWords()
         if words.isEmpty { return nil }

Sources/ArgumentParser/Completions/FishCompletionsGenerator.swift

@@ -56,7 +56,7 @@ struct FishCompletionsGenerator {
     }
 
     let argumentCompletions = commands
-      .argumentsForHelp()
+      .argumentsForHelp(visibility: .default)
       .flatMap { $0.argumentSegments(commandChain) }
       .map { complete(ancestors: $0, suggestion: $1) }
 

Sources/ArgumentParser/Completions/ZshCompletionsGenerator.swift

@@ -103,7 +103,9 @@ struct ZshCompletionsGenerator {
   }
 
   static func generateCompletionArguments(_ commands: [ParsableCommand.Type]) -> [String] {
-    commands.argumentsForHelp().compactMap { $0.zshCompletionString(commands) }
+    commands
+      .argumentsForHelp(visibility: .default)
+      .compactMap { $0.zshCompletionString(commands) }
   }
 }
 

Sources/ArgumentParser/Parsable Properties/ArgumentVisibility.swift

@@ -20,3 +20,27 @@ public enum ArgumentVisibility {
     /// Never show help for this argument.
     case `private`
 }
+
+extension ArgumentVisibility {
+  /// A raw Integer value that represents each visibility level.
+  ///
+  /// `_comparableLevel` can be used to test if a Visibility case is more or
+  /// less visible than another, without committing this behavior to API.
+  /// A lower `_comparableLevel` indicates that the case is less visible (more
+  /// secret).
+  private var _comparableLevel: Int {
+    switch self {
+    case .default:
+      return 2
+    case .hidden:
+      return 1
+    case .private:
+      return 0
+    }
+  }
+
+  /// - Returns: true if `self` is at least as visible as the supplied argument.
+  func isAtLeastAsVisible(as other: Self) -> Bool {
+    self._comparableLevel >= other._comparableLevel
+  }
+}

Sources/ArgumentParser/Parsable Properties/OptionGroup.swift

@@ -64,7 +64,7 @@ public struct OptionGroup<Value: ParsableArguments>: Decodable, ParsedWrapper {
   /// Creates a property that represents another parsable type.
   public init() {
     self.init(_parsedValue: .init { _ in
-      ArgumentSet(Value.self)
+      ArgumentSet(Value.self, visibility: .private)
     })
   }
 

Sources/ArgumentParser/Parsable Types/ParsableArguments.swift

@@ -163,7 +163,7 @@ extension ParsableArguments {
     includeHidden: Bool = false,
     columns: Int? = nil
   ) -> String {
-    HelpGenerator(self, includeHidden: includeHidden)
+    HelpGenerator(self, visibility: includeHidden ? .hidden : .default)
       .rendered(screenWidth: columns)
   }
 
@@ -269,7 +269,7 @@ extension ArgumentSetProvider {
 }
 
 extension ArgumentSet {
-  init(_ type: ParsableArguments.Type, creatingHelp: Bool = false, includeHidden: Bool = false) {
+  init(_ type: ParsableArguments.Type, visibility: ArgumentVisibility) {
 
     #if DEBUG
     do {
@@ -285,13 +285,8 @@ extension ArgumentSet {
         guard var codingKey = child.label else { return nil }
 
         if let parsed = child.value as? ArgumentSetProvider {
-          if creatingHelp {
-            if includeHidden {
-              guard parsed._visibility != .private else { return nil }
-            } else {
-              guard parsed._visibility == .default else { return nil }
-            }
-          }
+          guard parsed._visibility.isAtLeastAsVisible(as: visibility)
+          else { return nil }
 
           // Property wrappers have underscore-prefixed names
           codingKey = String(codingKey.first == "_"

Sources/ArgumentParser/Parsable Types/ParsableCommand.swift

@@ -108,7 +108,7 @@ extension ParsableCommand {
   ) -> String {
     HelpGenerator(
       commandStack: CommandParser(self).commandStack(for: subcommand),
-      includeHidden: includeHidden)
+      visibility: includeHidden ? .hidden : .default)
         .rendered(screenWidth: columns)
   }
 
@@ -141,7 +141,7 @@ extension ParsableCommand {
   /// `true` if this command contains any array arguments that are declared
   /// with `.unconditionalRemaining`.
   internal static var includesUnconditionalArguments: Bool {
-    ArgumentSet(self).contains(where: {
+    ArgumentSet(self, visibility: .private).contains(where: {
       $0.isRepeatingPositional && $0.parsingStrategy == .allRemainingInput
     })
   }

Sources/ArgumentParser/Parsing/CommandParser.swift

@@ -130,7 +130,7 @@ extension CommandParser {
   /// possible.
   fileprivate mutating func parseCurrent(_ split: inout SplitArguments) throws -> ParsableCommand {
     // Build the argument set (i.e. information on how to parse):
-    let commandArguments = ArgumentSet(currentNode.element)
+    let commandArguments = ArgumentSet(currentNode.element, visibility: .private)
 
     // Parse the arguments, ignoring anything unexpected
     let values = try commandArguments.lenientParse(
@@ -315,7 +315,7 @@ extension CommandParser {
     let completionValues = Array(args)
 
     // Generate the argument set and parse the argument to find in the set
-    let argset = ArgumentSet(current.element)
+    let argset = ArgumentSet(current.element, visibility: .private)
     let parsedArgument = try! parseIndividualArg(argToMatch, at: 0).first!
 
     // Look up the specified argument and retrieve its custom completion function

Sources/ArgumentParser/Usage/DumpHelpGenerator.swift

@@ -38,7 +38,7 @@ fileprivate extension BidirectionalCollection where Element == ParsableCommand.T
   /// Returns the ArgumentSet for the last command in this stack, including
   /// help and version flags, when appropriate.
   func allArguments() -> ArgumentSet {
-    guard var arguments = self.last.map({ ArgumentSet($0, creatingHelp: false) })
+    guard var arguments = self.last.map({ ArgumentSet($0, visibility: .private) })
     else { return ArgumentSet() }
     self.versionArgumentDefinition().map { arguments.append($0) }
     self.helpArgumentDefinition().map { arguments.append($0) }

Sources/ArgumentParser/Usage/HelpCommand.swift

@@ -19,7 +19,7 @@ struct HelpCommand: ParsableCommand {
   @Argument var subcommands: [String] = []
 
   /// Capture and ignore any extra help flags given by the user.
-  @Flag(name: [.short, .long, .customLong("help", withSingleDash: true)], help: .hidden)
+  @Flag(name: [.short, .long, .customLong("help", withSingleDash: true)], help: .private)
   var help = false
 
   private(set) var commandStack: [ParsableCommand.Type] = []
@@ -39,7 +39,10 @@ struct HelpCommand: ParsableCommand {
 
   /// Used for testing.
   func generateHelp(screenWidth: Int) -> String {
-    HelpGenerator(commandStack: commandStack).rendered(screenWidth: screenWidth)
+    HelpGenerator(
+      commandStack: commandStack,
+      visibility: visibility)
+      .rendered(screenWidth: screenWidth)
   }
 
   enum CodingKeys: CodingKey {

Sources/ArgumentParser/Usage/HelpGenerator.swift

@@ -89,12 +89,12 @@ internal struct HelpGenerator {
   var sections: [Section]
   var discussionSections: [DiscussionSection]
 
-  init(commandStack: [ParsableCommand.Type], includeHidden: Bool = false) {
+  init(commandStack: [ParsableCommand.Type], visibility: ArgumentVisibility) {
     guard let currentCommand = commandStack.last else {
       fatalError()
     }
 
-    let currentArgSet = ArgumentSet(currentCommand)
+    let currentArgSet = ArgumentSet(currentCommand, visibility: visibility)
     self.commandStack = commandStack
 
     // Build the tool name and subcommand name from the command configuration
@@ -121,25 +121,24 @@ internal struct HelpGenerator {
       }
       self.abstract += "\n\(currentCommand.configuration.discussion)"
     }
-    
-    self.sections = HelpGenerator.generateSections(commandStack: commandStack, includeHidden: includeHidden)
+
+    self.sections = HelpGenerator.generateSections(commandStack: commandStack, visibility: visibility)
     self.discussionSections = []
   }
 
-  init(_ type: ParsableArguments.Type, includeHidden: Bool = false) {
-    self.init(commandStack: [type.asCommand], includeHidden: includeHidden)
+  init(_ type: ParsableArguments.Type, visibility: ArgumentVisibility) {
+    self.init(commandStack: [type.asCommand], visibility: visibility)
   }
 
-  private static func generateSections(commandStack: [ParsableCommand.Type], includeHidden: Bool) -> [Section] {
+  private static func generateSections(commandStack: [ParsableCommand.Type], visibility: ArgumentVisibility) -> [Section] {
     guard !commandStack.isEmpty else { return [] }
 
     var positionalElements: [Section.Element] = []
     var optionElements: [Section.Element] = []
 
     /// Start with a full slice of the ArgumentSet so we can peel off one or
     /// more elements at a time.
-    var args = commandStack.argumentsForHelp(includeHidden: includeHidden)[...]
-    
+    var args = commandStack.argumentsForHelp(visibility: visibility)[...]
     while let arg = args.popFirst() {
       guard arg.help.visibility == .default else { continue }
 
@@ -300,7 +299,7 @@ internal extension BidirectionalCollection where Element == ParsableCommand.Type
       .map { $0.configuration.helpNames!.generateHelpNames(visibility: visibility) }
       ?? CommandConfiguration.defaultHelpNames.generateHelpNames(visibility: visibility)
   }
-  
+
   func getPrimaryHelpName() -> Name? {
     getHelpNames(visibility: .default).preferredName
   }
@@ -340,8 +339,8 @@ internal extension BidirectionalCollection where Element == ParsableCommand.Type
 
   /// Returns the ArgumentSet for the last command in this stack, including
   /// help and version flags, when appropriate.
-  func argumentsForHelp(includeHidden: Bool = false) -> ArgumentSet {
-    guard var arguments = self.last.map({ ArgumentSet($0, creatingHelp: true, includeHidden: includeHidden) })
+  func argumentsForHelp(visibility: ArgumentVisibility) -> ArgumentSet {
+    guard var arguments = self.last.map({ ArgumentSet($0, visibility: visibility) })
       else { return ArgumentSet() }
     self.versionArgumentDefinition().map { arguments.append($0) }
     self.helpArgumentDefinition().map { arguments.append($0) }

Sources/ArgumentParser/Usage/MessageInfo.swift

@@ -28,7 +28,7 @@ enum MessageInfo {
       // Exit early on built-in requests
       switch e.parserError {
       case .helpRequested(let visibility):
-        self = .help(text: HelpGenerator(commandStack: e.commandStack, includeHidden: visibility != .default).rendered())
+        self = .help(text: HelpGenerator(commandStack: e.commandStack, visibility: visibility).rendered())
         return
 
       case .dumpHelpRequested:
@@ -73,7 +73,7 @@ enum MessageInfo {
       parserError = .userValidationError(error)
     }
 
-    var usage = HelpGenerator(commandStack: commandStack).usageMessage()
+    var usage = HelpGenerator(commandStack: commandStack, visibility: .default).usageMessage()
 
     let commandNames = commandStack.map { $0._commandName }.joined(separator: " ")
     if let helpName = commandStack.getPrimaryHelpName() {
@@ -96,7 +96,7 @@ enum MessageInfo {
           if let command = command {
             commandStack = CommandParser(type.asCommand).commandStack(for: command)
           }
-          self = .help(text: HelpGenerator(commandStack: commandStack).rendered())
+          self = .help(text: HelpGenerator(commandStack: commandStack, visibility: .default).rendered())
         case .dumpRequest(let command):
           if let command = command {
             commandStack = CommandParser(type.asCommand).commandStack(for: command)
@@ -119,9 +119,9 @@ enum MessageInfo {
     } else if let parserError = parserError {
       let usage: String = {
         guard case ParserError.noArguments = parserError else { return usage }
-        return "\n" + HelpGenerator(commandStack: [type.asCommand]).rendered()
+        return "\n" + HelpGenerator(commandStack: [type.asCommand], visibility: .default).rendered()
       }()
-      let argumentSet = ArgumentSet(commandStack.last!)
+      let argumentSet = ArgumentSet(commandStack.last!, visibility: .default)
       let message = argumentSet.errorDescription(error: parserError) ?? ""
       let helpAbstract = argumentSet.helpDescription(error: parserError) ?? ""
       self = .validation(message: message, usage: usage, help: helpAbstract)

Sources/ArgumentParser/Usage/UsageGenerator.swift

@@ -23,7 +23,9 @@ extension UsageGenerator {
   }
 
   init(toolName: String, parsable: ParsableArguments) {
-    self.init(toolName: toolName, definition: ArgumentSet(type(of: parsable)))
+    self.init(
+      toolName: toolName,
+      definition: ArgumentSet(type(of: parsable), visibility: .default))
   }
 
   init(toolName: String, definition: [ArgumentSet]) {

Tests/ArgumentParserUnitTests/HelpGenerationTests.swift

@@ -71,6 +71,29 @@ extension HelpGenerationTests {
               -h, --help              Show help information.
 
             """)
+
+#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]
+
+            ARGUMENTS:
+              <hidden-name>
+
+            OPTIONS:
+              --name <name>           Your name
+              --title <title>         Your title
+              --hidden-title <hidden-title>
+              --hidden-flag
+              --hidden-inverted-flag/--no-hidden-inverted-flag
+                                      (default: true)
+              -h, --help              Show help information.
+
+            """)
+#endif
   }
 
   struct C: ParsableArguments {
@@ -322,7 +345,8 @@ extension HelpGenerationTests {
   }
 
   func testOverviewButNoAbstractSpacing() {
-    let renderedHelp = HelpGenerator(J.self).rendered()
+    let renderedHelp = HelpGenerator(J.self, visibility: .default)
+      .rendered()
     AssertEqualStringsIgnoringTrailingWhitespace(renderedHelp, """
     OVERVIEW:
     test
@@ -508,7 +532,7 @@ extension HelpGenerationTests {
     let helpMessage = """
       OVERVIEW: Demo hiding option groups
 
-      USAGE: driver [--verbose] [--custom-name <custom-name>] [--timeout <timeout>]
+      USAGE: driver [--timeout <timeout>]
 
       OPTIONS:
         --timeout <timeout>     Time to wait before timeout (in seconds)
@@ -569,7 +593,7 @@ extension HelpGenerationTests {
   }
 
   func testAllValues() {
-    let opts = ArgumentSet(AllValues.self)
+    let opts = ArgumentSet(AllValues.self, visibility: .private)
     XCTAssertEqual(AllValues.Manual.allValueStrings, opts[0].help.allValues)
     XCTAssertEqual(AllValues.Manual.allValueStrings, opts[1].help.allValues)