Merge branch 'main' into async

Author: natecook1000

Sources/ArgumentParser/CMakeLists.txt

@@ -6,6 +6,7 @@ add_library(ArgumentParser
 
   "Parsable Properties/Argument.swift"
   "Parsable Properties/ArgumentHelp.swift"
+  "Parsable Properties/ArgumentVisibility.swift"
   "Parsable Properties/CompletionKind.swift"
   "Parsable Properties/Errors.swift"
   "Parsable Properties/Flag.swift"
@@ -34,7 +35,6 @@ add_library(ArgumentParser
 
   Usage/DumpHelpGenerator.swift
   Usage/HelpCommand.swift
-  Usage/HelpHiddenCommand.swift
   Usage/HelpGenerator.swift
   Usage/MessageInfo.swift
   Usage/UsageGenerator.swift

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 }
@@ -178,7 +180,7 @@ struct BashCompletionsGenerator {
 extension ArgumentDefinition {
   /// Returns the different completion names for this argument.
   fileprivate func bashCompletionWords() -> [String] {
-    return help.shouldDisplay
+    return help.visibility == .default
       ? names.map { $0.synopsisString }
       : []
   }

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) }
 
@@ -100,7 +100,7 @@ extension Name {
 
 extension ArgumentDefinition {
   fileprivate func argumentSegments(_ commandChain: [String]) -> [([String], String)] {
-    guard help.shouldDisplay else { return [] }
+    guard help.visibility == .default else { return [] }
 
     var results = [([String], String)]()
     var formattedFlags = [String]()

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) }
   }
 }
 
