Implemented support for Markdown tables. Made it easier to extend class MarkdownParser. Included ExtendedMarkdownParser.

Author: objecthub

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 1.0 (2020-07-18)
+- Implemented support for Markdown tables
+- Made it easier to extend class `MarkdownParser`
+- Included extended markdown parser `ExtendedMarkdownParser`
+
 ## 0.2.2 (2020-01-26)
 - Fixed bug in AttributedStringGenerator.swift
 - Migrated project to Xcode 11.3.1

MarkdownKit.xcodeproj/project.pbxproj

@@ -10,6 +10,9 @@
 		CC088C0B22DB74090059460E /* TextFragment.swift in Sources */ = {isa = PBXBuildFile; fileRef = CC088C0A22DB74090059460E /* TextFragment.swift */; };
 		CC088C0F22DD2BCD0059460E /* HtmlGenerator.swift in Sources */ = {isa = PBXBuildFile; fileRef = CC088C0E22DD2BCD0059460E /* HtmlGenerator.swift */; };
 		CC088C2422E337BD0059460E /* MarkdownHtmlTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = CC088C2322E337BD0059460E /* MarkdownHtmlTests.swift */; };
+		CC24757324C1EBB600678C59 /* ExtendedMarkdownBlockTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = CC24757224C1EBB600678C59 /* ExtendedMarkdownBlockTests.swift */; };
+		CC24757524C1EC3600678C59 /* TableParser.swift in Sources */ = {isa = PBXBuildFile; fileRef = CC24757424C1EC3600678C59 /* TableParser.swift */; };
+		CC24757724C1ED7E00678C59 /* ExtendedMarkdownParser.swift in Sources */ = {isa = PBXBuildFile; fileRef = CC24757624C1ED7E00678C59 /* ExtendedMarkdownParser.swift */; };
 		CC2AF6F2227CD98100BEA420 /* MarkdownKit.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = CC2AF6E8227CD98100BEA420 /* MarkdownKit.framework */; };
 		CC2AF6F7227CD98100BEA420 /* MarkdownBlockTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = CC2AF6F6227CD98100BEA420 /* MarkdownBlockTests.swift */; };
 		CC2AF6F9227CD98100BEA420 /* MarkdownKit.h in Headers */ = {isa = PBXBuildFile; fileRef = CC2AF6EB227CD98100BEA420 /* MarkdownKit.h */; settings = {ATTRIBUTES = (Public, ); }; };
@@ -31,6 +34,7 @@
 		CC8CBC21228730800084683B /* LinkRefDefinitionParser.swift in Sources */ = {isa = PBXBuildFile; fileRef = CC8CBC20228730800084683B /* LinkRefDefinitionParser.swift */; };
 		CC8CBC2322884F940084683B /* SetextHeadingParser.swift in Sources */ = {isa = PBXBuildFile; fileRef = CC8CBC2222884F940084683B /* SetextHeadingParser.swift */; };
 		CC8CBC25228898B00084683B /* HtmlBlockParser.swift in Sources */ = {isa = PBXBuildFile; fileRef = CC8CBC24228898B00084683B /* HtmlBlockParser.swift */; };
+		CC8D559D24C3560700E11F96 /* ExtendedMarkdownHtmlTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = CC8D559C24C3560700E11F96 /* ExtendedMarkdownHtmlTests.swift */; };
 		CCB033CF227CDB2F00E1C4DC /* MarkdownParser.swift in Sources */ = {isa = PBXBuildFile; fileRef = CCB033C7227CDB2F00E1C4DC /* MarkdownParser.swift */; };
 		CCB033D0227CDB2F00E1C4DC /* AtxHeadingParser.swift in Sources */ = {isa = PBXBuildFile; fileRef = CCB033C8227CDB2F00E1C4DC /* AtxHeadingParser.swift */; };
 		CCB033D1227CDB2F00E1C4DC /* CodeBlockParser.swift in Sources */ = {isa = PBXBuildFile; fileRef = CCB033C9227CDB2F00E1C4DC /* CodeBlockParser.swift */; };
