refactor and organize

add readme

Author: antoinepalazzolo

.swiftpm/xcode/xcshareddata/xcschemes/HTMLBuilder.xcscheme

@@ -0,0 +1,101 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Scheme
+   LastUpgradeVersion = "1230"
+   version = "1.3">
+   <BuildAction
+      parallelizeBuildables = "YES"
+      buildImplicitDependencies = "YES">
+      <BuildActionEntries>
+         <BuildActionEntry
+            buildForTesting = "YES"
+            buildForRunning = "YES"
+            buildForProfiling = "YES"
+            buildForArchiving = "YES"
+            buildForAnalyzing = "YES">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "HTMLBuilder"
+               BuildableName = "HTMLBuilder"
+               BlueprintName = "HTMLBuilder"
+               ReferencedContainer = "container:">
+            </BuildableReference>
+         </BuildActionEntry>
+         <BuildActionEntry
+            buildForTesting = "YES"
+            buildForRunning = "YES"
+            buildForProfiling = "NO"
+            buildForArchiving = "NO"
+            buildForAnalyzing = "YES">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "HTMLBuilderTests"
+               BuildableName = "HTMLBuilderTests"
+               BlueprintName = "HTMLBuilderTests"
+               ReferencedContainer = "container:">
+            </BuildableReference>
+         </BuildActionEntry>
+      </BuildActionEntries>
+   </BuildAction>
+   <TestAction
+      buildConfiguration = "Debug"
+      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
+      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      shouldUseLaunchSchemeArgsEnv = "YES"
+      codeCoverageEnabled = "YES">
+      <CodeCoverageTargets>
+         <BuildableReference
+            BuildableIdentifier = "primary"
+            BlueprintIdentifier = "HTMLBuilder"
+            BuildableName = "HTMLBuilder"
+            BlueprintName = "HTMLBuilder"
+            ReferencedContainer = "container:">
+         </BuildableReference>
+      </CodeCoverageTargets>
+      <Testables>
+         <TestableReference
+            skipped = "NO">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "HTMLBuilderTests"
+               BuildableName = "HTMLBuilderTests"
+               BlueprintName = "HTMLBuilderTests"
+               ReferencedContainer = "container:">
+            </BuildableReference>
+         </TestableReference>
+      </Testables>
+   </TestAction>
+   <LaunchAction
+      buildConfiguration = "Debug"
+      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
+      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      launchStyle = "0"
+      useCustomWorkingDirectory = "NO"
+      ignoresPersistentStateOnLaunch = "NO"
+      debugDocumentVersioning = "YES"
+      debugServiceExtension = "internal"
+      allowLocationSimulation = "YES">
+   </LaunchAction>
+   <ProfileAction
+      buildConfiguration = "Release"
+      shouldUseLaunchSchemeArgsEnv = "YES"
+      savedToolIdentifier = ""
+      useCustomWorkingDirectory = "NO"
+      debugDocumentVersioning = "YES">
+      <MacroExpansion>
+         <BuildableReference
+            BuildableIdentifier = "primary"
+            BlueprintIdentifier = "HTMLBuilder"
+            BuildableName = "HTMLBuilder"
+            BlueprintName = "HTMLBuilder"
+            ReferencedContainer = "container:">
+         </BuildableReference>
+      </MacroExpansion>
+   </ProfileAction>
+   <AnalyzeAction
+      buildConfiguration = "Debug">
+   </AnalyzeAction>
+   <ArchiveAction
+      buildConfiguration = "Release"
+      revealArchiveInOrganizer = "YES">
+   </ArchiveAction>
+</Scheme>

README.md

@@ -1,3 +1,99 @@
 # HTMLBuilder
 
