Command generated help (#8)

* made init of Command public.

* updated for swift 4.2

* added discardable result.

* moved createTable to Help class.

* fixed config to runt with Swift 4.0 as well.

* updated xcode build image for travis.

* added automated help for commands and support for multiline help texts.

* fixed lint issue

Author: dastrobu

Sources/ArgTree.swift

@@ -110,8 +110,7 @@ public class ArgTree: ParserNode {
         let printHelp: () -> Void = {
             [unowned self] in
             var rows: [[String]] = []
-            self.parsers
-                .flatMap({ $0.description })
+            self.flatMap({ $0.description })
                 .forEach({ (argument: String, description: String) in
                     rows.append(["   ", argument, description])
                 })

Sources/parsers/Command.swift

@@ -1,3 +1,10 @@
+#if os(macOS)
+import Darwin
+#elseif os(Linux)
+import Glibc
+#endif
+import LoggerAPI
+
 public enum CommandParseError: Error {
     case commandAllowedOnlyOnce(command: Command, atIndex: Int)
 }
@@ -9,17 +16,34 @@ open class Command: ValueParser<Bool>, ParserNode {
 
     fileprivate var parsers: [Parser] = []
 
+    /** delegate to write to an output stream, defaults to stdout. */
+    public var writeToOutStream: (_ s: String) -> Void = { s in
+        print(s)
+    }
+
     public var defaultAction: (() -> Void)?
 
     /** callback invoked after all child parsers where invoked */
     public var afterChildrenParsed: OnParsed?
 
+    /**
+     * Create a Command.
+     * - Parameters:
+     *   - aliases: all strings that should be matched by this parser, e.g. for a flag '-v' and '--verbose'
+     *   - description: description to be shown in the global help
+     *                  (will also be used for generated help on the command, if `helpText` is not given)
+     *   - helpTest: help text for the generated help
+     */
     public init(name: String,
                 aliases: [String] = [],
                 description: String = "",
+                helpText: String? = nil,
                 stopToken: String? = "--",
                 parsed: OnParsed? = nil,
                 parsers: [Parser] = [],
+                helpPrinted: @escaping () -> Void = {
+                    exit(0)
+                },
                 afterChildrenParsed: OnParsed? = nil) {
 
         self.afterChildrenParsed = afterChildrenParsed
@@ -34,6 +58,22 @@ open class Command: ValueParser<Bool>, ParserNode {
         }
 
         self.parsers = parsers
+
+        let printHelp: () -> Void = {
+            [unowned self] in
+            var rows: [[String]] = []
+            self.flatMap({ $0.description })
+                .forEach({ (argument: String, description: String) in
+                    rows.append(["   ", argument, description])
+                })
+            self.writeToOutStream(
+                "\(helpText ?? description)\n\(Help.createTable(rows))")
+            helpPrinted()
+        }
+        // add help as first parse, to play together with the var arg parser
+        Log.debug("creating generated help flag as first parser")
+        insert(Help(longName: "help", shortName: "h", parsed: { _ in printHelp() }), at: 0)
+        defaultAction = printHelp
     }
 
     open override func parse(arguments: [String], atIndex i: Int, path: [ParsePathSegment]) throws -> Int {
@@ -119,6 +159,7 @@ public extension Command {
         parsers.removeSubrange(bounds)
     }
 
+    @discardableResult
     public func removeFirst() -> Parser {
         return parsers.removeFirst()
     }

Sources/parsers/Help.swift

@@ -5,30 +5,58 @@ public class Help: Flag {
 
     /** create a simple ascii table */
     public static func createTable(_ rows: [[String]]) -> String {
-        var colMaxCount: [Int] = []
+        var colCount = 0
+        var colWidths: [Int] = []
+        // number of lines per row
+        var rowLines: [Int] = Array(repeating: 0, count: rows.count)
         // determine the widths of the columns
-        rows.forEach { row in
-            row.enumerated().forEach { i, col in
-                if colMaxCount.count <= i {
-                    colMaxCount.append(col.count)
+        rows.enumerated().forEach { i, cols in
+            colCount = max(colCount, cols.count)
+            cols.enumerated().forEach { j, col in
+                let lines = String(col).split(separator: "\n")
+                rowLines[i] = max(rowLines[i], lines.count)
+                let colCount = lines.map {
+                    $0.count
+                }.max() ?? 0
+                if colWidths.count <= j {
+                    colWidths.append(colCount)
                 }
-                colMaxCount[i] = max(colMaxCount[i], col.count)
+                colWidths[j] = max(colWidths[j], col.count)
             }
         }
 
         // set the last col count to zero, to avoid padding the last col
-        if colMaxCount.popLast() != nil {
-            colMaxCount.append(0)
+        if colWidths.popLast() != nil {
+            colWidths.append(0)
+        }
+
+        // compute rows that account for multiline rows
+        var adjustedRows: [[String]] = []
+        for i in 0..<rows.count {
+            for _ in 0..<rowLines[i] {
+                adjustedRows.append(Array(repeating: "", count: colCount))
+            }
+        }
+
+        var i = 0
+        rows.enumerated().forEach { j, cols in
+            cols.enumerated().forEach { l, col in
+                let lines = String(col).split(separator: "\n")
+                lines.enumerated().forEach { k, line in
+                    adjustedRows[i + k][l] = String(line)
+                }
+            }
+            i += rowLines[j]
         }
 
         // format the columns
-        let r = rows.map { row in
+        let r = adjustedRows.map { row in
             return row
                 .enumerated()
                 .map({ i, col in
-                    if col.count < colMaxCount[i] {
+                    if col.count < colWidths[i] {
                         // right pad texts with whitespace
-                        return col + String(repeating: " ", count: colMaxCount[i] - col.count)
+                        return col + String(repeating: " ", count: colWidths[i] - col.count)
                     }
                     return col
                 }).joined(separator: " ")

Tests/argtreeTests/ArgTreeTests.swift

@@ -88,10 +88,10 @@ final class ArgTreeTests: XCTestCase {
         let tokensConsumed = try? argTree.parse(arguments: ["foo", "--help"])
         XCTAssertEqual(tokensConsumed, 2)
         let expected = """
-            usage
-                --help, -h print this help
-                --bar, -b  a bar flag
-            """
+                       usage
+                           --help, -h print this help
+                           --bar, -b  a bar flag
+                       """
         XCTAssertEqualTrimmingWhiteSpace(out, expected)
         XCTAssert(helpPrinted)
     }
@@ -112,9 +112,38 @@ final class ArgTreeTests: XCTestCase {
         let tokensConsumed = try? argTree.parse(arguments: ["foo", "--help"])
         XCTAssertEqual(tokensConsumed, 2)
         let expected = """
-            usage
-                --help, -h print this help
-            """
+                       usage
+                           --help, -h print this help
+                       """
+        XCTAssertEqualTrimmingWhiteSpace(out, expected)
+        XCTAssert(helpPrinted)
+    }
+
+    func testGeneratedHelpWithMultilineText() {
+        var helpPrinted = false
+        let argTree = ArgTree(description: "usage") {
+            helpPrinted = true
+        }
+        argTree.append(Flag(longName: "bar", shortName: "b", description:
+        """
+        bar is a nice flag
+        baz also
+        """, parsed: { _ in }))
+
+        var out = ""
+        argTree.writeToOutStream = { s in
+            print(s, to: &out)
+        }
+
+        argTree.defaultAction = nil
+        let tokensConsumed = try? argTree.parse(arguments: ["foo", "--help"])
+        XCTAssertEqual(tokensConsumed, 2)
+        let expected = """
+                       usage
+                           --help, -h print this help
+                           --bar, -b  bar is a nice flag
+                                      baz also
+                       """
         XCTAssertEqualTrimmingWhiteSpace(out, expected)
         XCTAssert(helpPrinted)
     }
@@ -171,17 +200,18 @@ final class ArgTreeTests: XCTestCase {
 
         try! argTree.parse(arguments: ["foo", "-h"])
         let expected = """
-            foo
-                --verbose, -v print verbose output
-                --help, -h    print this help
-            """
+                       foo
+                           --verbose, -v print verbose output
+                           --help, -h    print this help
+                       """
         XCTAssertEqualTrimmingWhiteSpace(out, expected)
     }
 
-#if !os(macOS)
+    #if !os(macOS)
     static var allTests = [
         ("testGeneratedHelp", testGeneratedHelp),
         ("testGeneratedHelpIgnoringFlagWithoutDescription", testGeneratedHelpIgnoringFlagWithoutDescription),
+        ("testGeneratedHelpWithMultilineText", testGeneratedHelpWithMultilineText),
         ("testHelpLongFlag", testHelpLongFlag),
         ("testHelpShortFlag", testHelpShortFlag),
         ("testReorderingFlags", testReorderingFlags),
@@ -190,5 +220,5 @@ final class ArgTreeTests: XCTestCase {
         ("testSimpleDemo", testSimpleDemo),
         ("testVarArgsExample", testVarArgsExample),
     ]
-#endif
+    #endif
 }