Add APIs for generating the help screen (#142)

* Add public API for generating help text

* Add tests for `helpMessage()`

* Update documentation

* Use new rendered method instead of property

Author: natecook1000

Documentation/04 Customizing Help.md

@@ -165,3 +165,17 @@ struct Example: ParsableCommand {
     var experimentalEnableWidgets: Bool
 }
 ```
+
+## Generating Help Text Programmatically
+
+The help screen is automatically shown to users when they call your command with the help flag. You can generate the same text from within your program by calling the `helpMessage()` method.
+
+```swift
+let help = Repeat.helpMessage()
+// `help` matches the output above
+
+let fortyColumnHelp = Repeat.helpMessage(columns: 40)
+// `fortyColumnHelp` is the same help screen, but wrapped to 40 columns
+```
+
+When generating help text for a subcommand, call `helpMessage(for:)` on the `ParsableCommand` type that represents the root of the command tree and pass the subcommand type as a parameter to ensure the correct display.

Sources/ArgumentParser/Parsable Types/ParsableArguments.swift

@@ -125,6 +125,16 @@ extension ParsableArguments {
     MessageInfo(error: error, type: self).fullText
   }
 
+  /// 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.
+  /// - Returns: The full help screen for this type.
+  public static func helpMessage(columns: Int? = nil) -> String {
+    HelpGenerator(self).rendered(screenWidth: columns)
+  }
+
   /// Returns the exit code for the given error.
   ///
   /// The returned code is the same exit code that is used if `error` is passed

Sources/ArgumentParser/Parsable Types/ParsableCommand.swift

@@ -64,6 +64,25 @@ extension ParsableCommand {
     return try parser.parse(arguments: arguments).get()
   }
 
+  /// 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.
+  ///   - 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.
+  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)
+  }
+
   /// Parses an instance of this type, or one of its subcommands, from
   /// command-line arguments and calls its `run()` method, exiting cleanly
   /// or with a relevant error message.

Sources/ArgumentParser/Usage/HelpCommand.swift

@@ -27,7 +27,7 @@ struct HelpCommand: ParsableCommand {
   }
 
   func generateHelp() -> String {
-    return HelpGenerator(commandStack: commandStack).rendered
+    return HelpGenerator(commandStack: commandStack).rendered()
   }
 
   enum CodingKeys: CodingKey {

Sources/ArgumentParser/Usage/HelpGenerator.swift

@@ -12,7 +12,7 @@
 internal struct HelpGenerator {
   static var helpIndent = 2
   static var labelColumnWidth = 26
-  static var screenWidth: Int {
+  static var systemScreenWidth: Int {
     _screenWidthOverride ?? _terminalSize().width
   }
 
@@ -21,7 +21,7 @@ internal struct HelpGenerator {
   struct Usage {
     var components: [String]
 
-    var rendered: String {
+    func rendered(screenWidth: Int) -> String {
       components
         .joined(separator: "\n")
     }
@@ -37,13 +37,13 @@ internal struct HelpGenerator {
         String(repeating: " ", count: HelpGenerator.helpIndent) + label
       }
 
-      var rendered: String {
+      func rendered(screenWidth: Int) -> String {
         let paddedLabel = self.paddedLabel
         let wrappedAbstract = self.abstract
-          .wrapped(to: HelpGenerator.screenWidth, wrappingIndent: HelpGenerator.labelColumnWidth)
+          .wrapped(to: screenWidth, wrappingIndent: HelpGenerator.labelColumnWidth)
         let wrappedDiscussion = self.discussion.isEmpty
           ? ""
-          : self.discussion.wrapped(to: HelpGenerator.screenWidth, wrappingIndent: HelpGenerator.helpIndent * 4) + "\n"
+          : self.discussion.wrapped(to: screenWidth, wrappingIndent: HelpGenerator.helpIndent * 4) + "\n"
         let renderedAbstract: String = {
           guard !abstract.isEmpty else { return "" }
           if paddedLabel.count < HelpGenerator.labelColumnWidth {
@@ -82,10 +82,10 @@ internal struct HelpGenerator {
     var discussion: String = ""
     var isSubcommands: Bool = false
 
-    var rendered: String {
+    func rendered(screenWidth: Int) -> String {
       guard !elements.isEmpty else { return "" }
 
-      let renderedElements = elements.map { $0.rendered }.joined()
+      let renderedElements = elements.map { $0.rendered(screenWidth: screenWidth) }.joined()
       return "\(String(describing: header).uppercased()):\n"
         + renderedElements
     }
@@ -125,6 +125,10 @@ internal struct HelpGenerator {
     self.discussionSections = []
   }
 
+  init(_ type: ParsableArguments.Type) {
+    self.init(commandStack: [type.asCommand])
+  }
+
   static func generateSections(commandStack: [ParsableCommand.Type]) -> [Section] {
     var positionalElements: [Section.Element] = []
     var optionElements: [Section.Element] = []
@@ -219,22 +223,24 @@ internal struct HelpGenerator {
     ]
   }
 
-  var usageMessage: String {
-    "Usage: \(usage.rendered)"
+  func usageMessage(screenWidth: Int? = nil) -> String {
+    let screenWidth = screenWidth ?? HelpGenerator.systemScreenWidth
+    return "Usage: \(usage.rendered(screenWidth: screenWidth))"
   }
 
-  var rendered: String {
+  func rendered(screenWidth: Int? = nil) -> String {
+    let screenWidth = screenWidth ?? HelpGenerator.systemScreenWidth
     let renderedSections = sections
-      .map { $0.rendered }
+      .map { $0.rendered(screenWidth: screenWidth) }
       .filter { !$0.isEmpty }
       .joined(separator: "\n")
     let renderedAbstract = abstract.isEmpty
       ? ""
-      : "OVERVIEW: \(abstract)".wrapped(to: HelpGenerator.screenWidth) + "\n\n"
+      : "OVERVIEW: \(abstract)".wrapped(to: screenWidth) + "\n\n"
 
     return """
     \(renderedAbstract)\
-    USAGE: \(usage.rendered)
+    USAGE: \(usage.rendered(screenWidth: screenWidth))
     
     \(renderedSections)
     """

Sources/ArgumentParser/Usage/MessageInfo.swift

@@ -27,7 +27,7 @@ enum MessageInfo {
 
       switch e.parserError {
       case .helpRequested:
-        self = .help(text: HelpGenerator(commandStack: e.commandStack).rendered)
+        self = .help(text: HelpGenerator(commandStack: e.commandStack).rendered())
         return
       case .versionRequested:
         let versionString = commandStack
@@ -43,7 +43,7 @@ enum MessageInfo {
       commandStack = [type.asCommand]
       parserError = e
       if case .helpRequested = e {
-        self = .help(text: HelpGenerator(commandStack: [type.asCommand]).rendered)
+        self = .help(text: HelpGenerator(commandStack: [type.asCommand]).rendered())
         return
       }
     default:
@@ -53,7 +53,7 @@ enum MessageInfo {
       parserError = .userValidationError(error)
     }
 
-    let usage = HelpGenerator(commandStack: commandStack).usageMessage
+    let usage = HelpGenerator(commandStack: commandStack).usageMessage()
 
     // Parsing errors and user-thrown validation errors have the usage
     // string attached. Other errors just get the error message.
@@ -68,7 +68,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).rendered())
         case .message(let message):
           self = .help(text: message)
         }
@@ -82,7 +82,7 @@ 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]).rendered()
       }()
       let message = ArgumentSet(commandStack.last!).helpMessage(for: parserError)
       self = .validation(message: message, usage: usage)

Sources/ArgumentParserTestHelpers/TestHelpers.swift

@@ -117,12 +117,25 @@ public func AssertHelp<T: ParsableArguments>(
 ) {
   do {
     _ = try T.parse(["-h"])
-    XCTFail()
+    XCTFail(file: file, line: line)
   } catch {
     let helpString = T.fullMessage(for: error)
     AssertEqualStringsIgnoringTrailingWhitespace(
       helpString, expected, file: file, line: line)
   }
+  
+  let helpString = T.helpMessage()
+  AssertEqualStringsIgnoringTrailingWhitespace(
+    helpString, expected, file: file, line: line)
+}
+
+public func AssertHelp<T: ParsableCommand, U: ParsableCommand>(
+  for _: T.Type, root _: U.Type, equals expected: String,
+  file: StaticString = #file, line: UInt = #line
+) {
+  let helpString = U.helpMessage(for: T.self)
+  AssertEqualStringsIgnoringTrailingWhitespace(
+    helpString, expected, file: file, line: line)
 }
 
 extension XCTest {

Tests/ArgumentParserUnitTests/HelpGenerationTests.swift

@@ -132,7 +132,6 @@ extension HelpGenerationTests {
     }
   }
 
-
   struct D: ParsableCommand {
     @Argument(default: "--", help: "Your occupation.")
     var occupation: String
@@ -267,8 +266,8 @@ extension HelpGenerationTests {
 
     """)
 
-    AssertHelp(for: H.AnotherCommand.self, equals: """
-    USAGE: another-command [--some-option-with-very-long-name <some-option-with-very-long-name>] [--option <option>] [<argument-with-very-long-name-and-help>] [<argument-with-very-long-name>] [<argument>]
+    AssertHelp(for: H.AnotherCommand.self, root: H.self, equals: """
+    USAGE: h another-command [--some-option-with-very-long-name <some-option-with-very-long-name>] [--option <option>] [<argument-with-very-long-name-and-help>] [<argument-with-very-long-name>] [<argument>]
 
     ARGUMENTS:
       <argument-with-very-long-name-and-help>