-A description of this package.
+Swift library for generating HTML using  [Result Builder](https://github.com/apple/swift-evolution/blob/main/proposals/0289-result-builders.md)
+
+# Features
+
+- Clean & clear syntax
+- Composable & extensible
+- Conditional and iteration support
+- Underlying generation with libxml2 for always valid results
+- Built-in convenient builders and modifiers for common cases
+- Raw HTML integration
+
+# Usage
+
+## Tree builder
+
+An HTML tree is built by combining `Node` which is a protocol implemented on `Element` and `String`
+
+```swift
+let tree = Element.html(head: {
+    Element.metadata(charset: "UTF-8")
+    Element(name: "title") { "Hello world" }
+}, body: {
+    Element.division {
+        Element(name: "h1") { "Hello" }
+        Element.paragraph { "Lorem ipsum dolor sit amet, <consectetur> adipiscing elit, sed & eiusmod." }
+    }
+})
+print(tree.renderHTML())
+```
+Will output:
+```html
+<html><head><meta charset="UTF-8"><title>Hello world</title></head><body><div><h1>Hello</h1><p>Lorem ipsum dolor sit amet, &lt;consectetur&gt; adipiscing&nbsp;elit, sed &amp; eiusmod.</p></div></body></html>
+```
+
+## Condition and Iteration
+Conditions (`if`, `if else`, `switch`) and iterations (`for ... in`) will work the same as imperative control-flow.
+
+```swift
+let cond1 = true
+let cond2 = false
+let elements = ["Lorem", "ipsum"]
+let treeControlFlow = Element.html(head: {
+    Element.metadata(charset: "UTF-8")
+    Element(name: "title") { "Hello world" }
+}, body: {
+    Element.division {
+        if cond1 {
+            Element(name: "h1") { "Hello" }
+        }
+        if cond2 {
+            Element(name: "h1") { "Hello" }
+        } else {
+            Element(name: "h1") { "world" }
+        }
+        ForEach(elements) { el in
+            Element.paragraph { el }
+        }
+    }
+})
+print(treeControlFlow.renderHTML())
+```
+Will output:
+```html
+<html><head><meta charset="UTF-8"><title>Hello world</title></head><body><div><h1>Hello</h1><h1>world</h1><p>Lorem</p><p>ipsum</p></div></body></html>
+```
+
+## Modifiers
+
+`Element` is modifiable while building the tree. 
+There is 2 built in modifiers, `identifier` and `class`
+
+```swift
+let modifierTree = Element.division {
+    Element.paragraph { "Hello world" }.identifier("title")
+}.class("container")
+print(modifierTree.renderHTML())
+```
+
+Will output:
+```html
+<div class="container"><p id="title">Hello world</p></div>
+```
+
+## Raw HTML
+You can include raw html in the tree with `RawHTML` 
+```swift
+let rawHTMLTree = try Element.division {
+    try RawHTML("""
+        <h1>hello world</h1>
+        <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit</p>
+        """)
+}
+```
+Will output:
+```html
+<div><h1>hello world</h1><p>Lorem ipsum dolor sit amet, consectetur adipiscing elit</p></div>
+```

Sources/HTMLBuilder/ConvenientElementBuilders.swift

@@ -0,0 +1,58 @@
+//
+//  ConvenientElementBuilders.swift
+//  
+//
+//  Created by Antoine Palazzolo on 18/12/2020.
+//
+
+import Foundation
+
+extension Element {
+    
+    public static func division(@NodeBuilder content: () throws -> [Node]) rethrows -> Self {
+        try Self(name: "div", children: content)
+    }
+    public static func image(_ url: URL) -> Self {
+        Self(name: "img", attributes: [.source: url.absoluteString])
+    }
+    public static func paragraph(@NodeBuilder content: () throws -> [Node]) rethrows -> Self {
+        try Self(name: "p", children: content)
+    }
+    public static func button(_ title: String) -> Self {
+        Self(name: "button", attributes: [.type: "button"]) {
+            title
+        }
+    }
+    public static func html(@NodeBuilder head: () throws -> [Node], @NodeBuilder body: () throws -> [Node]) rethrows -> Self {
+        try Self(name: "html") {
+            try Self(name: "head", children: head)
+            try Self(name: "body", children: body)
+        }
+    }
+    public static func cssLink(_ url: URL) -> Self {
+        Self(name: "link", attributes: [.relationship: "stylesheet", .type: "text/css", .hypertextReference: url.absoluteString])
+    }
+    public static func javascript(_ script: String) -> Self {
+        Self(name: "script", attributes: [.type: "application/javascript"]) {
+            script
+        }
+    }
+    public static func metadata(name: String, content: String) -> Self {
+        Self.init(name: "meta", attributes: ["name": name, "content": content])
+    }
+    public static func metadata(httpEquivalent: String, content: String) -> Self {
+        Self.init(name: "meta", attributes: ["http-equiv": httpEquivalent, "content": content])
+    }
+    public static func metadata(charset: String) -> Self {
+        Self.init(name: "meta", attributes: ["charset": charset])
+    }
+}
+
+extension Element.AttributeName {
+    public static let identifier = Self(rawValue: "id")
+    public static let `class` = Self(rawValue: "class")
+    public static let hypertextReference = Self(rawValue: "href")
+    public static let type = Self(rawValue: "type")
+    public static let source = Self(rawValue: "src")
+    public static let relationship = Self(rawValue: "rel")
+}

Sources/HTMLBuilder/Element.swift

@@ -0,0 +1,60 @@
+//
+//  Element.swift
+//  
+//
+//  Created by Antoine Palazzolo on 18/12/2020.
+//
+
+import Foundation
+import libxml2
+
+public struct Element: Node {
+    public var name: String
+    public var attributes: [AttributeName: AttributeValue]
+    public var children: [Node]
+    
+    public func asXMLNode() -> xmlNodePtr {
+        guard let node = xmlNewNode(nil, self.name) else { fatalError("node allocation failed") }
+        for (attrName, attrValue) in self.attributes.sorted(by: { $0.key.rawValue < $1.key.rawValue }) {
+            xmlNewProp(node, attrName.rawValue, attrValue)
+        }
+        for child in self.children {
+            xmlAddChild(node, child.asXMLNode())
+        }
+        return node
+    }
+    public func isEqual(to other: Node) -> Bool {
+        if let other = other as? Element {
+            if self.name != other.name { return false }
+            if self.attributes != other.attributes { return false }
+            if self.children.count != other.children.count { return false }
+            if zip(self.children, other.children).allSatisfy({ $0.0.isEqual(to: $0.1) }) == false { return false }
+            return true
+        }
+        return false
+    }
+    
+    public init(name: String, attributes: [AttributeName: AttributeValue], children: [Node]) {
+        self.name = name
+        self.attributes = attributes
+        self.children = children
+    }
+    public init(name: String, attributes: [AttributeName: AttributeValue] = [:], @NodeBuilder children: () throws -> [Node]) rethrows {
+        self.init(name: name, attributes: attributes, children: try children())
+    }
+    public init(name: String, attributes: [AttributeName: AttributeValue] = [:]) {
+        self.init(name: name, attributes: attributes, children: [])
+    }
+}
+extension Element {
+    public struct AttributeName: RawRepresentable, Hashable, ExpressibleByStringLiteral {
+        public var rawValue: String
+        public init(rawValue: String) {
+            self.rawValue = rawValue
+        }
+        public init(stringLiteral value: String) {
+            self.init(rawValue: value)
+        }
+    }
+    public typealias AttributeValue = String?
+}

Sources/HTMLBuilder/ElementModifiers.swift

@@ -0,0 +1,22 @@
+//
+//  ElementModifiers.swift
+//  
+//
+//  Created by Antoine Palazzolo on 18/12/2020.
+//
+
+import Foundation
+
+extension Element {
+    public func identifier(_ identifier: String?) -> Self {
+        var result = self
+        result.attributes[.identifier] = identifier
+        return result
+    }
+    
+    public func `class`(_ class: String?) -> Self {
+        var result = self
+        result.attributes[.class] = `class`
+        return result
+    }
+}