@@ -73,6 +77,9 @@
 		CC0DFBE022FDC617002ACD37 /* Package.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = Package.swift; sourceTree = "<group>"; };
 		CC0DFBE222FDCCE0002ACD37 /* CONTRIBUTING.md */ = {isa = PBXFileReference; lastKnownFileType = net.daringfireball.markdown; path = CONTRIBUTING.md; sourceTree = "<group>"; };
 		CC0DFBE322FDCD5F002ACD37 /* CHANGELOG.md */ = {isa = PBXFileReference; lastKnownFileType = net.daringfireball.markdown; path = CHANGELOG.md; sourceTree = "<group>"; };
+		CC24757224C1EBB600678C59 /* ExtendedMarkdownBlockTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ExtendedMarkdownBlockTests.swift; sourceTree = "<group>"; };
+		CC24757424C1EC3600678C59 /* TableParser.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = TableParser.swift; sourceTree = "<group>"; };
+		CC24757624C1ED7E00678C59 /* ExtendedMarkdownParser.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = ExtendedMarkdownParser.swift; sourceTree = "<group>"; };
 		CC2AF6E8227CD98100BEA420 /* MarkdownKit.framework */ = {isa = PBXFileReference; explicitFileType = wrapper.framework; includeInIndex = 0; path = MarkdownKit.framework; sourceTree = BUILT_PRODUCTS_DIR; };
 		CC2AF6EB227CD98100BEA420 /* MarkdownKit.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = MarkdownKit.h; sourceTree = "<group>"; };
 		CC2AF6EC227CD98100BEA420 /* Info.plist */ = {isa = PBXFileReference; lastKnownFileType = text.plist.xml; path = Info.plist; sourceTree = "<group>"; };
@@ -98,8 +105,9 @@
 		CC8CBC182284B3F40084683B /* MarkdownFactory.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = MarkdownFactory.swift; sourceTree = "<group>"; };
 		CC8CBC1E2286CED60084683B /* Blocks.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = Blocks.swift; sourceTree = "<group>"; };
 		CC8CBC20228730800084683B /* LinkRefDefinitionParser.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = LinkRefDefinitionParser.swift; sourceTree = "<group>"; };
-		CC8CBC2222884F940084683B /* SetextHeadingParser.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = SetextHeadingParser.swift; sourceTree = "<group>"; };
+		CC8CBC2222884F940084683B /* SetextHeadingParser.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = SetextHeadingParser.swift; sourceTree = "<group>"; };
 		CC8CBC24228898B00084683B /* HtmlBlockParser.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = HtmlBlockParser.swift; sourceTree = "<group>"; };
+		CC8D559C24C3560700E11F96 /* ExtendedMarkdownHtmlTests.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = ExtendedMarkdownHtmlTests.swift; sourceTree = "<group>"; };
 		CCB033C7227CDB2F00E1C4DC /* MarkdownParser.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = MarkdownParser.swift; sourceTree = "<group>"; };
 		CCB033C8227CDB2F00E1C4DC /* AtxHeadingParser.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = AtxHeadingParser.swift; sourceTree = "<group>"; };
 		CCB033C9227CDB2F00E1C4DC /* CodeBlockParser.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = CodeBlockParser.swift; sourceTree = "<group>"; };
@@ -206,8 +214,10 @@
 			children = (
 				CC8CBC182284B3F40084683B /* MarkdownFactory.swift */,
 				CC2AF6F6227CD98100BEA420 /* MarkdownBlockTests.swift */,
+				CC24757224C1EBB600678C59 /* ExtendedMarkdownBlockTests.swift */,
 				CC7B603822AC67DC0092188C /* MarkdownInlineTests.swift */,
 				CC088C2322E337BD0059460E /* MarkdownHtmlTests.swift */,
+				CC8D559C24C3560700E11F96 /* ExtendedMarkdownHtmlTests.swift */,
 				CC2AF6F8227CD98100BEA420 /* Info.plist */,
 			);
 			name = MarkdownKitTests;
