update README to reflect new syntax and how to escape HTML

RandomHashTags · RandomHashTags · commit 0c46fb20d16a · 2024-10-12T05:14:38.000-05:00
- added some documentation to escape functions
- now flattens certain string interpolations to equivalent string representations
diff --git a/README.md b/README.md
@@ -23,14 +23,14 @@ Write HTML using Swift Macros.
 <details>
 <summary>How do I use this library?</summary>
 
-Syntax: `#<html element>(attributes: [], <element specific attributes>: V?, _ innerHTML: [ExpressibleByStringLiteral])`
+Syntax: `#<html element>(attributes: [], <element specific attributes>: V?, _ innerHTML: ExpressibleByStringLiteral...)`
 #### Examples
 
 ```swift
 // <div class="dark"><p>Macros are beautiful</p></div>
-#div(attributes: [.class(["dark"])], [
-    #p(["Macros are beautiful"])
-])
+#div(attributes: [.class(["dark"])],
+    #p("Macros are beautiful")
+)
 
 // <a href="https://github.com/RandomHashTags/litleagues" target="_blank"></a>
 #a(href: "https://github.com/RandomHashTags/litleagues", target: ._blank)
@@ -47,8 +47,8 @@ Syntax: `#<html element>(attributes: [], <element specific attributes>: V?, _ in
 )
 
 // html example
-let test:String = #html([
-    #body([
+let test:String = #html(
+    #body(
         #div(
             attributes: [
                 .class(["dark-mode", "row"]),
@@ -57,38 +57,65 @@ let test:String = #html([
                 .inputmode(.email),
                 .title("Hey, you're pretty cool")
             ],
-            [
-                "Random text",
-                #div(),
-                #a([
-                    #div([
-                        #abbr()
-                    ]),
-                    #address()
-                ]),
-                #div(),
-                #button(disabled: true),
-                #video(autoplay: true, controls: false, preload: .auto, src: "https://github.com/RandomHashTags/litleagues", width: .centimeters(1)),
-            ]
+            "Random text",
+            #div(),
+            #a(
+                #div(
+                    #abbr()
+                ),
+                #address()
+            ),
+            #div(),
+            #button(disabled: true),
+            #video(autoplay: true, controls: false, preload: .auto, src: "https://github.com/RandomHashTags/litleagues", width: .centimeters(1)),
         )
-    ])
-])
+    )
+)
 ```
 </details>
 
+<details>
+<summary>How do I escape HTML?</summary>
+
+The output automatically escapes html characters **known only at compile time**.
+
+
+If you know the data **at compile time** (and not working with HTML macros):
+- `#escapeHTML()` macro
+
+If you're working with **runtime** data:
+- `<string>.escapeHTML(escapeAttributes:)`
+  - mutates `self` escaping HTML and, optionally, attribute characters
+- `<string>.escapeHTMLAttributes()`
+  - mutates `self` escaping only attribute characters
+- `<string>.escapingHTML(escapeAttributes:)`
+  - creates a copy of `self` escaping HTML and, optionally, attribute characters
+- `<string>.escapingHTMLAttributes()`
+  - creates a copy of `self` escaping only attribute characters
+
+</details>
+
 <details>
 <summary>How do I encode variables?</summary>
+
 Using String Interpolation.
 
+> You will get a compiler warning saying *interpolation may introduce raw HTML*.
+> 
+> Its up to you whether or not to suppress this warning or escape the HTML at runtime using an method described above.
+
 #### Example
 ```swift
 let string:String = "any string value", integer:Int = -69, float:Float = 3.14159
 
 // ✅ DO
-let _:String = #p(["\(string); \(integer); \(float)"])
+let _:String = #p("\(string); \(integer); \(float)")
+let _:String = #p("\(string)", "; ", String(describing: integer), "; ", float.description)
+
+// ❌ DON'T; compiler error: String Interpolation required
+let integer_string:String = String(describing: integer), float_string:String = String(describing: float)
+let _:String = #p(string, "; ", integer_string, "; ", float_string)
 
-// ❌ DON'T
-let _:String = #p([string, "; ", String(describing: integer), "; ", float.description])
 ```
 
 </details>
