Markdown: Add title property (#28)

This change adds a `title` property to the `Markdown` struct, which when
accessed is lazily evaluated to compute a plain text version of the first
top-level heading (H1) found in the Markdown text.

To make this happen, a `PlainTextConvertible` protocol is introduced,
which is also made a requirement of `Fragment`. A best effort is made
to convert each fragment into a reasonable plain text representation,
even if many of them will never be used as the implementation currently
stands (for example, lists can’t be placed inside headings). It still
felt worth it to do a proper implementation in case we ever make this
a public API for some reason.

This lets tools built on top of Ink extract a title for the parsed Markdown
document without doing additional string parsing.

Author: JohnSundell

.gitignore

@@ -1,4 +1,5 @@
 .DS_Store
+/build
 /.build
 /.swiftpm
 /*.xcodeproj

Sources/Ink/API/Markdown.swift

@@ -15,7 +15,45 @@ public struct Markdown {
     /// The HTML representation of the Markdown, ready to
     /// be rendered in a web browser.
     public var html: String
+    /// The inferred title of the document, from any top-level
+    /// heading found when parsing. If the Markdown text contained
+    /// two top-level headings, then this property will contain
+    /// the first one. Note that this property does not take modifiers
+    /// into acccount.
+    public var title: String? {
+        get { makeTitle() }
+        set { overrideTitle(with: newValue) }
+    }
     /// Any metadata values found at the top of the Markdown
     /// document. See this project's README for more information.
     public var metadata: [String : String]
+
+    private let titleHeading: Heading?
+    private var titleStorage = TitleStorage()
+
+    internal init(html: String,
+                  titleHeading: Heading?,
+                  metadata: [String : String]) {
+        self.html = html
+        self.titleHeading = titleHeading
+        self.metadata = metadata
+    }
+}
+
+private extension Markdown {
+    final class TitleStorage {
+        var title: String?
+    }
+
+    mutating func overrideTitle(with title: String?) {
+        let storage = TitleStorage()
+        storage.title = title
+        titleStorage = storage
+    }
+
+    func makeTitle() -> String? {
+        if let stored = titleStorage.title { return stored }
+        titleStorage.title = titleHeading?.plainText()
+        return titleStorage.title
+    }
 }

Sources/Ink/API/MarkdownParser.swift

@@ -43,6 +43,7 @@ public struct MarkdownParser {
         var reader = Reader(string: markdown)
         var fragments = [ParsedFragment]()
         var urlsByName = [String : URL]()
+        var titleHeading: Heading?
         var metadata: Metadata?
 
         while !reader.didReachEnd {
@@ -68,6 +69,12 @@ public struct MarkdownParser {
 
                 let fragment = try makeFragment(using: type.readOrRewind, reader: &reader)
                 fragments.append(fragment)
+
+                if titleHeading == nil, let heading = fragment.fragment as? Heading {
+                    if heading.level == 1 {
+                        titleHeading = heading
+                    }
+                }
             } catch {
                 let paragraph = makeFragment(using: Paragraph.read, reader: &reader)
                 fragments.append(paragraph)
@@ -88,6 +95,7 @@ public struct MarkdownParser {
 
         return Markdown(
             html: html,
+            titleHeading: titleHeading,
             metadata: metadata?.values ?? [:]
         )
     }

Sources/Ink/Internal/Blockquote.swift

@@ -36,4 +36,8 @@ internal struct Blockquote: Fragment {
         let body = text.html(usingURLs: urls, modifiers: modifiers)
         return "<blockquote><p>\(body)</p></blockquote>"
     }
+
+    func plainText() -> String {
+        text.plainText()
+    }
 }

Sources/Ink/Internal/CodeBlock.swift

@@ -52,4 +52,8 @@ internal struct CodeBlock: Fragment {
         let languageClass = language.isEmpty ? "" : " class=\"language-\(language)\""
         return "<pre><code\(languageClass)>\(code)</code></pre>"
     }
+
+    func plainText() -> String {
+        code
+    }
 }

Sources/Ink/Internal/FormattedText.swift

@@ -4,7 +4,7 @@
 *  MIT license, see LICENSE file for details
 */
 
-internal struct FormattedText: Readable, HTMLConvertible {
+internal struct FormattedText: Readable, HTMLConvertible, PlainTextConvertible {
     private var components = [Component]()
 
     static func read(using reader: inout Reader) -> Self {
@@ -27,7 +27,7 @@ internal struct FormattedText: Readable, HTMLConvertible {
 
     func html(usingURLs urls: NamedURLCollection,
               modifiers: ModifierCollection) -> String {
-        return components.reduce(into: "") { string, component in
+        components.reduce(into: "") { string, component in
             switch component {
             case .linebreak:
                 string.append("<br>")
@@ -48,6 +48,21 @@ internal struct FormattedText: Readable, HTMLConvertible {
         }
     }
 
+    func plainText() -> String {
+        components.reduce(into: "") { string, component in
+            switch component {
+            case .linebreak:
+                string.append("\n")
+            case .text(let text):
+                string.append(String(text))
+            case .styleMarker:
+                break
+            case .fragment(let fragment, _):
+                string.append(fragment.plainText())
+            }
+        }
+    }
+
     mutating func append(_ text: FormattedText, separator: Substring = "") {
         let separator = separator.isEmpty ? [] : [Component.text(separator)]
         components += separator + text.components

Sources/Ink/Internal/Fragment.swift

@@ -4,4 +4,4 @@
 *  MIT license, see LICENSE file for details
 */
 
-internal typealias Fragment = Readable & Modifiable & HTMLConvertible
+internal typealias Fragment = Readable & Modifiable & HTMLConvertible & PlainTextConvertible

Sources/Ink/Internal/HTML.swift

@@ -53,7 +53,13 @@ internal struct HTML: Fragment {
 
     func html(usingURLs urls: NamedURLCollection,
               modifiers: ModifierCollection) -> String {
-        return String(string)
+        String(string)
+    }
+
+    func plainText() -> String {
+        // Since we want to strip all HTML from plain text output,
+        // there is nothing to return here, just an empty string.
+        ""
     }
 }
 

Sources/Ink/Internal/Heading.swift

@@ -6,8 +6,8 @@
 
 internal struct Heading: Fragment {
     var modifierTarget: Modifier.Target { .headings }
+    var level: Int
 
-    private var level: Int
     private var text: FormattedText
 
     static func read(using reader: inout Reader) throws -> Heading {
@@ -21,22 +21,34 @@ internal struct Heading: Fragment {
 
     func html(usingURLs urls: NamedURLCollection,
               modifiers: ModifierCollection) -> String {
-        var body = text.html(usingURLs: urls, modifiers: modifiers)
+        let body = stripTrailingMarkers(
+            from: text.html(usingURLs: urls, modifiers: modifiers)
+        )
 
-        if !body.isEmpty {
-            let lastCharacterIndex = body.index(before: body.endIndex)
-            var trimIndex = lastCharacterIndex
+        let tagName = "h\(level)"
+        return "<\(tagName)>\(body)</\(tagName)>"
+    }
+
+    func plainText() -> String {
+        stripTrailingMarkers(from: text.plainText())
+    }
+}
 
-            while body[trimIndex] == "#", trimIndex != body.startIndex {
-                trimIndex = body.index(before: trimIndex)
-            }
+private extension Heading {
+    func stripTrailingMarkers(from text: String) -> String {
+        guard !text.isEmpty else { return text }
 
-            if trimIndex != lastCharacterIndex {
-                body = String(body[..<trimIndex])
-            }
+        let lastCharacterIndex = text.index(before: text.endIndex)
+        var trimIndex = lastCharacterIndex
+
+        while text[trimIndex] == "#", trimIndex != text.startIndex {
+            trimIndex = text.index(before: trimIndex)
         }
 
-        let tagName = "h\(level)"
-        return "<\(tagName)>\(body)</\(tagName)>"
+        if trimIndex != lastCharacterIndex {
+            return String(text[..<trimIndex])
+        }
+
+        return text
     }
 }

Sources/Ink/Internal/HorizontalLine.swift

@@ -19,6 +19,12 @@ internal struct HorizontalLine: Fragment {
 
     func html(usingURLs urls: NamedURLCollection,
               modifiers: ModifierCollection) -> String {
-        return "<hr>"
+        "<hr>"
+    }
+
+    func plainText() -> String {
+        // Since we want to strip all HTML from plain text output,
+        // there is nothing to return here, just an empty string.
+        ""
     }
 }