@@ -234,11 +244,13 @@
 			isa = PBXGroup;
 			children = (
 				CCB033C7227CDB2F00E1C4DC /* MarkdownParser.swift */,
+				CC24757624C1ED7E00678C59 /* ExtendedMarkdownParser.swift */,
 				CCB033CE227CDB2F00E1C4DC /* DocumentParser.swift */,
 				CCB033CA227CDB2F00E1C4DC /* BlockParser.swift */,
 				CCB033CD227CDB2F00E1C4DC /* Container.swift */,
 				CCB033C8227CDB2F00E1C4DC /* AtxHeadingParser.swift */,
 				CC8CBC2222884F940084683B /* SetextHeadingParser.swift */,
+				CC24757424C1EC3600678C59 /* TableParser.swift */,
 				CCB033CB227CDB2F00E1C4DC /* ThematicBreakParser.swift */,
 				CCB033C9227CDB2F00E1C4DC /* CodeBlockParser.swift */,
 				CC8CBC24228898B00084683B /* HtmlBlockParser.swift */,
@@ -393,8 +405,10 @@
 				CC8CBC17227F39C00084683B /* ListItemParser.swift in Sources */,
 				CCB033D2227CDB2F00E1C4DC /* BlockParser.swift in Sources */,
 				CC6D239822C03CBA00BB1302 /* LinkTransformer.swift in Sources */,
+				CC24757524C1EC3600678C59 /* TableParser.swift in Sources */,
 				CCB033CF227CDB2F00E1C4DC /* MarkdownParser.swift in Sources */,
 				CCB033D3227CDB2F00E1C4DC /* ThematicBreakParser.swift in Sources */,
+				CC24757724C1ED7E00678C59 /* ExtendedMarkdownParser.swift in Sources */,
 				CCB033D6227CDB2F00E1C4DC /* DocumentParser.swift in Sources */,
 				CCD07466229FDFB90053B73C /* InlineParser.swift in Sources */,
 				CCB033D4227CDB2F00E1C4DC /* Block.swift in Sources */,
@@ -423,8 +437,10 @@
 			buildActionMask = 2147483647;
 			files = (
 				CC7B603922AC67DC0092188C /* MarkdownInlineTests.swift in Sources */,
+				CC24757324C1EBB600678C59 /* ExtendedMarkdownBlockTests.swift in Sources */,
 				CC088C2422E337BD0059460E /* MarkdownHtmlTests.swift in Sources */,
 				CC2AF6F7227CD98100BEA420 /* MarkdownBlockTests.swift in Sources */,
+				CC8D559D24C3560700E11F96 /* ExtendedMarkdownHtmlTests.swift in Sources */,
 				CC8CBC192284B3F40084683B /* MarkdownFactory.swift in Sources */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;
@@ -591,7 +607,7 @@
 					"@executable_path/../Frameworks",
 					"@loader_path/Frameworks",
 				);
-				MARKETING_VERSION = 0.2.2;
+				MARKETING_VERSION = 1.0;
 				PRODUCT_BUNDLE_IDENTIFIER = net.objecthub.MarkdownKit;
 				PRODUCT_NAME = "$(TARGET_NAME:c99extidentifier)";
 				SKIP_INSTALL = YES;
@@ -620,7 +636,7 @@
 					"@executable_path/../Frameworks",
 					"@loader_path/Frameworks",
 				);
-				MARKETING_VERSION = 0.2.2;
+				MARKETING_VERSION = 1.0;
 				PRODUCT_BUNDLE_IDENTIFIER = net.objecthub.MarkdownKit;
 				PRODUCT_NAME = "$(TARGET_NAME:c99extidentifier)";
 				SKIP_INSTALL = YES;

README.md

