update README to include recent additions

RandomHashTags · RandomHashTags · commit bb5e2ea85e2b · 2024-10-16T11:34:50.000-05:00
diff --git a/README.md b/README.md
@@ -3,7 +3,7 @@ Write HTML using Swift Macros.
 <a href="https://swift.org"><img src="https://img.shields.io/badge/Swift-5.9+-orange" alt="Requires at least Swift 5.9"></a> <img src="https://img.shields.io/badge/Platforms-Any-gold"> <a href="https://github.com/RandomHashTags/swift-htmlkit/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue" alt="Apache 2.0 License">
 
 - [Why](#why)
-- [Examples](#examples)
+- [Usage](#usage)
   - [Basic](#basic)
   - [Advanced](#advanced)
 - [Benchmarks](#benchmarks)
@@ -17,7 +17,7 @@ Write HTML using Swift Macros.
 - Alternative libraries may not fit all situations and may restrict how the html is generated, manipulated, prone to human error, or cost a constant performance overhead (middleware, rendering, result builders, etc)
 - HTML macros enforce safety, can be used anywhere, and compile directly to strings
 - The output is minified at no performance cost
-## Examples
+## Usage
 ### Basic
 <details>
 <summary>How do I use this library?</summary>
@@ -83,6 +83,9 @@ If you know the data **at compile time** (and not working with HTML macros):
 - `#escapeHTML()` macro
 
 If you're working with **runtime** data:
+
+> \>\>\> !! You need to `import HTMLKitUtilities` to use these functions !! <<<
+
 - `<string>.escapeHTML(escapeAttributes:)`
   - mutates `self` escaping HTML and, optionally, attribute characters
 - `<string>.escapeHTMLAttributes()`
@@ -172,6 +175,19 @@ Use the `HTMLElementAttribute.event(<type>, "<value>")`.
 ```
 </details>
 
+<details>
+<summary>I need the output as a different type!</summary>
+
+Use a different html macro. Currently supported types (more to come with new language features):
+- `#html()` -> `String`/`StaticString`
+- `#htmlUTF8Bytes()` -> `[UInt8]`
+- `#htmlUTF16Bytes()` -> `[UInt16]`
+- `#htmlUTF8CString()` -> `ContiguousArray<CChar>`
+- `#htmlData()` -> `Foundation.Data`
+- `#htmlByteBuffer()` -> `NIOCore.ByteBuffer`
+
+</details>
+
 ## Benchmarks
 - Libraries tested
   - [BinaryBuilds/swift-html](https://github.com/BinaryBirds/swift-html) v1.7.0 (patched version [here](https://github.com/RandomHashTags/fork-bb-swift-html))
diff --git a/Tests/HTMLKitTests/HTMLKitTests.swift b/Tests/HTMLKitTests/HTMLKitTests.swift
@@ -16,6 +16,7 @@ import struct Foundation.Data
 import struct NIOCore.ByteBuffer
 #endif
 
+// MARK: Escaping HTML
 struct HTMLKitTests {
     @Test func escape_html() {
         let unescaped:String = "<!DOCTYPE html><html>Test</html>"
@@ -46,6 +47,7 @@ struct HTMLKitTests {
     }
 }
 
+// MARK: Representations
 extension HTMLKitTests {
     func representations() {
         let _:StaticString = #html()
@@ -90,6 +92,7 @@ extension HTMLKitTests {
     #endif
 }
 
+// MARK: Element tests
 extension HTMLKitTests {
     @Test func element_html() {
         var string:StaticString = #html()
@@ -238,6 +241,7 @@ extension HTMLKitTests {
     }
 }
 
+// MARK: Misc element tests
 extension HTMLKitTests {
     @Test func recursive_elements() {
         let string:StaticString = #div(
@@ -303,6 +307,7 @@ extension HTMLKitTests {
     }*/
 }
 
+// MARK: Attribute tests
 extension HTMLKitTests {
     @Test func attribute_data() {
         let string:StaticString = #div(attributes: [.data("id", "5")])
@@ -328,6 +333,7 @@ extension HTMLKitTests {
     }
 }
 
+// MARK: 3rd party tests
 extension HTMLKitTests {
     enum Shrek : String {
         case isLove, isLife
@@ -371,6 +377,7 @@ extension HTMLKitTests {
     }
 }
 
+// MARK: StaticString Example
 extension HTMLKitTests {
     @Test func example_1() {
         let test:StaticString = #html(
@@ -401,6 +408,7 @@ extension HTMLKitTests {
     }
 }
 
+// MARK: Dynamic test
 extension HTMLKitTests {
     @Test func dynamic() {
         let charset:String = "utf-8", title:String = "Dynamic"
@@ -429,6 +437,7 @@ extension HTMLKitTests {
     }
 }
 
+// MARK: Example2
 extension HTMLKitTests {
     @Test func example2() {
         var test:TestStruct = TestStruct(name: "one", array: ["1", "2", "3"])

Original file line number	Diff line number	Diff line change
`@@ -16,6 +16,7 @@ import struct Foundation.Data`
`16`	`16`	`import struct NIOCore.ByteBuffer`
`17`	`17`	`#endif`
`18`	`18`
	`19`	`+// MARK: Escaping HTML`
`19`	`20`	`struct HTMLKitTests {`
`20`	`21`	`@Test func escape_html() {`
`21`	`22`	`let unescaped:String = "<!DOCTYPE html><html>Test</html>"`
`@@ -46,6 +47,7 @@ struct HTMLKitTests {`
`46`	`47`	`}`
`47`	`48`	`}`
`48`	`49`
	`50`	`+// MARK: Representations`
`49`	`51`	`extension HTMLKitTests {`
`50`	`52`	`func representations() {`
`51`	`53`	`let _:StaticString = #html()`
`@@ -90,6 +92,7 @@ extension HTMLKitTests {`
`90`	`92`	`#endif`
`91`	`93`	`}`
`92`	`94`
	`95`	`+// MARK: Element tests`
`93`	`96`	`extension HTMLKitTests {`
`94`	`97`	`@Test func element_html() {`
`95`	`98`	`var string:StaticString = #html()`
`@@ -238,6 +241,7 @@ extension HTMLKitTests {`
`238`	`241`	`}`
`239`	`242`	`}`
`240`	`243`
	`244`	`+// MARK: Misc element tests`
`241`	`245`	`extension HTMLKitTests {`
`242`	`246`	`@Test func recursive_elements() {`
`243`	`247`	`let string:StaticString = #div(`
`@@ -303,6 +307,7 @@ extension HTMLKitTests {`
`303`	`307`	`}*/`
`304`	`308`	`}`
`305`	`309`
	`310`	`+// MARK: Attribute tests`
`306`	`311`	`extension HTMLKitTests {`
`307`	`312`	`@Test func attribute_data() {`
`308`	`313`	`let string:StaticString = #div(attributes: [.data("id", "5")])`
`@@ -328,6 +333,7 @@ extension HTMLKitTests {`
`328`	`333`	`}`
`329`	`334`	`}`
`330`	`335`
	`336`	`+// MARK: 3rd party tests`
`331`	`337`	`extension HTMLKitTests {`
`332`	`338`	`enum Shrek : String {`
`333`	`339`	`case isLove, isLife`
`@@ -371,6 +377,7 @@ extension HTMLKitTests {`
`371`	`377`	`}`
`372`	`378`	`}`
`373`	`379`
	`380`	`+// MARK: StaticString Example`
`374`	`381`	`extension HTMLKitTests {`
`375`	`382`	`@Test func example_1() {`
`376`	`383`	`let test:StaticString = #html(`
`@@ -401,6 +408,7 @@ extension HTMLKitTests {`
`401`	`408`	`}`
`402`	`409`	`}`
`403`	`410`
	`411`	`+// MARK: Dynamic test`
`404`	`412`	`extension HTMLKitTests {`
`405`	`413`	`@Test func dynamic() {`
`406`	`414`	`let charset:String = "utf-8", title:String = "Dynamic"`
`@@ -429,6 +437,7 @@ extension HTMLKitTests {`
`429`	`437`	`}`
`430`	`438`	`}`
`431`	`439`
	`440`	`+// MARK: Example2`
`432`	`441`	`extension HTMLKitTests {`
`433`	`442`	`@Test func example2() {`
`434`	`443`	`var test:TestStruct = TestStruct(name: "one", array: ["1", "2", "3"])`