@@ -151,7 +178,7 @@ Use the `HTMLElementAttribute.event(<type>, "<value>")`.
   - [BinaryBuilds/swift-html](https://github.com/BinaryBirds/swift-html) v1.7.0 (patched version [here](https://github.com/RandomHashTags/fork-bb-swift-html))
   - [sliemeobn/elementary](https://github.com/sliemeobn/elementary) v0.3.4
   - [JohnSundell/Plot](https://github.com/JohnSundell/Plot) v0.14.0
-  - [RandomHashTags/swift-htmlkit](https://github.com/RandomHashTags/swift-htmlkit) v0.5.0 (this library)
+  - [RandomHashTags/swift-htmlkit](https://github.com/RandomHashTags/swift-htmlkit) v0.6.0 (this library)
   - [pointfreeco/swift-html](https://github.com/pointfreeco/swift-html) v0.4.1
   - [robb/Swim](https://github.com/robb/Swim) v0.4.0 (patched version [here](https://github.com/RandomHashTags/fork-Swim); custom renderer [here](https://github.com/RandomHashTags/swift-htmlkit/blob/main/Benchmarks/Benchmarks/Swim/Swim.swift))
   - [vapor-community/HTMLKit](https://github.com/vapor-community/HTMLKit) v2.8.1
diff --git a/Sources/HTMLKitMacros/HTMLElement.swift b/Sources/HTMLKitMacros/HTMLElement.swift
@@ -47,12 +47,12 @@ private extension HTMLElement {
         }
         return (string, false)
 
-        if isRoot {
+        /*if isRoot {
             return dynamicVariables.isEmpty ? (string, false) : ("DynamicString(string: \"" + string + "\").test", true)
             //return dynamicVariables.isEmpty ? (string, false) : ("DynamicString(string: \"" + string + "\", values: [" + dynamicVariables.map({ $0.contains("\\(") ? "\"\($0)\"" : $0 }).joined(separator: ",") + "]).test", true)
         } else {
             return (string, false)
-        }
+        }*/
     }
     static func parse_arguments(context: some MacroExpansionContext, elementType: HTMLElementType, children: Slice<SyntaxChildren>, dynamicVariables: inout [String]) -> ElementData {
         var attributes:[String] = [], innerHTML:[String] = []
@@ -65,7 +65,7 @@ private extension HTMLElement {
                         if key == "acceptCharset" {
                             key = "accept-charset"
                         }
-                        if var string:String = parse_attribute(context: context, elementType: elementType, key: key, argument: child, dynamicVariables: &dynamicVariables) {
+                        if let string:String = parse_attribute(context: context, elementType: elementType, key: key, argument: child, dynamicVariables: &dynamicVariables) {
                             attributes.append(key + (string.isEmpty ? "" : "=\\\"" + string + "\\\""))
                         }
                     }
@@ -86,7 +86,7 @@ private extension HTMLElement {
                 case "custom", "data":
                     var (literalValue, returnType):(String, LiteralReturnType) = parse_literal_value(context: context, elementType: elementType, key: key, argument: function.arguments.last!, dynamicVariables: &dynamicVariables)!
                     if returnType == .string {
-                        literalValue.escapeHTML(attribute: true)
+                        literalValue.escapeHTML(escapeAttributes: true)
                     }
                     value = literalValue
                     if key == "custom" {
@@ -97,7 +97,15 @@ private extension HTMLElement {
                     break
                 case "event":
                     key = "on" + key_element.memberAccess!.declName.baseName.text
-                    value = function.arguments.last!.expression.stringLiteral!.string.escapingHTML(attribute: true)
+                    if var (literalValue, returnType):(String, LiteralReturnType) = parse_literal_value(context: context, elementType: elementType, key: key, argument: function.arguments.last!, dynamicVariables: &dynamicVariables) {
+                        if returnType == .string {
+                            literalValue.escapeHTML(escapeAttributes: true)
+                        }
+                        value = literalValue
+                    } else {
+                        unallowed_expression(context: context, node: function.arguments.last!)
+                        return []
+                    }
                     break
                 default:
                     if let string:String = parse_attribute(context: context, elementType: elementType, key: key, argument: key_argument, dynamicVariables: &dynamicVariables) {
@@ -122,24 +130,27 @@ private extension HTMLElement {
         if let macro:MacroExpansionExprSyntax = child.expression.macroExpansion {
             var string:String = parse_macro(context: context, expression: macro, isRoot: false, dynamicVariables: &dynamicVariables).0
             if elementType == .escapeHTML {
-                string.escapeHTML(attribute: false)
+                string.escapeHTML(escapeAttributes: false)
             }
             return string
-        } else if var (string, returnType) = parse_literal_value(context: context, elementType: elementType, key: "", argument: child, dynamicVariables: &dynamicVariables) {
-            string.escapeHTML(attribute: false)
+        } else if var string:String = parse_literal_value(context: context, elementType: elementType, key: "", argument: child, dynamicVariables: &dynamicVariables)?.value {
+            string.escapeHTML(escapeAttributes: false)
             return string
         } else {
-            context.diagnose(Diagnostic(node: child, message: DiagnosticMsg(id: "unallowedExpression", message: "Expression not allowed. String interpolation is required when encoding runtime values."), fixIts: [
-                FixIt(message: DiagnosticMsg(id: "useStringInterpolation", message: "Use String Interpolation.", severity: .error), changes: [
-                    FixIt.Change.replace(
-                        oldNode: Syntax(child),
-                        newNode: Syntax(StringLiteralExprSyntax(content: "\\(\(child))"))
-                    )
-                ])
-            ]))
+            unallowed_expression(context: context, node: child)
             return nil
         }
     }
+    static func unallowed_expression(context: some MacroExpansionContext, node: LabeledExprSyntax) {
+        context.diagnose(Diagnostic(node: node, message: DiagnosticMsg(id: "unallowedExpression", message: "String Interpolation is required when encoding runtime values."), fixIts: [
+            FixIt(message: DiagnosticMsg(id: "useStringInterpolation", message: "Use String Interpolation.", severity: .error), changes: [
+                FixIt.Change.replace(
+                    oldNode: Syntax(node),
+                    newNode: Syntax(StringLiteralExprSyntax(content: "\\(\(node))"))
+                )
+            ])
+        ]))
+    }
 
     struct ElementData {
         let attributes:String, innerHTML:String
@@ -166,7 +177,7 @@ private extension HTMLElement {
             switch returnType {
             case .boolean: return string.elementsEqual("true") ? "" : nil
             case .string:
-                string.escapeHTML(attribute: true)
+                string.escapeHTML(escapeAttributes: true)
                 return string
             case .interpolation: return string
             }
@@ -213,7 +224,7 @@ private extension HTMLElement {
                     if function.calledExpression.as(DeclReferenceExprSyntax.self)?.baseName.text == "StaticString" {
                         return (function.arguments.first!.expression.stringLiteral!.string, .string)
                     }
-                    return ("\(function)", .interpolation)
+                    return ("\\(\(function))", .interpolation)
                 }
             }
             if let member:MemberAccessExprSyntax = expression.memberAccess {
@@ -227,7 +238,7 @@ private extension HTMLElement {
                             return (integer, .interpolation)
                         }
                     } else {*/
-                        return ("\(member)", .interpolation)
+                        return ("\\(\(member))", .interpolation)
                     //}
                 } else {
                     return (HTMLElementAttribute.Extra.htmlValue(enumName: enumName(elementType: elementType, key: key), for: decl), .string)
@@ -263,22 +274,56 @@ private extension HTMLElement {
             //context.diagnose(Diagnostic(node: expression, message: DiagnosticMsg(id: "somethingWentWrong", message: "Something went wrong. (" + expression.debugDescription + ")", severity: .warning)))
             return nil
         }
-        if returnType == .interpolation || string.contains("\\(") {
-            context.diagnose(Diagnostic(node: expression, message: DiagnosticMsg(id: "unsafeInterpolation", message: "Interpolation may introduce raw HTML elements.", severity: .warning)))
+        var remaining_interpolation:Int = 0
+        if let list:StringLiteralSegmentListSyntax = expression.stringLiteral?.segments {
+            for segment in list {
+                if let expr:ExpressionSegmentSyntax = segment.as(ExpressionSegmentSyntax.self) {
+                    remaining_interpolation += 1
+                    if flatten_interpolation(string: &string, remaining_interpolation: &remaining_interpolation, expr: expr) {
+                        remaining_interpolation -= 1
+                    }
+                }
+            }
+        }
+        if returnType == .interpolation || remaining_interpolation > 0 {
             //dynamicVariables.append(string)
-            string = string.contains("\\(") ? string : "\\(" + string + ")"
+            if !string.contains("\\(") {
+                string = "\\(" + string + ")"
+            }
             returnType = .interpolation
+            context.diagnose(Diagnostic(node: expression, message: DiagnosticMsg(id: "unsafeInterpolation", message: "Interpolation may introduce raw HTML.", severity: .warning)))
         }
         return (string, returnType)
     }
+    static func flatten_interpolation(string: inout String, remaining_interpolation: inout Int, expr: ExpressionSegmentSyntax) -> Bool { // TODO: can still be improved ("\(description \(title))" doesn't get flattened)
+        let expression:ExprSyntax = expr.expressions.first!.expression
+        if let list:StringLiteralSegmentListSyntax = expression.stringLiteral?.segments {
+            for segment in list {
+                if let expr:ExpressionSegmentSyntax = segment.as(ExpressionSegmentSyntax.self) {
+                    remaining_interpolation += 1
+                    if flatten_interpolation(string: &string, remaining_interpolation: &remaining_interpolation, expr: expr) {
+                        remaining_interpolation -= 1
+                    }
+                } else if let fix:String = segment.as(StringSegmentSyntax.self)?.content.text {
+                    string.replace("\(expr)", with: fix)
+                    remaining_interpolation -= 1
+                }
+            }
+        }
+        if let fix:String = expression.integerLiteral?.literal.text ?? expression.floatLiteral?.literal.text {
+            string.replace("\(expr)", with: fix)
+            return true
+        }
+        return false
+    }
 }
 
 enum LiteralReturnType {
     case boolean, string, interpolation
 }
 
 // MARK: HTMLElementType
-enum HTMLElementType : String {
+enum HTMLElementType : String, CaseIterable {
     case escapeHTML
     case html
     case custom
@@ -424,6 +469,7 @@ enum HTMLElementType : String {
     }
 }
 
+// MARK: Misc
 extension ExprSyntax {
     var booleanLiteral : BooleanLiteralExprSyntax? { self.as(BooleanLiteralExprSyntax.self) }
     var stringLiteral : StringLiteralExprSyntax? { self.as(StringLiteralExprSyntax.self) }
diff --git a/Sources/HTMLKitUtilities/HTMLKitUtilities.swift b/Sources/HTMLKitUtilities/HTMLKitUtilities.swift
@@ -7,25 +7,35 @@
 
 // MARK: Escape HTML
 public extension String {
-    func escapingHTML(attribute: Bool) -> String {
+    /// Escapes all occurrences of source-breaking HTML characters
+    /// - Parameters:
+    ///   - escapeAttributes: Whether or not to escape source-breaking HTML attribute characters
+    /// - Returns: A new `String` escaping source-breaking HTML
+    func escapingHTML(escapeAttributes: Bool) -> String {
         var string:String = self
-        string.escapeHTML(attribute: attribute)
+        string.escapeHTML(escapeAttributes: escapeAttributes)
         return string
     }
-    mutating func escapeHTML(attribute: Bool) {
+    /// Escapes all occurrences of source-breaking HTML characters
+    /// - Parameters:
+    ///   - escapeAttributes: Whether or not to escape source-breaking HTML attribute characters
+    mutating func escapeHTML(escapeAttributes: Bool) {
         self.replace("&", with: "&amp;")
         self.replace("<", with: "&lt;")
         self.replace(">", with: "&gt;")
-        if attribute {
-            self.escapeHTMLAttribute()
+        if escapeAttributes {
+            self.escapeHTMLAttributes()
         }
     }
-    func escapingHTMLAttribute() -> String {
+    /// Escapes all occurrences of source-breaking HTML attribute characters
+    /// - Returns: A new `String` escaping source-breaking HTML attribute characters
+    func escapingHTMLAttributes() -> String {
         var string:String = self
-        string.escapeHTMLAttribute()
+        string.escapeHTMLAttributes()
         return string
     }
-    mutating func escapeHTMLAttribute() {
+    /// Escapes all occurrences of source-breaking HTML attribute characters
+    mutating func escapeHTMLAttributes() {
         self.replace("\"", with: "&quot;")
         self.replace("'", with: "&#39")
     }
diff --git a/Tests/HTMLKitTests/HTMLKitTests.swift b/Tests/HTMLKitTests/HTMLKitTests.swift
