HTMLEncoding updates, which allowed...

- removal of `swift-nio` dependency
- addition of `custom` HTMLEncoding case (read documentation to learn how to use)

Author: RandomHashTags

Package.swift

@@ -16,8 +16,7 @@ let package = Package(
         )
     ],
     dependencies: [
-        .package(url: "https://github.com/swiftlang/swift-syntax", from: "600.0.1"),
-        .package(url: "https://github.com/apple/swift-nio", from: "2.75.0")
+        .package(url: "https://github.com/swiftlang/swift-syntax", from: "600.0.1")
     ],
     targets: [
         .macro(
@@ -35,8 +34,7 @@ let package = Package(
                 "HTMLKitUtilityMacros",
                 .product(name: "SwiftDiagnostics", package: "swift-syntax"),
                 .product(name: "SwiftSyntax", package: "swift-syntax"),
-                .product(name: "SwiftSyntaxMacros", package: "swift-syntax"),
-                .product(name: "NIOCore", package: "swift-nio")
+                .product(name: "SwiftSyntaxMacros", package: "swift-syntax")
             ]
         ),
         .macro(

Sources/HTMLKit/HTMLKit.swift

@@ -11,8 +11,6 @@
 import struct Foundation.Data
 #endif
 
-import struct NIOCore.ByteBuffer
-
 // MARK: StaticString equality
 public extension StaticString {
     static func == (left: Self, right: Self) -> Bool { left.description == right.description }
@@ -29,8 +27,8 @@ public macro escapeHTML<T: ExpressibleByStringLiteral>(_ innerHTML: T...) -> T =
 
 // MARK: HTML Representation
 @freestanding(expression)
-public macro html<T: ExpressibleByStringLiteral>(
+public macro html<T: CustomStringConvertible>(
     encoding: HTMLEncoding = .string,
     lookupFiles: [StaticString] = [],
-    _ innerHTML: CustomStringConvertible...
+    _ innerHTML: HTMLElement...
 ) -> T = #externalMacro(module: "HTMLKitMacros", type: "HTMLElementMacro")

Sources/HTMLKitMacros/HTMLElement.swift

@@ -14,13 +14,9 @@ import SwiftSyntaxMacros
 import struct Foundation.Data
 #endif
 
-import struct NIOCore.ByteBuffer
-
 enum HTMLElementMacro : ExpressionMacro {
     static func expansion(of node: some FreestandingMacroExpansionSyntax, in context: some MacroExpansionContext) throws -> ExprSyntax {
-        let string:String = expand_macro(context: context, macro: node.macroExpansion!)
-        let encoding:HTMLEncoding = HTMLEncoding.string
-
+        let (string, encoding):(String, HTMLEncoding) = expand_macro(context: context, macro: node.macroExpansion!)
         func has_no_interpolation() -> Bool {
             let has_interpolation:Bool = !string.ranges(of: try! Regex("\\((.*)\\)")).isEmpty
             guard !has_interpolation else {
@@ -52,15 +48,17 @@ enum HTMLElementMacro : ExpressionMacro {
 
             case .string:
                 return "\"\(raw: string)\""
+            case .custom(let encoded):
+                return "\(raw: encoded.replacingOccurrences(of: "$0", with: string))"
         }
     }
 }
 
 private extension HTMLElementMacro {
     // MARK: Expand Macro
-    static func expand_macro(context: some MacroExpansionContext, macro: MacroExpansionExprSyntax) -> String {
+    static func expand_macro(context: some MacroExpansionContext, macro: MacroExpansionExprSyntax) -> (String, HTMLEncoding) {
         guard let elementType:HTMLElementType = HTMLElementType(rawValue: macro.macroName.text) else {
-            return "\(macro)"
+            return ("\(macro)", .string)
         }
         let children:SyntaxChildren = macro.arguments.children(viewMode: .all)
         /*if elementType == .escapeHTML {
@@ -71,6 +69,6 @@ private extension HTMLElementMacro {
             return array.map({ String(describing: $0) }).joined()
         }*/
         let data:HTMLKitUtilities.ElementData = HTMLKitUtilities.parse_arguments(context: context, children: children)
-        return data.innerHTML.map({ String(describing: $0) }).joined()
+        return (data.innerHTML.map({ String(describing: $0) }).joined(), data.encoding)
     }
 }

Sources/HTMLKitUtilities/HTMLEncoding.swift

@@ -7,29 +7,29 @@
 
 /// The value type the data should be encoded to when returned from the macro.
 /// 
-/// ## Interpolation Promotion
-/// Swift HTMLKit tries to [promote](https://github.com/RandomHashTags/swift-htmlkit/blob/94793984763308ef5275dd9f71ea0b5e83fea417/Sources/HTMLKitMacros/HTMLElement.swift#L423) known interpolation at compile time with an equivalent `StaticString` for the best performance.
+/// ### Interpolation Promotion
+/// Swift HTMLKit tries to [promote](https://github.com/RandomHashTags/swift-htmlkit/blob/94793984763308ef5275dd9f71ea0b5e83fea417/Sources/HTMLKitMacros/HTMLElement.swift#L423) known interpolation at compile time with an equivalent string literal for the best performance, regardless of encoding.
 /// It is currently limited due to macro expansions being sandboxed and lexical contexts/AST not being available for macro arguments.
-/// This means referencing content known at compile time in a html macro won't get replaced by its literal contents.
+/// This means referencing content known at compile time in a html macro won't get promoted to its expected value.
 /// [Read more about this limitation](https://forums.swift.org/t/swift-lexical-lookup-for-referenced-stuff-located-outside-scope-current-file/75776/6).
 /// 
-/// ### Promotion Example
+/// #### Promotion Example
 /// 
 /// ```swift
 /// let _:StaticString = #html(div("\("string")")) // ✅ promotion makes this "<div>string</div>"
-/// let _:StaticString = #html("\(5)") // ✅ promotion makes this "<div>5</div>"
-/// let _:StaticString = #html(5) // ✅ promotion makes this "<div>5</div>"
+/// let _:StaticString = #html(div("\(5)")) // ✅ promotion makes this "<div>5</div>"
+/// let _:StaticString = #html(div(5)) // ✅ promotion makes this "<div>5</div>"
 /// ````
 /// 
-/// ### Promotion Limitation
+/// #### Promotion Limitation
 /// 
 /// ```swift
 /// let string:StaticString = "Test"
 /// let _:StaticString = #html(div(string)) // ❌ promotion cannot be applied; StaticString not allowed
 /// let _:String = #html(div(string)) // ⚠️ promotion cannot be applied; compiled as "<div>\(string)</div>"
-/// ````
+/// ```
 /// 
-public enum HTMLEncoding : String {
+public enum HTMLEncoding {
     /// `String`/`StaticString`
     case string
 
@@ -47,6 +47,18 @@ public enum HTMLEncoding : String {
     case foundationData
 
     /// `ByteBuffer`
-    /// - Warning: Swift HTMLKit does not depend on `swift-nio`. You need to import `NIOCore` to use this!
+    /// - Warning: You need to import `NIOCore` to use this! Swift HTMLKit does not depend on `swift-nio`!
     case byteBuffer
+
+    /// Encode the HTML into a custom type.
+    /// 
+    /// Use `$0` for the compiled HTML.
+    /// - Parameters:
+    ///   - logic: The encoding logic, represented as a string.
+    /// ### Example Usage
+    /// ```swift
+    /// let _:String = #html(encoding: .custom(#"String("$0")"#), p(5)) // String("<p>5</p>")
+    /// ```
+    /// 
+    case custom(_ logic: String)
 }

Sources/HTMLKitUtilities/HTMLKitUtilities.swift

@@ -8,17 +8,20 @@
 // MARK: HTMLKitUtilities
 public enum HTMLKitUtilities {
     public struct ElementData {
+        public let encoding:HTMLEncoding
         public let globalAttributes:[HTMLElementAttribute]
         public let attributes:[String:Any]
         public let innerHTML:[CustomStringConvertible]
         public let trailingSlash:Bool
 
         init(
+            _ encoding: HTMLEncoding,
             _ globalAttributes: [HTMLElementAttribute],
             _ attributes: [String:Any],
             _ innerHTML: [CustomStringConvertible],
             _ trailingSlash: Bool
         ) {
+            self.encoding = encoding
             self.globalAttributes = globalAttributes
             self.attributes = attributes
             self.innerHTML = innerHTML

Sources/HTMLKitUtilities/ParseData.swift

@@ -15,6 +15,7 @@ public extension HTMLKitUtilities {
         context: some MacroExpansionContext,
         children: SyntaxChildren
     ) -> ElementData {
+        var encoding:HTMLEncoding = HTMLEncoding.string
         var global_attributes:[HTMLElementAttribute] = []
         var attributes:[String:Any] = [:]
         var innerHTML:[CustomStringConvertible] = []
@@ -23,7 +24,20 @@ public extension HTMLKitUtilities {
         for element in children {
             if let child:LabeledExprSyntax = element.labeled {
                 if var key:String = child.label?.text {
-                    if key == "lookupFiles" {
+                    if key == "encoding" {
+                        if let key:String = child.expression.memberAccess?.declName.baseName.text {
+                            switch key {
+                                case "string": encoding = .string
+                                case "utf8Bytes": encoding = .utf8Bytes
+                                case "utf16Bytes": encoding = .utf16Bytes
+                                case "foundationData": encoding = .foundationData
+                                case "byteBuffer": encoding = .byteBuffer
+                                default: break
+                            }
+                        } else if let custom:FunctionCallExprSyntax = child.expression.functionCall {
+                            encoding = .custom(custom.arguments.first!.expression.stringLiteral!.string)
+                        }
+                    } else if key == "lookupFiles" {
                         lookupFiles = Set(child.expression.array!.elements.compactMap({ $0.expression.stringLiteral?.string }))
                     } else if key == "attributes" {
                         (global_attributes, trailingSlash) = parse_global_attributes(context: context, array: child.expression.array!.elements, lookupFiles: lookupFiles)
@@ -43,7 +57,7 @@ public extension HTMLKitUtilities {
                 }
             }
         }
-        return ElementData(global_attributes, attributes, innerHTML, trailingSlash)
+        return ElementData(encoding, global_attributes, attributes, innerHTML, trailingSlash)
     }
     // MARK: Parse Global Attributes
     static func parse_global_attributes(
@@ -144,7 +158,7 @@ public extension HTMLKitUtilities {
             default: break
         }
         for expr in interpolation {
-            string.replace("\(expr)", with: flatten_interpolation(context: context, remaining_interpolation: &remaining_interpolation, expr: expr, lookupFiles: lookupFiles))
+            string.replace("\(expr)", with: promote_interpolation(context: context, remaining_interpolation: &remaining_interpolation, expr: expr, lookupFiles: lookupFiles))
         }
         if remaining_interpolation > 0 {
             warn_interpolation(context: context, node: expression, string: &string, remaining_interpolation: &remaining_interpolation, lookupFiles: lookupFiles)
@@ -232,15 +246,15 @@ public extension HTMLKitUtilities {
         }
         return nil
     }
-    // MARK: Flatten Interpolation
-    static func flatten_interpolation(
+    // MARK: Promote Interpolation
+    static func promote_interpolation(
         context: some MacroExpansionContext,
         remaining_interpolation: inout Int,
         expr: ExpressionSegmentSyntax,
         lookupFiles: Set<String>
     ) -> String {
-        let expression:ExprSyntax = expr.expressions.first!.expression
         var string:String = "\(expr)"
+        guard let expression:ExprSyntax = expr.expressions.first?.expression else { return string }
         if let stringLiteral:StringLiteralExprSyntax = expression.stringLiteral {
             let segments:StringLiteralSegmentListSyntax = stringLiteral.segments
             if segments.count(where: { $0.is(StringSegmentSyntax.self) }) == segments.count {
@@ -252,13 +266,13 @@ public extension HTMLKitUtilities {
                     if let literal:String = segment.as(StringSegmentSyntax.self)?.content.text {
                         string += literal
                     } else if let interpolation:ExpressionSegmentSyntax = segment.as(ExpressionSegmentSyntax.self) {
-                        let flattened:String = flatten_interpolation(context: context, remaining_interpolation: &remaining_interpolation, expr: interpolation, lookupFiles: lookupFiles)
-                        if "\(interpolation)" == flattened {
-                            //string += "\\(\"\(flattened)\".escapingHTML(escapeAttributes: true))"
-                            string += "\(flattened)"
+                        let promoted:String = promote_interpolation(context: context, remaining_interpolation: &remaining_interpolation, expr: interpolation, lookupFiles: lookupFiles)
+                        if "\(interpolation)" == promoted {
+                            //string += "\\(\"\(promoted)\".escapingHTML(escapeAttributes: true))"
+                            string += "\(promoted)"
                             warn_interpolation(context: context, node: interpolation, string: &string, remaining_interpolation: &remaining_interpolation, lookupFiles: lookupFiles)
                         } else {
-                            string += flattened
+                            string += promoted
                         }
                     } else {
                         //string += "\\(\"\(segment)\".escapingHTML(escapeAttributes: true))"

Tests/HTMLKitTests/HTMLKitTests.swift

@@ -12,47 +12,46 @@ import HTMLKit
 import struct Foundation.Data
 #endif
 
-import struct NIOCore.ByteBuffer
-
 // MARK: Representations
 struct HTMLKitTests {
     func representations() {
         let _:StaticString = #html()
+        let _:StaticString = #html(encoding: .string)
         let _:String = #html()
-        let _:[UInt8] = #htmlUTF8Bytes("")
-        let _:[UInt16] = #htmlUTF16Bytes("")
-        let _:ContiguousArray<CChar> = #htmlUTF8CString("")
+        let _:String = #html(encoding: .string)
+        let _:[UInt8] = #html(encoding: .utf8Bytes, p())
+        let _:[UInt16] = #html(encoding: .utf16Bytes, p())
+        let _:ContiguousArray<CChar> = #html(encoding: .utf8CString, p())
         #if canImport(Foundation)
-        let _:Data = #htmlData("")
+        let _:Data = #html(encoding: .foundationData, p())
         #endif
-        let _:ByteBuffer = #htmlByteBuffer("")
-
-        //let bro:String = ""
-        //let _:[UInt8] = #htmlUTF8Bytes("\(bro)")
+        //let _:ByteBuffer = #html(encoding: .byteBuffer, "")
+        let _:String = #html(encoding: .custom(#"String("$0")"#), p(5))
     }
     func representation1() -> StaticString {
-        #html()
+        #html(p(123))
     }
     func representation2() -> String {
-        #html()
+        #html(p(123))
     }
     func representation3() -> [UInt8] {
-        #htmlUTF8Bytes("")
+        #html(encoding: .utf8Bytes, p(123))
     }
     func representation4() -> [UInt16] {
-        #htmlUTF16Bytes("")
+        #html(encoding: .utf16Bytes, p(123))
     }
     func representation5() -> ContiguousArray<CChar> {
-        #htmlUTF8CString("")
+        #html(encoding: .utf8CString, p(123))
     }
     #if canImport(Foundation)
     func representation5() -> Data {
-        #htmlData("")
+        #html(encoding: .foundationData, p(123))
     }
     #endif
+    /*
     func representation6() -> ByteBuffer {
         #htmlByteBuffer("")
-    }
+    }*/
 }
 
 // MARK: StaticString Example