implement plain text markdown rendering target

Author: tayloraswift

Sources/MarkdownRendering/HTML.AttributeEncoder (ext).swift renamed to Sources/MarkdownRendering/HTML/HTML.AttributeEncoder (ext).swift

@@ -4,7 +4,8 @@ import MarkdownABI
 extension HTML.ContentEncoder
 {
     mutating
-    func emit(element:MarkdownBytecode.Emission, with attributes:MarkdownAttributeContext)
+    func emit(element:MarkdownBytecode.Emission,
+        with attributes:MarkdownElementContext.AttributeContext)
     {
         let html:HTML.VoidElement
 
@@ -38,12 +39,14 @@ extension HTML.ContentEncoder
 extension HTML.ContentEncoder
 {
     private mutating
-    func open(_ element:HTML.ContainerElement, with attributes:MarkdownAttributeContext)
+    func open(_ element:HTML.ContainerElement,
+        with attributes:MarkdownElementContext.AttributeContext)
     {
         self.open(element) { attributes.encode(to: &$0) }
     }
     mutating
-    func open(context:MarkdownElementContext, with attributes:MarkdownAttributeContext)
+    func open(context:MarkdownElementContext,
+        with attributes:MarkdownElementContext.AttributeContext)
     {
         switch context
         {

Sources/MarkdownRendering/HTML.ContentEncoder (ext).swift renamed to Sources/MarkdownRendering/HTML/HTML.ContentEncoder (ext).swift

@@ -44,10 +44,13 @@ extension HyperTextRenderableMarkdown
     /// If an error occurs, stops execution and throws the error, otherwise
     /// returns nil if successful. This function always closes any HTML elements
     /// it creates, even on error.
+    ///
+    /// See ``PlainTextRenderableMarkdown.write(to:)`` for a simpler version of this function
+    /// that only renders visible text.
     public
     func render(to html:inout HTML.ContentEncoder) throws
     {
-        var attributes:MarkdownAttributeContext = .init()
+        var attributes:MarkdownElementContext.AttributeContext = .init()
         var stack:[MarkdownElementContext] = []
 
         defer
@@ -67,20 +70,18 @@ extension HyperTextRenderableMarkdown
                 throw MarkdownRenderingError.invalidInstruction
 
             case .attribute(let attribute, nil):
-                attributes.commit()
-                attributes.current = (attribute, [])
-
+                attributes.flush(beginning: attribute)
 
             case .attribute(let attribute, let reference?):
-                attributes.commit()
+                attributes.flush()
 
                 if  let value:String = self.load(reference, for: attribute)
                 {
                     attributes.append(value: value, as: attribute)
                 }
 
             case .emit(let element):
-                attributes.commit()
+                attributes.flush()
 
                 html.emit(newlines: &newlines)
                 html.emit(element: element, with: attributes)
@@ -92,7 +93,7 @@ extension HyperTextRenderableMarkdown
                 self.load(reference, into: &html)
 
             case .push(let element):
-                attributes.commit()
+                attributes.flush()
 
                 let context:MarkdownElementContext = .init(from: element,
                     attributes: &attributes)
@@ -120,7 +121,7 @@ extension HyperTextRenderableMarkdown
                 }
 
             case .utf8(let codeunit):
-                guard case nil = attributes.current?.utf8.append(codeunit)
+                guard case nil = attributes.buffer(utf8: codeunit)
                 else
                 {
                     continue

Sources/MarkdownRendering/HyperTextRenderableMarkdown.swift renamed to Sources/MarkdownRendering/HTML/HyperTextRenderableMarkdown.swift

@@ -0,0 +1,121 @@
+import HTML
+import MarkdownABI
+
+extension MarkdownElementContext
+{
+    struct AttributeContext
+    {
+        private
+        var complete:[(name:HTML.Attribute, value:String)]
+        private
+        var current:MarkdownBytecode.Attribute?
+        private
+        var buffer:[UInt8]
+
+        init()
+        {
+            self.complete = []
+            self.current = nil
+            self.buffer = []
+        }
+    }
+}
+extension MarkdownElementContext.AttributeContext
+{
+    func contains(_ attribute:HTML.Attribute) -> Bool
+    {
+        self.complete.contains { $0.name == attribute }
+    }
+
+    mutating
+    func append(class enumerated:some RawRepresentable<String>)
+    {
+        self.complete.append((.class, enumerated.rawValue))
+    }
+    mutating
+    func append(value:String, as instruction:MarkdownBytecode.Attribute)
+    {
+        switch instruction
+        {
+        case .language: self.complete.append((.class, "language-\(value)"))
+
+        case .checkbox: self.complete.append((.type, "checkbox"))
+
+        case .center:   self.complete.append((.align, "center"))
+        case .left:     self.complete.append((.align, "left"))
+        case .right:    self.complete.append((.align, "right"))
+
+        case .alt:      self.complete.append((.alt, value))
+        case .class:    self.complete.append((.class, value))
+        case .checked:  self.complete.append((.checked, value))
+        case .disabled: self.complete.append((.disabled, value))
+        case .href:     self.complete.append((.href, value))
+        case .src:      self.complete.append((.src, value))
+        case .title:    self.complete.append((.title, value))
+
+        case .external:
+            self.complete.append((.rel, "\(HTML.Attribute.Rel.nofollow)"))
+            self.complete.append((.rel, "\(HTML.Attribute.Rel.noopener)"))
+            self.complete.append((.rel, "\(HTML.Attribute.Rel.google_ugc)"))
+            self.complete.append((.href, value))
+        }
+    }
+}
+extension MarkdownElementContext.AttributeContext
+{
+    mutating
+    func buffer(utf8 codeunit:UInt8) -> Void?
+    {
+        self.current.map { _ in self.buffer.append(codeunit) }
+    }
+    /// Remove all attributes from the attribute context.
+    mutating
+    func clear()
+    {
+        self.complete.removeAll(keepingCapacity: true)
+        self.current = nil
+        self.buffer.removeAll(keepingCapacity: true)
+    }
+    /// Closes the current attribute (if any), and appends it to the list of
+    /// complete attributes, making it available for encoding.
+    mutating
+    func flush(beginning next:MarkdownBytecode.Attribute?)
+    {
+        defer
+        {
+            self.current = next
+        }
+        if  let instruction:MarkdownBytecode.Attribute = self.current
+        {
+            self.append(value: .init(decoding: self.buffer, as: Unicode.UTF8.self),
+                as: instruction)
+            self.buffer.removeAll(keepingCapacity: true)
+        }
+    }
+}
+extension MarkdownElementContext.AttributeContext:MarkdownAttributeContext
+{
+}
+extension MarkdownElementContext.AttributeContext
+{
+    func encode(to attributes:inout HTML.AttributeEncoder)
+    {
+        var classes:[String] = []
+
+        for (name, value):(HTML.Attribute, String) in self.complete
+        {
+            switch name
+            {
+            case .class:
+                classes.append(value)
+
+            default:
+                attributes[name: name] = value
+            }
+        }
+        if !classes.isEmpty
+        {
+            attributes.class = classes.joined(separator: " ")
+        }
+    }
+}

Sources/MarkdownRendering/HTML/MarkdownElementContext.AttributeContext.swift

@@ -26,30 +26,29 @@ enum MarkdownElementContext
 extension MarkdownElementContext
 {
     private static
-    func highlight(_ type:MarkdownSyntaxHighlight,
-        attributes:inout MarkdownAttributeContext) -> Self
+    func highlight(_ type:MarkdownSyntaxHighlight, attributes:inout AttributeContext) -> Self
     {
         let container:HTML.ContainerElement = attributes.contains(.href) ? .a : .span
         attributes.append(class: type)
         return .highlight(.init(container: container, type: type))
     }
 
     private static
-    func section(_ type:Section, attributes:inout MarkdownAttributeContext) -> Self
+    func section(_ type:Section, attributes:inout AttributeContext) -> Self
     {
         attributes.append(class: type)
         return .section(type)
     }
     private static
-    func signage(_ type:Signage, attributes:inout MarkdownAttributeContext) -> Self
+    func signage(_ type:Signage, attributes:inout AttributeContext) -> Self
     {
         attributes.append(class: type)
         return .signage(type)
     }
 }
 extension MarkdownElementContext
 {
-    init(from markdown:MarkdownBytecode.Context, attributes:inout MarkdownAttributeContext)
+    init(from markdown:MarkdownBytecode.Context, attributes:inout AttributeContext)
     {
         switch markdown
         {

Sources/MarkdownRendering/MarkdownElementContext.Highlight.swift renamed to Sources/MarkdownRendering/HTML/MarkdownElementContext.Highlight.swift

@@ -1,103 +1,46 @@
-import HTML
 import MarkdownABI
 
-struct MarkdownAttributeContext
+/// Common interface for ``MarkdownElementContext.AttributeContext`` and
+/// ``MarkdownTextContext.AttributeContext``.
+///
+/// We never actually dispatch through this protocol, but it is helpful for understanding how
+/// the markdown VM works.
+protocol MarkdownAttributeContext
 {
-    private(set)
-    var complete:[(name:HTML.Attribute, value:String)]
-    var current:(name:MarkdownBytecode.Attribute, utf8:[UInt8])?
-
     init()
-    {
-        self.complete = []
-        self.current = nil
-    }
-}
-extension MarkdownAttributeContext
-{
-    func contains(_ attribute:HTML.Attribute) -> Bool
-    {
-        self.complete.contains { $0.name == attribute }
-    }
 
     mutating
-    func append(class enumerated:some RawRepresentable<String>)
-    {
-        self.complete.append((.class, enumerated.rawValue))
-    }
-    mutating
-    func append(value:String, as instruction:MarkdownBytecode.Attribute)
-    {
-        switch instruction
-        {
-        case .language: self.complete.append((.class, "language-\(value)"))
+    func append(value:__owned String, as instruction:MarkdownBytecode.Attribute)
 
-        case .checkbox: self.complete.append((.type, "checkbox"))
-
-        case .center:   self.complete.append((.align, "center"))
-        case .left:     self.complete.append((.align, "left"))
-        case .right:    self.complete.append((.align, "right"))
+    /// Appends a single UTF-8 code unit to the current attribute, returning `nil` if and only
+    /// if there is no current attribute.
+    mutating
+    func buffer(utf8 codeunit:UInt8) -> Void?
 
-        case .alt:      self.complete.append((.alt, value))
-        case .class:    self.complete.append((.class, value))
-        case .checked:  self.complete.append((.checked, value))
-        case .disabled: self.complete.append((.disabled, value))
-        case .href:     self.complete.append((.href, value))
-        case .src:      self.complete.append((.src, value))
-        case .title:    self.complete.append((.title, value))
+    /// Resets the attribute context to its initial state, possibly re-using existing array
+    /// allocations.
+    mutating
+    func clear()
 
-        case .external:
-            self.complete.append((.rel, "\(HTML.Attribute.Rel.nofollow)"))
-            self.complete.append((.rel, "\(HTML.Attribute.Rel.noopener)"))
-            self.complete.append((.rel, "\(HTML.Attribute.Rel.google_ugc)"))
-            self.complete.append((.href, value))
-        }
-    }
+    /// Terminates the current attribute, if any, and begins a new attribute if `next` is
+    /// non-nil.
+    mutating
+    func flush(beginning next:MarkdownBytecode.Attribute?)
 }
 extension MarkdownAttributeContext
 {
-    /// Remove all attributes from the attribute context.
+    /// Replaces `self` with ``init``.
     mutating
     func clear()
     {
-        self.complete.removeAll()
-        self.current = nil
-    }
-    /// Closes the current attribute (if any), and appends it to the list of
-    /// complete attributes, making it available for encoding.
-    mutating
-    func commit()
-    {
-        defer
-        {
-            self.current = nil
-        }
-        if  let (instruction, utf8):(MarkdownBytecode.Attribute, [UInt8]) = self.current
-        {
-            self.append(value: .init(decoding: utf8, as: Unicode.UTF8.self), as: instruction)
-        }
+        self = .init()
     }
 }
 extension MarkdownAttributeContext
 {
-    func encode(to attributes:inout HTML.AttributeEncoder)
+    mutating
+    func flush()
     {
-        var classes:[String] = []
-
-        for (name, value):(HTML.Attribute, String) in self.complete
-        {
-            switch name
-            {
-            case .class:
-                classes.append(value)
-
-            default:
-                attributes[name: name] = value
-            }
-        }
-        if !classes.isEmpty
-        {
-            attributes.class = classes.joined(separator: " ")
-        }
+        self.flush(beginning: nil)
     }
 }