@@ -132,7 +134,7 @@ extension ArgumentDefinition {
   }
 
   func zshCompletionString(_ commands: [ParsableCommand.Type]) -> String? {
-    guard help.shouldDisplay else { return nil }
+    guard help.visibility == .default else { return nil }
 
     var inputs: String
     switch update {

Sources/ArgumentParser/Documentation.docc/Extensions/ParsableArguments.md

@@ -19,7 +19,7 @@
 
 ### Generating Help Text
 
-- ``helpMessage(columns:)``
+- ``helpMessage(includeHidden:columns:)``
 
 ### Handling Errors
 

Sources/ArgumentParser/Documentation.docc/Extensions/ParsableCommand.md

@@ -13,7 +13,7 @@
 
 ### Generating Help Text
 
-- ``helpMessage(for:columns:)``
+- ``helpMessage(for:includeHidden:columns:)``
 
 ### Starting the Program
 

Sources/ArgumentParser/Parsable Properties/ArgumentHelp.swift

@@ -11,18 +11,6 @@
 
 /// Help information for a command-line argument.
 public struct ArgumentHelp {
-  /// Visibility level of an argument's help.
-  public enum Visibility {
-      /// Show help for this argument whenever appropriate.
-      case `default`
-
-      /// Only show help for this argument in the extended help screen.
-      case hidden
-
-      /// Never show help for this argument.
-      case `private`
-  }
-
   /// A short description of the argument.
   public var abstract: String = ""
 
@@ -38,7 +26,7 @@ public struct ArgumentHelp {
 
   /// A visibility level indicating whether this argument should be shown in
   /// the extended help display.
-  public var visibility: Visibility = .default
+  public var visibility: ArgumentVisibility = .default
 
   /// A Boolean value indicating whether this argument should be shown in
   /// the extended help display.
@@ -71,7 +59,7 @@ public struct ArgumentHelp {
     _ abstract: String = "",
     discussion: String = "",
     valueName: String? = nil,
-    visibility: Visibility = .default)
+    visibility: ArgumentVisibility = .default)
   {
     self.abstract = abstract
     self.discussion = discussion

Sources/ArgumentParser/Parsable Properties/ArgumentVisibility.swift

@@ -0,0 +1,46 @@
+//===----------------------------------------------------------*- 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
+//
+//===----------------------------------------------------------------------===//
+
+/// Visibility level of an argument's help.
+public enum ArgumentVisibility {
+    /// Show help for this argument whenever appropriate.
+    case `default`
+
+    /// Only show help for this argument in the extended help screen.
+    case hidden
+
+    /// 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

@@ -31,14 +31,15 @@
 @propertyWrapper
 public struct OptionGroup<Value: ParsableArguments>: Decodable, ParsedWrapper {
   internal var _parsedValue: Parsed<Value>
-  internal var _hiddenFromHelp: Bool = false
-  
+  internal var _visibility: ArgumentVisibility
+
   // FIXME: Adding this property works around the crasher described in
   // https://github.com/apple/swift-argument-parser/issues/338
   internal var _dummy: Bool = false
 
   internal init(_parsedValue: Parsed<Value>) {
     self._parsedValue = _parsedValue
+    self._visibility = .default
   }
 
   public init(from decoder: Decoder) throws {
@@ -63,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)
     })
   }
 
@@ -96,8 +97,14 @@ extension OptionGroup: CustomStringConvertible {
 
 // Experimental use with caution
 extension OptionGroup {
-    public init(_hiddenFromHelp: Bool) {
-        self.init()
-        self._hiddenFromHelp = _hiddenFromHelp
-    }
+  @available(*, deprecated, message: "Use init(_visibility:) instead.")
+  public init(_hiddenFromHelp: Bool) {
+    self.init()
+    self._visibility = .hidden
+  }
+
+  public init(_visibility: ArgumentVisibility) {
+    self.init()
+    self._visibility = _visibility
+  }
 }

Sources/ArgumentParser/Parsable Types/ParsableArguments.swift

@@ -95,10 +95,8 @@ extension ParsableArguments {
   ) throws -> Self {
     // Parse the command and unwrap the result if necessary.
     switch try self.asCommand.parseAsRoot(arguments) {
-    case is HelpCommand:
-      throw ParserError.helpRequested
-    case is HelpHiddenCommand:
-      throw ParserError.helpHiddenRequested
+    case let helpCommand as HelpCommand:
+      throw ParserError.helpRequested(visibility: helpCommand.visibility)
     case let result as _WrappedParsableCommand<Self>:
       return result.options
     case var result as Self:
@@ -134,15 +132,39 @@ extension ParsableArguments {
   ) -> String {
     MessageInfo(error: error, type: self).fullText(for: self)
   }
-  
+
   /// Returns the text of the help screen for this type.
   ///
-  /// - Parameter columns: The column width to use when wrapping long lines in
-  ///   the help screen. If `columns` is `nil`, uses the current terminal width,
-  ///   or a default value of `80` if the terminal width is not available.
+  /// - Parameters:
+  ///   - columns: The column width to use when wrapping long line in the
+  ///     help screen. If `columns` is `nil`, uses the current terminal
+  ///     width, or a default value of `80` if the terminal width is not
+  ///     available.
   /// - Returns: The full help screen for this type.
-  public static func helpMessage(columns: Int? = nil) -> String {
-    HelpGenerator(self).rendered(screenWidth: columns)
+  @_disfavoredOverload
+  @available(*, deprecated, message: "Use helpMessage(includeHidden:columns:) instead.")
+  public static func helpMessage(
+    columns: Int?
+  ) -> String {
+    helpMessage(includeHidden: false, columns: columns)
+  }
+
+  /// Returns the text of the help screen for this type.
+  ///
+  /// - Parameters:
+  ///   - includeHidden: Include hidden help information in the generated
+  ///     message.
+  ///   - columns: The column width to use when wrapping long line in the
+  ///     help screen. If `columns` is `nil`, uses the current terminal
+  ///     width, or a default value of `80` if the terminal width is not
+  ///     available.
+  /// - Returns: The full help screen for this type.
+  public static func helpMessage(
+    includeHidden: Bool = false,
+    columns: Int? = nil
+  ) -> String {
+    HelpGenerator(self, visibility: includeHidden ? .hidden : .default)
+      .rendered(screenWidth: columns)
   }
 
   /// Returns the JSON representation of this type.
@@ -239,15 +261,15 @@ func nilOrValue(_ value: Any) -> Any? {
 protocol ArgumentSetProvider {
   func argumentSet(for key: InputKey) -> ArgumentSet
 
-  var _hiddenFromHelp: Bool { get }
+  var _visibility: ArgumentVisibility { get }
 }
 
 extension ArgumentSetProvider {
-  var _hiddenFromHelp: Bool { false }
+  var _visibility: ArgumentVisibility { .default }
 }
 
 extension ArgumentSet {
-  init(_ type: ParsableArguments.Type, creatingHelp: Bool = false, includeHidden: Bool = false) {
+  init(_ type: ParsableArguments.Type, visibility: ArgumentVisibility) {
 
     #if DEBUG
     do {
@@ -263,9 +285,8 @@ extension ArgumentSet {
         guard var codingKey = child.label else { return nil }
 
         if let parsed = child.value as? ArgumentSetProvider {
-          if creatingHelp && !includeHidden {
-            guard !parsed._hiddenFromHelp 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

@@ -77,12 +77,39 @@ extension ParsableCommand {
   ///     help screen. If `columns` is `nil`, uses the current terminal
   ///     width, or a default value of `80` if the terminal width is not
   ///     available.
+  /// - Returns: The full help screen for this type.
+  @_disfavoredOverload
+  @available(*, deprecated, message: "Use helpMessage(for:includeHidden:columns:) instead.")
   public static func helpMessage(
     for subcommand: ParsableCommand.Type,
     columns: Int? = nil
   ) -> String { 
-    let stack = CommandParser(self).commandStack(for: subcommand)
-    return HelpGenerator(commandStack: stack).rendered(screenWidth: columns)
+    helpMessage(for: subcommand, includeHidden: false, columns: columns)
+  }
+
+  /// Returns the text of the help screen for the given subcommand of this
+  /// command.
+  ///
+  /// - Parameters:
+  ///   - subcommand: The subcommand to generate the help screen for.
+  ///     `subcommand` must be declared in the subcommand tree of this
+  ///     command.
+  ///   - includeHidden: Include hidden help information in the generated
+  ///     message.
+  ///   - columns: The column width to use when wrapping long line in the
+  ///     help screen. If `columns` is `nil`, uses the current terminal
+  ///     width, or a default value of `80` if the terminal width is not
+  ///     available.
+  /// - Returns: The full help screen for this type.
+  public static func helpMessage(
+    for subcommand: ParsableCommand.Type,
+    includeHidden: Bool = false,
+    columns: Int? = nil
+  ) -> String {
+    HelpGenerator(
+      commandStack: CommandParser(self).commandStack(for: subcommand),
+      visibility: includeHidden ? .hidden : .default)
+        .rendered(screenWidth: columns)
   }
 
   /// Parses an instance of this type, or one of its subcommands, from
@@ -114,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/ArgumentDefinition.swift

@@ -44,7 +44,7 @@ struct ArgumentDefinition {
     var abstract: String = ""
     var discussion: String = ""
     var valueName: String = ""
-    var shouldDisplay: Bool = true
+    var visibility: ArgumentVisibility = .default
 
     var defaultValue: String?
     var keys: [InputKey]
@@ -79,7 +79,7 @@ struct ArgumentDefinition {
       self.abstract = help?.abstract ?? ""
       self.discussion = help?.discussion ?? ""
       self.valueName = help?.valueName ?? ""
-      self.shouldDisplay = (help?.visibility ?? .default) == .default
+      self.visibility = help?.visibility ?? .default
     }
   }