Merge branch 'dev'

Author: tomasf

README.md

@@ -12,7 +12,7 @@ Add Nodal as a dependency in your `Package.swift`:
 
 ```swift
 dependencies: [
-    .package(url: "https://github.com/tomasf/Nodal.git", .upToNextMinor(from: "0.3.0"))
+    .package(url: "https://github.com/tomasf/Nodal.git", from: "1.0.0")
 ]
 ```
 
@@ -78,13 +78,71 @@ let document = try Document(string: """
 </catalog>
 """)
 
-if let name = query.firstNodeResult(with: document)?.node?.textContent {
-    print("Book name:", name) // Outputs "XML Developer's Guide"
+let query = try XPathQuery("//book[@id='bk101']/title")
+if let title = query.firstNodeResult(with: document)?.node?.textContent {
+    print("Book title:", title) // Outputs "XML Developer's Guide"
 }
 ```
 
 While Nodal supports XML namespaces when working with the DOM, its XPath implementation does not support namespaces. This limitation arises from pugixml. To work with elements and attributes in documents that use namespaces, you must use their qualified names in your XPath expressions.
 
+## Value Serialization
+
+Nodal provides protocols for serializing Swift values to and from XML. The `XMLValueCodable` protocol handles encoding and decoding values as strings (for attributes and text content), while `XMLElementCodable` handles encoding and decoding entire elements.
+
+### Built-in Type Support
+
+Common types like `Int`, `Double`, `Bool`, `String`, `UUID`, `URL`, `Date`, and `Data` conform to `XMLValueCodable` out of the box:
+
+```swift
+let root = document.makeDocumentElement(name: "item")
+root.setValue(42, forAttribute: "count")
+root.setValue(UUID(), forAttribute: "id")
+root.setValue(Date.now, forAttribute: "created")
+
+let count: Int = try root.value(forAttribute: "count")
+```
+
+### Configurable Formats
+
+You can configure how `Date` and `Data` values are serialized by setting properties on the document:
+
+```swift
+document.dateFormat = .iso8601              // Default, e.g. "2024-01-15T10:30:00Z"
+document.dateFormat = .secondsSince1970     // Unix timestamp
+document.dateFormat = .millisecondsSince1970
+
+document.dataFormat = .base64               // Default
+document.dataFormat = .hex                  // Hexadecimal encoding
+```
+
+### Custom Types
+
+Conform your own types to `XMLValueCodable` for string-based serialization, or `XMLElementCodable` for element-based serialization:
+
+```swift
+struct Point: XMLValueCodable {
+    var x: Double
+    var y: Double
+
+    func xmlStringValue(for node: Node) -> String {
+        "\(x),\(y)"
+    }
+
+    init(xmlStringValue: String, for node: Node) throws {
+        let parts = xmlStringValue.split(separator: ",")
+        guard parts.count == 2,
+              let x = Double(parts[0]),
+              let y = Double(parts[1])
+        else {
+            throw XMLValueError.invalidFormat(expected: "x,y", found: xmlStringValue)
+        }
+        self.x = x
+        self.y = y
+    }
+}
+```
+
 ## Contributions
 
 Contributions are welcome! If you have ideas, suggestions, or improvements, feel free to open an issue or submit a pull request.

Sources/Nodal/Codable/Value/Foundation+XMLValueCodable.swift

@@ -1,14 +1,14 @@
 import Foundation
 
 extension String: XMLValueCodable {
-    public var xmlStringValue: String { self }
-    public init(xmlStringValue: String) throws { self = xmlStringValue }
+    public func xmlStringValue(for node: Node) -> String { self }
+    public init(xmlStringValue: String, for node: Node) throws { self = xmlStringValue }
 }
 
 extension Bool: XMLValueCodable {
-    public var xmlStringValue: String { self ? "true" : "false" }
+    public func xmlStringValue(for node: Node) -> String { self ? "true" : "false" }
 
-    public init(xmlStringValue: String) throws {
+    public init(xmlStringValue: String, for node: Node) throws {
         switch xmlStringValue {
         case "true", "1": self = true
         case "false", "0": self = false
@@ -18,9 +18,9 @@ extension Bool: XMLValueCodable {
 }
 
 extension Double: XMLValueCodable {
-    public var xmlStringValue: String { String(self) }
+    public func xmlStringValue(for node: Node) -> String { String(self) }
 
-    public init(xmlStringValue: String) throws {
+    public init(xmlStringValue: String, for node: Node) throws {
         guard let double = Double(xmlStringValue) else {
             throw XMLValueError.invalidFormat(expected: "Double", found: xmlStringValue)
         }
@@ -29,9 +29,9 @@ extension Double: XMLValueCodable {
 }
 
 extension Float: XMLValueCodable {
-    public var xmlStringValue: String { String(self) }
+    public func xmlStringValue(for node: Node) -> String { String(self) }
 
-    public init(xmlStringValue: String) throws {
+    public init(xmlStringValue: String, for node: Node) throws {
         guard let float = Float(xmlStringValue) else {
             throw XMLValueError.invalidFormat(expected: "Float", found: xmlStringValue)
         }
@@ -40,9 +40,9 @@ extension Float: XMLValueCodable {
 }
 
 extension Int: XMLValueCodable {
-    public var xmlStringValue: String { String(self) }
+    public func xmlStringValue(for node: Node) -> String { String(self) }
 
-    public init(xmlStringValue: String) throws {
+    public init(xmlStringValue: String, for node: Node) throws {
         guard let int = Int(xmlStringValue) else {
             throw XMLValueError.invalidFormat(expected: "Int", found: xmlStringValue)
         }
@@ -51,9 +51,9 @@ extension Int: XMLValueCodable {
 }
 
 extension Int8: XMLValueCodable {
-    public var xmlStringValue: String { String(self) }
+    public func xmlStringValue(for node: Node) -> String { String(self) }
 
-    public init(xmlStringValue: String) throws {
+    public init(xmlStringValue: String, for node: Node) throws {
         guard let value = Int8(xmlStringValue) else {
             throw XMLValueError.invalidFormat(expected: "Int8", found: xmlStringValue)
         }
@@ -62,9 +62,9 @@ extension Int8: XMLValueCodable {
 }
 
 extension Int16: XMLValueCodable {
-    public var xmlStringValue: String { String(self) }
+    public func xmlStringValue(for node: Node) -> String { String(self) }
 
-    public init(xmlStringValue: String) throws {
+    public init(xmlStringValue: String, for node: Node) throws {
         guard let value = Int16(xmlStringValue) else {
             throw XMLValueError.invalidFormat(expected: "Int16", found: xmlStringValue)
         }
@@ -73,9 +73,9 @@ extension Int16: XMLValueCodable {
 }
 
 extension Int32: XMLValueCodable {
-    public var xmlStringValue: String { String(self) }
+    public func xmlStringValue(for node: Node) -> String { String(self) }
 
-    public init(xmlStringValue: String) throws {
+    public init(xmlStringValue: String, for node: Node) throws {
         guard let value = Int32(xmlStringValue) else {
             throw XMLValueError.invalidFormat(expected: "Int32", found: xmlStringValue)
         }
@@ -84,9 +84,9 @@ extension Int32: XMLValueCodable {
 }
 
 extension Int64: XMLValueCodable {
-    public var xmlStringValue: String { String(self) }
+    public func xmlStringValue(for node: Node) -> String { String(self) }
 
-    public init(xmlStringValue: String) throws {
+    public init(xmlStringValue: String, for node: Node) throws {
         guard let value = Int64(xmlStringValue) else {
             throw XMLValueError.invalidFormat(expected: "Int64", found: xmlStringValue)
         }
@@ -95,9 +95,9 @@ extension Int64: XMLValueCodable {
 }
 
 extension UInt: XMLValueCodable {
-    public var xmlStringValue: String { String(self) }
+    public func xmlStringValue(for node: Node) -> String { String(self) }
 
-    public init(xmlStringValue: String) throws {
+    public init(xmlStringValue: String, for node: Node) throws {
         guard let value = UInt(xmlStringValue) else {
             throw XMLValueError.invalidFormat(expected: "UInt", found: xmlStringValue)
         }
@@ -106,9 +106,9 @@ extension UInt: XMLValueCodable {
 }
 
 extension UInt8: XMLValueCodable {
-    public var xmlStringValue: String { String(self) }
+    public func xmlStringValue(for node: Node) -> String { String(self) }
 
-    public init(xmlStringValue: String) throws {
+    public init(xmlStringValue: String, for node: Node) throws {
         guard let value = UInt8(xmlStringValue) else {
             throw XMLValueError.invalidFormat(expected: "UInt8", found: xmlStringValue)
         }
@@ -117,9 +117,9 @@ extension UInt8: XMLValueCodable {
 }
 
 extension UInt16: XMLValueCodable {
-    public var xmlStringValue: String { String(self) }
+    public func xmlStringValue(for node: Node) -> String { String(self) }
 
-    public init(xmlStringValue: String) throws {
+    public init(xmlStringValue: String, for node: Node) throws {
         guard let value = UInt16(xmlStringValue) else {
             throw XMLValueError.invalidFormat(expected: "UInt16", found: xmlStringValue)
         }
@@ -128,9 +128,9 @@ extension UInt16: XMLValueCodable {
 }
 
 extension UInt32: XMLValueCodable {
-    public var xmlStringValue: String { String(self) }
+    public func xmlStringValue(for node: Node) -> String { String(self) }
 
-    public init(xmlStringValue: String) throws {
+    public init(xmlStringValue: String, for node: Node) throws {
         guard let value = UInt32(xmlStringValue) else {
             throw XMLValueError.invalidFormat(expected: "UInt32", found: xmlStringValue)
         }
@@ -139,9 +139,9 @@ extension UInt32: XMLValueCodable {
 }
 
 extension UInt64: XMLValueCodable {
-    public var xmlStringValue: String { String(self) }
+    public func xmlStringValue(for node: Node) -> String { String(self) }
 
-    public init(xmlStringValue: String) throws {
+    public init(xmlStringValue: String, for node: Node) throws {
         guard let value = UInt64(xmlStringValue) else {
             throw XMLValueError.invalidFormat(expected: "UInt64", found: xmlStringValue)
         }
@@ -150,25 +150,56 @@ extension UInt64: XMLValueCodable {
 }
 
 extension UUID: XMLValueCodable {
-    public var xmlStringValue: String { uuidString }
+    public func xmlStringValue(for node: Node) -> String { uuidString }
 
-    public init(xmlStringValue: String) throws {
+    public init(xmlStringValue: String, for node: Node) throws {
         guard let value = UUID(uuidString: xmlStringValue) else {
             throw XMLValueError.invalidFormat(expected: "UUID", found: xmlStringValue)
         }
         self = value
     }
 }
 
+extension URL: XMLValueCodable {
+    public func xmlStringValue(for node: Node) -> String { absoluteString }
+
+    public init(xmlStringValue: String, for node: Node) throws {
+        guard let url = URL(string: xmlStringValue) else {
+            throw XMLValueError.invalidFormat(expected: "URL", found: xmlStringValue)
+        }
+        self = url
+    }
+}
+
+extension Date: XMLValueCodable {
+    public func xmlStringValue(for node: Node) -> String {
+        node.document.dateFormat.encode(self)
+    }
+
+    public init(xmlStringValue: String, for node: Node) throws {
+        self = try node.document.dateFormat.decode(xmlStringValue)
+    }
+}
+
+extension Data: XMLValueCodable {
+    public func xmlStringValue(for node: Node) -> String {
+        node.document.dataFormat.encode(self)
+    }
+
+    public init(xmlStringValue: String, for node: Node) throws {
+        self = try node.document.dataFormat.decode(xmlStringValue)
+    }
+}
+
 extension RawRepresentable where RawValue: XMLValueEncodable {
-    public var xmlStringValue: String {
-        rawValue.xmlStringValue
+    public func xmlStringValue(for node: Node) -> String {
+        rawValue.xmlStringValue(for: node)
     }
 }
 
 extension RawRepresentable where RawValue: XMLValueDecodable {
-    public init(xmlStringValue string: String) throws {
-        let raw = try RawValue(xmlStringValue: string)
+    public init(xmlStringValue string: String, for node: Node) throws {
+        let raw = try RawValue(xmlStringValue: string, for: node)
         guard let value = Self(rawValue: raw) else {
             throw XMLValueError.invalidFormat(expected: "\(String(describing: Self.self))", found: string)
         }