Add --help-hidden for use with _hiddenFromHelp

Swift Package Manager adopted _hiddenFromHelp, the resulting help is
much more approachable for basic usage, but leaves no way to view
all the advanced options it accepts. This takes from swiftc's + clang's
playbook and adds a hidden `--help-hidden` flag that prints all help,
including those using `_hiddenFromHelp`

Author: keith

Sources/ArgumentParser/CMakeLists.txt

@@ -33,6 +33,7 @@ add_library(ArgumentParser
 
   Usage/DumpHelpGenerator.swift
   Usage/HelpCommand.swift
+  Usage/HelpHiddenCommand.swift
   Usage/HelpGenerator.swift
   Usage/MessageInfo.swift
   Usage/UsageGenerator.swift

Sources/ArgumentParser/Parsable Types/ParsableArguments.swift

@@ -95,6 +95,8 @@ extension ParsableArguments {
     switch try self.asCommand.parseAsRoot(arguments) {
     case is HelpCommand:
       throw ParserError.helpRequested
+    case is HelpHiddenCommand:
+      throw ParserError.helpHiddenRequested
     case let result as _WrappedParsableCommand<Self>:
       return result.options
     case var result as Self:
@@ -243,7 +245,7 @@ extension ArgumentSetProvider {
 }
 
 extension ArgumentSet {
-  init(_ type: ParsableArguments.Type, creatingHelp: Bool = false) {
+  init(_ type: ParsableArguments.Type, creatingHelp: Bool = false, includeHidden: Bool = false) {
 
     #if DEBUG
     do {
@@ -259,7 +261,7 @@ extension ArgumentSet {
         guard var codingKey = child.label else { return nil }
 
         if let parsed = child.value as? ArgumentSetProvider {
-          if creatingHelp {
+          if creatingHelp && !includeHidden {
             guard !parsed._hiddenFromHelp else { return nil }
           }
 

Sources/ArgumentParser/Parsing/CommandParser.swift

@@ -15,6 +15,7 @@ struct CommandError: Error {
 }
 
 struct HelpRequested: Error {}
+private struct HelpHiddenRequested: Error {}
 
 struct CommandParser {
   let commandTree: Tree<ParsableCommand.Type>
@@ -74,11 +75,15 @@ extension CommandParser {
   /// Throws a `HelpRequested` error if the user has specified either of the
   /// built in help flags.
   func checkForBuiltInFlags(_ split: SplitArguments) throws {
+    guard !split.contains(Name.long("help-hidden")) else {
+      throw HelpHiddenRequested()
+    }
+
     // Look for help flags
     guard !split.contains(anyOf: self.commandStack.getHelpNames()) else {
       throw HelpRequested()
     }
-    
+
     // Look for the "dump help" request
     guard !split.contains(Name.long("experimental-dump-help")) else {
       throw CommandError(commandStack: commandStack, parserError: .dumpHelpRequested)
@@ -225,6 +230,10 @@ extension CommandParser {
         try helpResult.buildCommandStack(with: self)
         return .success(helpResult)
       }
+      if var helpResult = result as? HelpHiddenCommand {
+        try helpResult.buildCommandStack(with: self)
+        return .success(helpResult)
+      }
       return .success(result)
     } catch let error as CommandError {
       return .failure(error)
@@ -233,6 +242,8 @@ extension CommandParser {
       return .failure(CommandError(commandStack: commandStack, parserError: error))
     } catch is HelpRequested {
       return .success(HelpCommand(commandStack: commandStack))
+    } catch is HelpHiddenRequested {
+      return .success(HelpHiddenCommand(commandStack: commandStack))
     } catch {
       return .failure(CommandError(commandStack: commandStack, parserError: .invalidState))
     }

Sources/ArgumentParser/Parsing/ParserError.swift

@@ -12,6 +12,7 @@
 /// Gets thrown while parsing and will be handled by the error output generation.
 enum ParserError: Error {
   case helpRequested
+  case helpHiddenRequested
   case versionRequested
   case dumpHelpRequested
 

Sources/ArgumentParser/Usage/HelpGenerator.swift

@@ -102,7 +102,7 @@ internal struct HelpGenerator {
   var sections: [Section]
   var discussionSections: [DiscussionSection]
 
-  init(commandStack: [ParsableCommand.Type]) {
+  init(commandStack: [ParsableCommand.Type], includeHidden: Bool = false) {
     guard let currentCommand = commandStack.last else {
       fatalError()
     }
@@ -131,23 +131,23 @@ internal struct HelpGenerator {
     }
 
     self.usage = Usage(components: [usageString])
-    self.sections = HelpGenerator.generateSections(commandStack: commandStack)
+    self.sections = HelpGenerator.generateSections(commandStack: commandStack, includeHidden: includeHidden)
     self.discussionSections = []
   }
 
   init(_ type: ParsableArguments.Type) {
     self.init(commandStack: [type.asCommand])
   }
 
-  static func generateSections(commandStack: [ParsableCommand.Type]) -> [Section] {
+  private static func generateSections(commandStack: [ParsableCommand.Type], includeHidden: Bool) -> [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()[...]
+    var args = commandStack.argumentsForHelp(includeHidden: includeHidden)[...]
 
     while let arg = args.popFirst() {
       guard arg.help.shouldDisplay else { continue }
@@ -322,8 +322,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() -> ArgumentSet {
-    guard var arguments = self.last.map({ ArgumentSet($0, creatingHelp: true) })
+  func argumentsForHelp(includeHidden: Bool = false) -> ArgumentSet {
+    guard var arguments = self.last.map({ ArgumentSet($0, creatingHelp: true, includeHidden: includeHidden) })
       else { return ArgumentSet() }
     self.versionArgumentDefinition().map { arguments.append($0) }
     self.helpArgumentDefinition().map { arguments.append($0) }

Sources/ArgumentParser/Usage/HelpHiddenCommand.swift

@@ -0,0 +1,57 @@
+//===----------------------------------------------------------*- swift -*-===//
+//
+// This source file is part of the Swift Argument Parser open source project
+//
+// Copyright (c) 2020 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+//
+//===----------------------------------------------------------------------===//
+
+struct HelpHiddenCommand: ParsableCommand {
+  static var configuration = CommandConfiguration(
+    commandName: "help-hidden",
+    abstract: "Show help information, including hidden options",
+    helpNames: [])
+
+  /// Any subcommand names provided after the `help` subcommand.
+  @Argument var subcommands: [String] = []
+
+  /// Capture and ignore any extra help flags given by the user.
+  @Flag(name: [.customLong("help-hidden", withSingleDash: false)], help: .hidden)
+  var helpHidden = false
+
+  private(set) var commandStack: [ParsableCommand.Type] = []
+
+  init() {}
+
+  mutating func run() throws {
+    throw CommandError(commandStack: commandStack, parserError: .helpHiddenRequested)
+  }
+
+  mutating func buildCommandStack(with parser: CommandParser) throws {
+    commandStack = parser.commandStack(for: subcommands)
+  }
+
+  func generateHelp() -> String {
+    return HelpGenerator(commandStack: commandStack, includeHidden: true).rendered()
+  }
+
+  enum CodingKeys: CodingKey {
+    case subcommands
+    case helpHidden
+  }
+
+  init(from decoder: Decoder) throws {
+    let container = try decoder.container(keyedBy: CodingKeys.self)
+    self.subcommands = try container.decode([String].self, forKey: .subcommands)
+    self.helpHidden = try container.decode(Bool.self, forKey: .helpHidden)
+  }
+
+  init(commandStack: [ParsableCommand.Type]) {
+    self.commandStack = commandStack
+    self.subcommands = commandStack.map { $0._commandName }
+    self.helpHidden = false
+  }
+}

Sources/ArgumentParser/Usage/MessageInfo.swift

@@ -31,6 +31,9 @@ enum MessageInfo {
         self = .help(text: HelpGenerator(commandStack: e.commandStack).rendered())
         return
 
+      case .helpHiddenRequested:
+        self = .help(text: HelpGenerator(commandStack: e.commandStack, includeHidden: true).rendered())
+        return
 
       case .dumpHelpRequested:
         self = .help(text: DumpHelpGenerator(commandStack: e.commandStack).rendered())

Sources/ArgumentParser/Usage/UsageGenerator.swift

@@ -161,7 +161,7 @@ struct ErrorMessageGenerator {
 extension ErrorMessageGenerator {
   func makeErrorMessage() -> String? {
     switch error {
-    case .helpRequested, .versionRequested, .completionScriptRequested, .completionScriptCustomResponse, .dumpHelpRequested:
+    case .helpRequested, .helpHiddenRequested, .versionRequested, .completionScriptRequested, .completionScriptCustomResponse, .dumpHelpRequested:
       return nil
 
     case .unsupportedShell(let shell?):

Sources/ArgumentParserTestHelpers/TestHelpers.swift

@@ -139,6 +139,20 @@ public func AssertHelp<T: ParsableCommand, U: ParsableCommand>(
     helpString, expected, file: file, line: line)
 }
 
+public func AssertHelpHidden<T: ParsableArguments>(
+  for _: T.Type, equals expected: String,
+  file: StaticString = #file, line: UInt = #line
+) {
+  do {
+    _ = try T.parse(["--help-hidden"])
+    XCTFail(file: (file), line: line)
+  } catch {
+    let helpString = T.fullMessage(for: error)
+    AssertEqualStringsIgnoringTrailingWhitespace(
+      helpString, expected, file: file, line: line)
+  }
+}
+
 public func AssertDump<T: ParsableArguments>(
   for _: T.Type, equals expected: String,
   file: StaticString = #file, line: UInt = #line

Tests/ArgumentParserUnitTests/HelpGenerationTests.swift

@@ -506,6 +506,23 @@ extension HelpGenerationTests {
     )
   }
 
+  func testHelpHiddenShowsAll() throws {
+    AssertHelpHidden(for: HideDriver.self, equals: """
+        OVERVIEW: Demo hiding option groups
+
+        USAGE: driver [--verbose] [--custom-name <custom-name>] [--timeout <timeout>]
+
+        OPTIONS:
+          --verbose               Verbose
+          --custom-name <custom-name>
+                                  Custom Name
+          --timeout <timeout>     Time to wait before timeout (in seconds)
+          -h, --help              Show help information.
+        
+        """
+    )
+  }
+
   struct AllValues: ParsableCommand {
     enum Manual: Int, ExpressibleByArgument {
       case foo