@@ -11,6 +11,7 @@
 
 _Swift MarkdownKit_ is a framework for parsing text in [Markdown](https://daringfireball.net/projects/markdown/)
 format. The supported syntax is based on the [CommonMark Markdown specification](https://commonmark.org).
+_Swift MarkdownKit_ also provides an extended version of the parser that is able to handle Markdown tables.
 
 _Swift MarkdownKit_ defines an abstract syntax for Markdown, it provides a parser for parsing strings into
 abstract syntax trees, and comes with generators for creating HTML and
@@ -59,6 +60,20 @@ is yet another recursively defined enumeration with associated values. The examp
 contains a `Text`  object, i.e. it encapsulates a sequence of `TextFragment` values which are
 "marked up strongly".
 
+Class `ExtendedMarkdownParser` has the same interface like `MarkdownParser` but supports table blocks in
+addition to the block types defined by the [CommonMark specification](https://commonmark.org).
+[Tables](https://github.github.com/gfm/#tables-extension-) are based on the
+[GitHub Flavored Markdown specification](https://github.github.com/gfm/) with one extension: within a table
+block it is possible to escape newline characters to enable cell text to be written on multiple lines. Here is an example:
+
+```markdown
+| Column 1     | Column 2       |
+| ------------ | -------------- |
+| This text \
+  is very long | More cell text |
+| Last line    | Last cell      |        
+```
+
 ### Configuring the Markdown parser
 
 The Markdown dialect supported by `MarkdownParser` is defined by two parameters: a sequence of
@@ -74,6 +89,28 @@ Since `MarkdownParser` objects are stateless (beyond the configuration of block
 transformers), there is a predefined default `MarkdownParser` object accessible via the static property
 `MarkdownParser.standard`. This default parsing object is used in the example above.
 
+New markdown parsers with different configurations can also be created by subclassing `MarkdownParser`
+and by overriding the class properties `defaultBlockParsers` and `defaultInlineTransformers`. Here is
+an example how class `ExtendedMarkdownParser` is derived from `MarkdownParser` simply by overriding
+`defaultBlockParsers` and by specializing `standard` in a covariant fashion.
+
+```swift
+open class ExtendedMarkdownParser: MarkdownParser {
+  override open class var defaultBlockParsers: [BlockParser.Type] {
+    return Self.blockParsers
+  }
+  private static let blockParsers: [BlockParser.Type] = {
+    var parsers = MarkdownParser.defaultBlockParsers
+    parsers.append(TableParser.self)
+    return parsers
+  }()
+  override open class var standard: ExtendedMarkdownParser {
+    return self.singleton
+  }
+  private static let singleton: ExtendedMarkdownParser = ExtendedMarkdownParser()
+}
+```
+
 ### Processing Markdown
 
 The usage of abstract syntax trees for representing Markdown text has the advantage that it is very easy to

Sources/MarkdownKit/Block.swift

@@ -3,7 +3,7 @@
 //  MarkdownKit
 //
 //  Created by Matthias Zenger on 25/04/2019.
-//  Copyright © 2019 Google LLC.
+//  Copyright © 2019-2020 Google LLC.
 //
 //  Licensed under the Apache License, Version 2.0 (the "License");
 //  you may not use this file except in compliance with the License.
@@ -37,6 +37,7 @@ public enum Block: Equatable, CustomStringConvertible, CustomDebugStringConverti
   case htmlBlock(Lines)
   case referenceDef(String, Substring, Lines)
   case thematicBreak
+  case table(Row, Alignments, Rows)
 
   /// Returns a description of the block as a string.
   public var description: String {
@@ -107,9 +108,18 @@ public enum Block: Equatable, CustomStringConvertible, CustomDebugStringConverti
         }
       case .thematicBreak:
         return "thematicBreak"
+      case .table(let header, let align, let rows):
+        var res = self.string(from: header) + ", "
+        for a in align {
+          res += a.description
+        }
+        for row in rows {
+          res += ", " + self.string(from: row)
+        }
+        return "table(\(res))"
     }
   }
-
+  
   /// Returns a debug description.
   public var debugDescription: String {
     return self.description
@@ -126,7 +136,19 @@ public enum Block: Equatable, CustomStringConvertible, CustomDebugStringConverti
     }
     return res
   }
-
+  
+  private func string(from row: Row) -> String {
+    var res = "row("
+    for cell in row {
+      if res.isEmpty {
+        res = cell.description
+      } else {
+        res = res + " | " + cell.description
+      }
+    }
+    return res + ")"
+  }
+  
   /// Defines an equality relation for two blocks.
   public static func == (lhs: Block, rhs: Block) -> Bool {
     switch (lhs, rhs) {
@@ -152,6 +174,8 @@ public enum Block: Equatable, CustomStringConvertible, CustomDebugStringConverti
         return llab == rlab && ldest == rdest && lt == rt
       case (.thematicBreak, .thematicBreak):
         return true
+      case (.table(let lheader, let lalign, let lrows), .table(let rheader, let ralign, let rrows)):
+        return lheader == rheader && lalign == ralign && lrows == rrows
       default:
         return false
     }
@@ -198,3 +222,38 @@ public enum ListType: Equatable, CustomStringConvertible, CustomDebugStringConve
     return self.description
   }
 }
+
+///
+/// Rows are arrays of text.
+///
+public typealias Row = ContiguousArray<Text>
+public typealias Rows = ContiguousArray<Row>
+
+///
+/// Column alignments are represented as arrays of `Alignment` enum values
+/// 
+public enum Alignment: UInt, CustomStringConvertible, CustomDebugStringConvertible {
+  case undefined = 0
+  case left = 1
+  case right = 2
+  case center = 3
+  
+  public var description: String {
+    switch self {
+      case .undefined:
+        return "-"
+      case .left:
+        return "L"
+      case .right:
+        return "R"
+      case .center:
+        return "C"
+    }
+  }
+  
+  public var debugDescription: String {
+    return self.description
+  }
+}
+
+public typealias Alignments = ContiguousArray<Alignment>

Sources/MarkdownKit/HTML/HtmlGenerator.swift

@@ -3,7 +3,7 @@
 //  MarkdownKit
 //
 //  Created by Matthias Zenger on 15/07/2019.
-//  Copyright © 2019 Google LLC.
+//  Copyright © 2019-2020 Google LLC.
 //
 //  Licensed under the Apache License, Version 2.0 (the "License");
 //  you may not use this file except in compliance with the License.
@@ -89,6 +89,38 @@ open class HtmlGenerator {
         return ""
       case .thematicBreak:
         return "<hr />\n"
+      case .table(let header, let align, let rows):
+        var tagsuffix: [String] = []
+        for a in align {
+          switch a {
+            case .undefined:
+              tagsuffix.append(">")
+            case .left:
+              tagsuffix.append(" align=\"left\">")
+            case .right:
+              tagsuffix.append(" align=\"right\">")
+            case .center:
+              tagsuffix.append(" align=\"center\">")
+          }
+        }
+        var html = "<table><thead><tr>\n"
+        var i = 0
+        for head in header {
+          html += "<th\(tagsuffix[i])\(self.generate(text: head))</th>"
+          i += 1
+        }
+        html += "\n</tr></thead><tbody>\n"
+        for row in rows {
+          html += "<tr>"
+          i = 0
+          for cell in row {
+            html += "<td\(tagsuffix[i])\(self.generate(text: cell))</td>"
+            i += 1
+          }
+          html += "</tr>\n"
+        }
+        html += "</tbody></table>\n"
+        return html
     }
   }
 

Sources/MarkdownKit/Info.plist

@@ -15,7 +15,7 @@
 	<key>CFBundlePackageType</key>
 	<string>FMWK</string>
 	<key>CFBundleShortVersionString</key>
-	<string>0.2.2</string>
+	<string>1.0</string>
 	<key>CFBundleVersion</key>
 	<string>$(CURRENT_PROJECT_VERSION)</string>
 	<key>NSHumanReadableCopyright</key>

Sources/MarkdownKit/Parser/DocumentParser.swift

@@ -3,7 +3,7 @@
 //  MarkdownKit
 //
 //  Created by Matthias Zenger on 20/04/2019.
-//  Copyright © 2019 Google LLC.
+//  Copyright © 2019-2020 Google LLC.
 //
 //  Licensed under the Apache License, Version 2.0 (the "License");
 //  you may not use this file except in compliance with the License.
@@ -28,7 +28,7 @@ import Foundation
 public class DocumentParser {
 
   /// Sequence of block parsers which implement the document parsing functionality.
-  private var blockParsers: [BlockParser]
+  internal private(set) var blockParsers: [BlockParser]
 
   /// The input string which gets parsed.
   private let input: String