Markdown tables

Author: eneko

Docs/Reference/MarkdownGenerator/README.md

@@ -10,6 +10,7 @@ Run `sourcedocs` in the repository root to update this documentation.
 - [MarkdownImage](/Docs/Reference/MarkdownGenerator/structs/MarkdownImage.md)
 - [MarkdownLink](/Docs/Reference/MarkdownGenerator/structs/MarkdownLink.md)
 - [MarkdownList](/Docs/Reference/MarkdownGenerator/structs/MarkdownList.md)
+- [MarkdownTable](/Docs/Reference/MarkdownGenerator/structs/MarkdownTable.md)
 
 
 

Docs/Reference/MarkdownGenerator/structs/MarkdownImage.md

@@ -21,11 +21,11 @@ MarkdownImage.Type
 
 Render an HTML image in Markdown format
 
-    MarkdownImage(url: "http://www.enekoalonso.com/media/sourcedocs-header.jpg", altText: "SourceDocs Header").markdown
+    MarkdownImage(url: "http://example.com/image.jpg", altText: "SourceDocs Header").markdown
 
 Would render as:
 
-    ![SourceDocs Header](http://www.enekoalonso.com/media/sourcedocs-header.jpg)
+    ![SourceDocs Header](http://example.com/image.jpg)
 
 --------------------
 

Docs/Reference/MarkdownGenerator/structs/MarkdownLink.md

@@ -21,11 +21,11 @@ MarkdownLink.Type
 
 Render an HTML link in Markdown format
 
-    MarkdownLink(text: "Google", url: "https://www.google.com").markdown
+    MarkdownLink(text: "Google", url: "https://example.com").markdown
 
 Would render as:
 
-    [Google](https://www.google.com)
+    [Google](https://example.com)
 
 --------------------
 

Docs/Reference/MarkdownGenerator/structs/MarkdownTable.md

@@ -0,0 +1,80 @@
+**STRUCT**
+# `MarkdownTable`
+
+**Contents**
+- [Properties](#properties)
+  - `markdown`
+- [Methods](#methods)
+  - `init(headers:data:)`
+
+**Declaration**
+```swift
+public struct MarkdownTable: MarkdownConvertible
+```
+
+**Infered Type**
+```swift
+MarkdownTable.Type
+```
+
+Render a two dimmensional Markdown table.
+
+    |   | Name | Department |
+    | - | ---- | ---------- |
+    | 🍏 | Apple | Fruits |
+    | 🍊 | Orange | Fruits |
+    | 🥖 | Bread | Bakery |
+
+*Notes*:
+- Markdown tables are not supported by all Markdown readers.
+- Table headers are required.
+- Table cells cannot contain multiple lines. New line characters are replaced by a space.
+
+--------------------
+
+## Properties
+### `markdown`
+
+**Declaration**
+```swift
+public var markdown: String
+```
+
+**Infered Type**
+```swift
+String
+```
+
+Generated Markdown output
+
+--------------------
+
+## Methods
+### `init(headers:data:)`
+
+**Declaration**
+```swift
+public init(headers: [String], data: [[String]])
+```
+
+**Infered Type**
+```swift
+(MarkdownTable.Type) -> ([String], [[String]]) -> MarkdownTable
+```
+
+MarkdownTable initializer
+
+- Parameters:
+  - headers: List of table header titles.
+  - data: Two-dimensional `String` array with the table content. Rows are defined by
+       the outer array, columns are defined by the inner arrays.
+
+       An array of rows, each row containing an array of columns. All rows should contain the same
+       number of colums as the headers array, to avoid formatting issues.
+
+#### Parameters
+| Name | Description |
+| ---- | ----------- |
+| `headers` | List of table header titles. |
+| `data` | Two-dimensional `String` array with the table content. Rows are defined by the outer array, columns are defined by the inner arrays.
+An array of rows, each row containing an array of columns. All rows should contain the same number of colums as the headers array, to avoid formatting issues. |

Sources/MarkdownGenerator/MarkdownImage.swift

@@ -9,11 +9,11 @@ import Foundation
 
 /// Render an HTML image in Markdown format
 ///
-///     MarkdownImage(url: "http://www.enekoalonso.com/media/sourcedocs-header.jpg", altText: "SourceDocs Header").markdown
+///     MarkdownImage(url: "http://example.com/image.jpg", altText: "SourceDocs Header").markdown
 ///
 /// Would render as:
 ///
-///     ![SourceDocs Header](http://www.enekoalonso.com/media/sourcedocs-header.jpg)
+///     ![SourceDocs Header](http://example.com/image.jpg)
 ///
 public struct MarkdownImage: MarkdownConvertible {
 

Sources/MarkdownGenerator/MarkdownLink.swift

@@ -9,11 +9,11 @@ import Foundation
 
 /// Render an HTML link in Markdown format
 ///
-///     MarkdownLink(text: "Google", url: "https://www.google.com").markdown
+///     MarkdownLink(text: "Google", url: "https://example.com").markdown
 ///
 /// Would render as:
 ///
-///     [Google](https://www.google.com)
+///     [Google](https://example.com)
 ///
 public struct MarkdownLink: MarkdownConvertible {
 

Sources/MarkdownGenerator/MarkdownTable.swift

@@ -6,3 +6,56 @@
 //
 
 import Foundation
+
+/// Render a two dimmensional Markdown table.
+///
+///     |   | Name | Department |
+///     | - | ---- | ---------- |
+///     | 🍏 | Apple | Fruits |
+///     | 🍊 | Orange | Fruits |
+///     | 🥖 | Bread | Bakery |
+///
+/// *Notes*:
+/// - Markdown tables are not supported by all Markdown readers.
+/// - Table headers are required.
+/// - Table cells cannot contain multiple lines. New line characters are replaced by a space.
+public struct MarkdownTable: MarkdownConvertible {
+
+    let headers: [String]
+    let data: [[String]]
+
+    /// MarkdownTable initializer
+    ///
+    /// - Parameters:
+    ///   - headers: List of table header titles.
+    ///   - data: Two-dimensional `String` array with the table content. Rows are defined by
+    ///        the outer array, columns are defined by the inner arrays.
+    ///
+    ///        An array of rows, each row containing an array of columns. All rows should contain the same
+    ///        number of colums as the headers array, to avoid formatting issues.
+    public init(headers: [String], data: [[String]]) {
+        self.headers = headers.map { $0.isEmpty ? " " : $0 }
+        self.data = data
+    }
+
+    /// Generated Markdown output
+    public var markdown: String {
+        let headerRow = makeRow(values: headers)
+        let separatorRow = makeRow(values: headers.map { Array(repeating: "-", count: $0.count).joined() })
+        let dataRows = data.map { columns in
+            return makeRow(values: columns)
+        }
+        return """
+        \(headerRow)
+        \(separatorRow)
+        \(dataRows.joined(separator: String.newLine))
+        """
+    }
+
+    // Convert a String array into a markdown formatter table row.
+    // Table cells cannot contain multiple lines. New line characters are replaced by a space.
+    private func makeRow(values: [String]) -> String {
+        let values = values.map { $0.replacingOccurrences(of: String.newLine, with: " ") }
+        return "| " + values.joined(separator: " | ") + " |"
+    }
+}

Tests/MarkdownGeneratorTests/MarkdownTableTests.swift

@@ -6,8 +6,59 @@
 //
 
 import XCTest
+import MarkdownGenerator
 
 class MarkdownTableTests: XCTestCase {
 
+    func test1x1Table() {
+        let data: [[String]] = [[]]
+        let table = MarkdownTable(headers: ["Header"], data: data)
+
+        let output = """
+        | Header |
+        | ------ |
+        |  |
+        """
+
+        XCTAssertEqual(table.markdown, output)
+    }
+
+    func test3x3Table() {
+        let data: [[String]] = [
+            ["🍏", "Apple", "Fruits"],
+            ["🍊", "Orange", "Fruits"],
+            ["🥖", "Bread", "Bakery"],
+        ]
+        let table = MarkdownTable(headers: ["", "Name", "Department"], data: data)
+
+        let output = """
+        |   | Name | Department |
+        | - | ---- | ---------- |
+        | 🍏 | Apple | Fruits |
+        | 🍊 | Orange | Fruits |
+        | 🥖 | Bread | Bakery |
+        """
+
+        XCTAssertEqual(table.markdown, output)
+    }
+
+    func testMultilineValues() {
+        let data: [[String]] = [
+            ["Single-line value", "Multi-line\n\nvalue"],
+            ["Single-line value", "Multi-line\n\nvalue"],
+            ["Single-line value", "Multi-line\n\nvalue"],
+        ]
+        let table = MarkdownTable(headers: ["Single-line", "Multi-line"], data: data)
+
+        let output = """
+        | Single-line | Multi-line |
+        | ----------- | ---------- |
+        | Single-line value | Multi-line  value |
+        | Single-line value | Multi-line  value |
+        | Single-line value | Multi-line  value |
+        """
+
+        XCTAssertEqual(table.markdown, output)
+    }
 
 }