updated escapeHTML macro behavior; added some documentation

Author: RandomHashTags

Sources/HTMLKit/HTMLKit.swift

@@ -19,7 +19,7 @@ public extension StringProtocol {
 }
 
 @freestanding(expression)
-public macro escapeHTML<T: CustomStringConvertible>(_ innerHTML: T...) -> T = #externalMacro(module: "HTMLKitMacros", type: "EscapeHTML")
+public macro escapeHTML(_ innerHTML: CustomStringConvertible...) -> String = #externalMacro(module: "HTMLKitMacros", type: "EscapeHTML")
 
 // MARK: HTML Representation
 @freestanding(expression)

Sources/HTMLKitUtilities/LiteralElements.swift

@@ -134,18 +134,26 @@ macro HTMLElements(
 
 // MARK: HTML
 public protocol HTMLElement : CustomStringConvertible {
+    /// Whether or not this element is a void element.
     var isVoid : Bool { get }
+    /// Whether or not this element should include a forward slash in the tag name.
     var trailingSlash : Bool { get }
-    var tag: String { get }
+    /// Whether or not to HTML escape the `<` & `>` characters directly adjacent of the opening and closing tag names when rendering.
+    var escaped : Bool { get set }
+    /// This element's tag name.
+    var tag : String { get }
+    /// The global attributes of this element.
     var attributes : [HTMLElementAttribute] { get }
+    /// The inner HTML content of this element.
     var innerHTML : [CustomStringConvertible] { get }
 }
 
 /// A custom HTML element.
 public struct custom : HTMLElement {
     public var isVoid:Bool
     public var trailingSlash:Bool
-    public var tag:String
+    public var escaped:Bool = false
+    public let tag:String
     public var attributes:[HTMLElementAttribute]
     public var innerHTML:[CustomStringConvertible]
 
@@ -171,7 +179,20 @@ public struct custom : HTMLElement {
     }
 
     public var description : String {
-        return "<" + tag + (isVoid && trailingSlash ? " /" : "") + ">" + (isVoid ? "" : "</" + tag + ">")
+        let attributes_string:String = self.attributes.compactMap({
+            guard let v:String = $0.htmlValue else { return nil }
+            let delimiter:String = $0.htmlValueDelimiter
+            return $0.key + ($0.htmlValueIsVoidable && v.isEmpty ? "" : "=\(delimiter)\(v)\(delimiter)")
+        }).joined(separator: " ")
+        let l:String, g:String
+        if escaped {
+            l = "&lt;"
+            g = "&gt;"
+        } else {
+            l = "<"
+            g = ">"
+        }
+        return l + tag + (isVoid && trailingSlash ? " /" : "") + g + (attributes_string.isEmpty ? "" : " " + attributes_string) + (isVoid ? "" : l + "/" + tag + g)
     }
 }
 

Sources/HTMLKitUtilities/ParseData.swift

@@ -14,9 +14,13 @@ public extension HTMLKitUtilities {
     static func escapeHTML(expansion: MacroExpansionExprSyntax, context: some MacroExpansionContext) -> String {
         return expansion.arguments.children(viewMode: .all).compactMap({
             guard let child:LabeledExprSyntax = $0.labeled,
-                    let c:CustomStringConvertible = HTMLKitUtilities.parseInnerHTML(context: context, child: child, lookupFiles: []) else {
+                    var c:CustomStringConvertible = HTMLKitUtilities.parseInnerHTML(context: context, child: child, lookupFiles: []) else {
                 return nil
             }
+            if var element:HTMLElement = c as? HTMLElement {
+                element.escaped = true
+                c = element
+            }
             return String(describing: c)
         }).joined()
     }
@@ -112,7 +116,7 @@ public extension HTMLKitUtilities {
     ) -> CustomStringConvertible? {
         if let expansion:MacroExpansionExprSyntax = child.expression.macroExpansion {
             if expansion.macroName.text == "escapeHTML" {
-                return escapeHTML(expansion: expansion, context: context).escapingHTML(escapeAttributes: true)
+                return escapeHTML(expansion: expansion, context: context)
             }
             return "" // TODO: fix?
         } else if let element:HTMLElement = parse_element(context: context, expr: child.expression) {

Sources/HTMLKitUtilityMacros/HTMLElements.swift

@@ -36,7 +36,8 @@ enum HTMLElements : DeclarationMacro {
             var string:String = "/// MARK: \(element)\n/// The `\(element)` HTML element.\npublic struct \(element) : HTMLElement {\n"
             string += "public private(set) var isVoid:Bool = \(is_void)\n"
             string += "public var trailingSlash:Bool = false\n"
-            string += "public private(set) var tag:String = \"\(element)\"\n"
+            string += "public var escaped:Bool = false\n"
+            string += "public let tag:String = \"\(element)\"\n"
             string += "public var attributes:[HTMLElementAttribute]\n"
 
             var initializers:String = ""
@@ -180,7 +181,17 @@ enum HTMLElements : DeclarationMacro {
             render += attributes_func
             render += "let string:String = innerHTML.map({ String(describing: $0) }).joined()\n"
             let trailing_slash:String = is_void ? " + (trailingSlash ? \" /\" : \"\")" : ""
-            render += "return \"\(element == "html" ? "<!DOCTYPE html>" : "")<\(element)\" + attributes()\(trailing_slash) + \">\" + string" + (is_void ? "" : " + \"</\(element)>\"")
+            render += """
+            let l:String, g:String
+            if escaped {
+                l = "&lt;"
+                g = "&gt;"
+            } else {
+                l = "<"
+                g = ">"
+            }
+            """
+            render += "return \(element == "html" ? "l + \"!DOCTYPE html\" + g + " : "")l + \"\(element)\" + attributes()\(trailing_slash) + g + string" + (is_void ? "" : " + l + \"/\(element)\" + g")
             render += "}"
 
             string += render

Tests/HTMLKitTests/ElementTests.swift

@@ -21,6 +21,9 @@ struct ElementTests {
         string = #escapeHTML("<!DOCTYPE html><html>Test</html>")
         #expect(string == escaped)
 
+        string = #escapeHTML(html("Test"))
+        #expect(string == escaped)
+
         string = #html(p(#escapeHTML(html("Test"))))
         #expect(string == expected_result)