Support titles for links and images

Sources/Ink/API/MarkdownParser.swift

@@ -42,7 +42,7 @@ public struct MarkdownParser {
     public func parse(_ markdown: String) -> Markdown {
         var reader = Reader(string: markdown)
         var fragments = [ParsedFragment]()
-        var urlsByName = [String : URL]()
+        var urlsByName = [String : URLDeclaration]()
         var titleHeading: Heading?
         var metadata: Metadata?
 
@@ -60,7 +60,7 @@ public struct MarkdownParser {
 
                 guard reader.currentCharacter != "[" else {
                     let declaration = try URLDeclaration.readOrRewind(using: &reader)
-                    urlsByName[declaration.name] = declaration.url
+                    urlsByName[declaration.name] = declaration
                     continue
                 }
 

Sources/Ink/Internal/Character+Classification.swift

@@ -8,9 +8,31 @@ internal extension Character {
     var isSameLineWhitespace: Bool {
         isWhitespace && !isNewline
     }
+
+    var isLegalInURL: Bool {
+        self != ")" && self != " " && self != "\n"
+    }
+
+    var isSameLineNonWhitespace: Bool {
+        !isWhitespace && !isNewline
+    }
 }
 
 internal extension Set where Element == Character {
     static let boldItalicStyleMarkers: Self = ["*", "_"]
     static let allStyleMarkers: Self = boldItalicStyleMarkers.union(["~"])
 }
+
+internal enum TitleDelimeter: Character {
+    case doubleQuote = "\""
+    case singleQuote = "'"
+    case parenthetical = "("
+    var closing: Character {
+        switch self {
+        case .parenthetical:
+            return ")"
+        default:
+            return self.rawValue
+        }
+    }
+}

Sources/Ink/Internal/Image.swift

@@ -17,13 +17,21 @@ internal struct Image: Fragment {
     func html(usingURLs urls: NamedURLCollection,
               modifiers: ModifierCollection) -> String {
         let url = link.target.url(from: urls)
+        let refTitle = link.target.title(from: urls)
+
+        let finalTitle = refTitle ?? link.title
+        var titleAttribute: String = ""
+        if let finalTitle = finalTitle {
+            titleAttribute = " title=\"\(finalTitle)\""
+        }
+
         var alt = link.text.html(usingURLs: urls, modifiers: modifiers)
 
         if !alt.isEmpty {
             alt = " alt=\"\(alt)\""
         }
 
-        return "<img src=\"\(url)\"\(alt)/>"
+        return "<img src=\"\(url)\"\(alt)\(titleAttribute)/>"
     }
 
     func plainText() -> String {

Sources/Ink/Internal/Link.swift

@@ -9,6 +9,7 @@ internal struct Link: Fragment {
 
     var target: Target
     var text: FormattedText
+    var title: Substring?
 
     static func read(using reader: inout Reader) throws -> Link {
         try reader.read("[")
@@ -19,20 +20,35 @@ internal struct Link: Fragment {
 
         if reader.currentCharacter == "(" {
             reader.advanceIndex()
-            let url = try reader.read(until: ")")
-            return Link(target: .url(url), text: text)
+            let url = try? reader.readCharacters(matching: \.isLegalInURL)
+
+            guard !reader.didReachEnd else { throw Reader.Error() }
+            var titleText: Substring? = nil
+            if reader.currentCharacter.isSameLineWhitespace {
+                try reader.readWhitespaces()
+                try reader.read("\"")
+                titleText = try reader.read(until: "\"")
+            }
+            try reader.read(")")
+            return Link(target: .url(url ?? ""), text: text, title: titleText)
         } else {
             try reader.read("[")
             let reference = try reader.read(until: "]")
-            return Link(target: .reference(reference), text: text)
+            return Link(target: .reference(reference), text: text, title: nil)
         }
     }
 
     func html(usingURLs urls: NamedURLCollection,
               modifiers: ModifierCollection) -> String {
         let url = target.url(from: urls)
-        let title = text.html(usingURLs: urls, modifiers: modifiers)
-        return "<a href=\"\(url)\">\(title)</a>"
+        let refTitle = target.title(from: urls)
+        let linkText = text.html(usingURLs: urls, modifiers: modifiers)
+        let finalTitle = refTitle ?? title
+        var titleAttribute: String = ""
+        if let finalTitle = finalTitle {
+            titleAttribute = " title=\"\(finalTitle)\""
+        }
+        return "<a href=\"\(url)\"\(titleAttribute)>\(linkText)</a>"
     }
 
     func plainText() -> String {
@@ -53,7 +69,16 @@ extension Link.Target {
         case .url(let url):
             return url
         case .reference(let name):
-            return urls.url(named: name) ?? name
+            return urls.url(named: name)?.url ?? name
+        }
+    }
+
+    func title(from urls: NamedURLCollection) -> Substring? {
+        switch self {
+        case .url:
+            return nil
+        case .reference(let name):
+            return urls.url(named: name)?.title
         }
     }
 }

Sources/Ink/Internal/NamedURLCollection.swift

@@ -5,13 +5,13 @@
 */
 
 internal struct NamedURLCollection {
-    private let urlsByName: [String : URL]
+    private let urlsByName: [String : URLDeclaration]
 
-    init(urlsByName: [String : URL]) {
+    init(urlsByName: [String : URLDeclaration]) {
         self.urlsByName = urlsByName
     }
 
-    func url(named name: Substring) -> URL? {
+    func url(named name: Substring) -> URLDeclaration? {
         urlsByName[name.lowercased()]
     }
 }

Sources/Ink/Internal/URLDeclaration.swift

@@ -7,14 +7,35 @@
 internal struct URLDeclaration: Readable {
     var name: String
     var url: URL
+    var title: Substring?
 
     static func read(using reader: inout Reader) throws -> Self {
         try reader.read("[")
         let name = try reader.read(until: "]")
         try reader.read(":")
         try reader.readWhitespaces()
-        let url = reader.readUntilEndOfLine()
 
-        return URLDeclaration(name: name.lowercased(), url: url)
+        var titleText: Substring? = nil
+        let url = try reader.readCharacters(matching: \.isSameLineNonWhitespace)
+
+        if !reader.didReachEnd {
+			if reader.currentCharacter.isNewline {
+				reader.advanceIndex()
+			}
+			if reader.currentCharacter.isSameLineWhitespace {
+				try reader.readWhitespaces()
+			}
+            if let delimeter = TitleDelimeter(rawValue: reader.currentCharacter) {
+                let index = reader.currentIndex
+                reader.advanceIndex()
+                titleText = try reader.read(until: delimeter.closing)
+                reader.discardWhitespaces()
+                if !reader.didReachEnd && !reader.currentCharacter.isWhitespace {
+                    reader.moveToIndex(index)
+                    titleText = nil
+                }
+            }
+        }
+        return URLDeclaration(name: name.lowercased(), url: url, title: titleText)
     }
 }

Tests/InkTests/ImageTests.swift

@@ -27,6 +27,11 @@ final class ImageTests: XCTestCase {
         XCTAssertEqual(html, #"<img src="url" alt="Alt text"/>"#)
     }
 
+    func testImageWithURLAndAltTextAndTitle() {
+        let html = MarkdownParser().html(from: "![Alt text](url \"Swift by Sundell\")")
+        XCTAssertEqual(html, #"<img src="url" alt="Alt text" title="Swift by Sundell"/>"#)
+    }
+
     func testImageWithReferenceAndAltText() {
         let html = MarkdownParser().html(from: """
         ![Alt text][url]
@@ -36,6 +41,25 @@ final class ImageTests: XCTestCase {
         XCTAssertEqual(html, #"<img src="swiftbysundell.com" alt="Alt text"/>"#)
     }
 
+    func testImageWithReferenceAndAltTextAndTitle() {
+        let html = MarkdownParser().html(from: """
+        ![Alt text][url]
+        [url]: swiftbysundell.com    'Swift by Sundell'
+        """)
+
+        XCTAssertEqual(html, #"<img src="swiftbysundell.com" alt="Alt text" title="Swift by Sundell"/>"#)
+    }
+
+    func testImageWithReferenceAndAltTextAndNewlineTitle() {
+        let html = MarkdownParser().html(from: """
+        ![Alt text][url]
+        [url]: swiftbysundell.com
+              (Swift by Sundell)
+        """)
+
+        XCTAssertEqual(html, #"<img src="swiftbysundell.com" alt="Alt text" title="Swift by Sundell"/>"#)
+    }
+
     func testImageWithinParagraph() {
         let html = MarkdownParser().html(from: "Text ![](url) text")
         XCTAssertEqual(html, #"<p>Text <img src="url"/> text</p>"#)
@@ -48,7 +72,10 @@ extension ImageTests {
             ("testImageWithURL", testImageWithURL),
             ("testImageWithReference", testImageWithReference),
             ("testImageWithURLAndAltText", testImageWithURLAndAltText),
+            ("testImageWithURLAndAltTextAndTitle", testImageWithURLAndAltTextAndTitle),
             ("testImageWithReferenceAndAltText", testImageWithReferenceAndAltText),
+            ("testImageWithReferenceAndAltTextAndTitle", testImageWithReferenceAndAltTextAndTitle),
+            ("testImageWithReferenceAndAltTextAndNewlineTitle", testImageWithReferenceAndAltTextAndNewlineTitle),
             ("testImageWithinParagraph", testImageWithinParagraph)
         ]
     }

Tests/InkTests/LinkTests.swift

@@ -13,6 +13,17 @@ final class LinkTests: XCTestCase {
         XCTAssertEqual(html, #"<p><a href="url">Title</a></p>"#)
     }
 
+    func testLinkWithURLAndTitle() {
+        let html = MarkdownParser().html(from: "[Title](url \"Swift by Sundell\")")
+        XCTAssertEqual(html, #"<p><a href="url" title="Swift by Sundell">Title</a></p>"#)
+    }
+
+    func testLinkWithoutURLAndTitle() {
+        let html = MarkdownParser().html(from: "[link]()")
+
+        XCTAssertEqual(html, #"<p><a href="">link</a></p>"#)
+    }
+
     func testLinkWithReference() {
         let html = MarkdownParser().html(from: """
         [Title][url]
@@ -23,6 +34,47 @@ final class LinkTests: XCTestCase {
         XCTAssertEqual(html, #"<p><a href="swiftbysundell.com">Title</a></p>"#)
     }
 
+    func testLinkWithReferenceAndDoubleQuoteTitle() {
+        let html = MarkdownParser().html(from: """
+        [Title][url]
+
+        [url]: swiftbysundell.com "Powered by Publish"
+        """)
+
+        XCTAssertEqual(html, #"<p><a href="swiftbysundell.com" title="Powered by Publish">Title</a></p>"#)
+    }
+
+    func testLinkWithReferenceAndSingleQuoteTitle() {
+        let html = MarkdownParser().html(from: """
+        [Title][url]
+
+        [url]: swiftbysundell.com  'Powered by Publish'
+        """)
+
+        XCTAssertEqual(html, #"<p><a href="swiftbysundell.com" title="Powered by Publish">Title</a></p>"#)
+    }
+
+    func testLinkWithReferenceAndParentheticalTitle() {
+        let html = MarkdownParser().html(from: """
+        [Title][url]
+
+        [url]: swiftbysundell.com (Powered by Publish)
+        """)
+
+        XCTAssertEqual(html, #"<p><a href="swiftbysundell.com" title="Powered by Publish">Title</a></p>"#)
+    }
+
+    func testLinkWithReferenceAndNewlineTitle() {
+        let html = MarkdownParser().html(from: """
+        [Title][url]
+
+        [url]: swiftbysundell.com
+                      'Powered by Publish'
+        """)
+
+        XCTAssertEqual(html, #"<p><a href="swiftbysundell.com" title="Powered by Publish">Title</a></p>"#)
+    }
+
     func testCaseMismatchedLinkWithReference() {
         let html = MarkdownParser().html(from: """
         [Title][Foo]
@@ -64,25 +116,62 @@ final class LinkTests: XCTestCase {
         let html = MarkdownParser().html(from: "[Hello]")
         XCTAssertEqual(html, "<p>[Hello]</p>")
     }
-    
+
     func testLinkWithEscapedSquareBrackets() {
         let html = MarkdownParser().html(from: "[\\[Hello\\]](hello)")
         XCTAssertEqual(html, #"<p><a href="hello">[Hello]</a></p>"#)
     }
+
+    func testLinkDestinationCannotIncludeLinkBreaks() {
+        let html = MarkdownParser().html(from: """
+        [link](foo
+        bar)
+        """)
+
+        XCTAssertEqual(html, #"<p>[link](foo bar)</p>"#)
+    }
+
+    func testLinkReferenceTitleMustEndLine() {
+        let html = MarkdownParser().html(from: """
+        [foo]: /url
+        "title" ok
+        """)
+
+        XCTAssertEqual(html, #"<p>"title" ok</p>"#)
+    }
+
+    func testInlineLinkHasPrecedenceOverReferenceLink() {
+        let html = MarkdownParser().html(from: """
+        [foo]()
+
+        [foo]: /url1
+        """)
+
+        XCTAssertEqual(html, #"<p><a href="">foo</a></p>"#)
+    }
 }
 
 extension LinkTests {
     static var allTests: Linux.TestList<LinkTests> {
         return [
             ("testLinkWithURL", testLinkWithURL),
+            ("testLinkWithURLAndTitle", testLinkWithURLAndTitle),
+            ("testLinkWithoutURLAndTitle", testLinkWithoutURLAndTitle),
             ("testLinkWithReference", testLinkWithReference),
+            ("testLinkWithReferenceAndDoubleQuoteTitle", testLinkWithReferenceAndDoubleQuoteTitle),
+            ("testLinkWithReferenceAndSingleQuoteTitle", testLinkWithReferenceAndSingleQuoteTitle),
+            ("testLinkWithReferenceAndParentheticalTitle", testLinkWithReferenceAndParentheticalTitle),
+            ("testLinkWithReferenceAndNewlineTitle", testLinkWithReferenceAndNewlineTitle),
             ("testCaseMismatchedLinkWithReference", testCaseMismatchedLinkWithReference),
             ("testNumericLinkWithReference", testNumericLinkWithReference),
             ("testBoldLinkWithInternalMarkers", testBoldLinkWithInternalMarkers),
             ("testBoldLinkWithExternalMarkers", testBoldLinkWithExternalMarkers),
             ("testLinkWithUnderscores", testLinkWithUnderscores),
             ("testUnterminatedLink", testUnterminatedLink),
-            ("testLinkWithEscapedSquareBrackets", testLinkWithEscapedSquareBrackets)
+            ("testLinkWithEscapedSquareBrackets", testLinkWithEscapedSquareBrackets),
+            ("testLinkDestinationCannotIncludeLinkBreaks", testLinkDestinationCannotIncludeLinkBreaks),
+            ("testLinkReferenceTitleMustEndLine", testLinkReferenceTitleMustEndLine),
+            ("testInlineLinkHasPrecedenceOverReferenceLink", testInlineLinkHasPrecedenceOverReferenceLink)
         ]
     }
 }