Add sourceOffset and make other minor improvements.

Author: tomasf

README.md

@@ -31,7 +31,7 @@ Then, include Nodal in the target dependencies and make sure to enable C++ inter
 ```swift
 let document = Document()
 let root = document.makeDocumentElement(name: "content", defaultNamespace: "http://tomasf.se/xml/example")
-let entry = root.appendElement("entry")
+let entry = root.addElement("entry")
 entry[attribute: "key"] = "price"
 entry.appendText("499")
 let output = try document.xmlData()
@@ -59,7 +59,7 @@ XPath is a language for querying and selecting nodes from an XML document. It al
 
 ### Example Usage
 ```swift
-let document = try Document(xmlString: """
+let document = try Document(string: """
 <catalog>
   <book id="bk101">
     <title>XML Developer's Guide</title>
@@ -70,17 +70,17 @@ let document = try Document(xmlString: """
 </catalog>
 """)
 
-if let name = query.firstNodeResult(with: document)?.node?.concatenatedText {
+if let name = query.firstNodeResult(with: document)?.node?.textContent {
     print("Book name:", name) // Outputs "XML Developer's Guide"
 }
 ```
 
-While Nodal supports XML namespaces when working with the DOM, its XPath implementation does not support XML namespaces. This limitation arises from pugixml, which lacks namespace support. To work with elements and attributes in documents that use namespaces, you must use their qualified names in your XPath expressions.
+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.
 
 ## Contributions
 
 Contributions are welcome! If you have ideas, suggestions, or improvements, feel free to open an issue or submit a pull request.
 
 ## License
 
-This project is licensed under the MIT License. See the LICENSE file for details.
+This project is licensed under the MIT License, and so is pugixml. See the respective LICENSE files for details.

Sources/Nodal/Document/Document+DocElement.swift

@@ -12,22 +12,22 @@ internal extension Document {
 }
 
 public extension Document {
-    /// The root element of the document, or `nil` if the document does not have a root element.
+    /// The document (root) element of the document, or `nil` if the document does not have a document element.
     ///
-    /// - Note: The root element is the top-level element in the document tree.
+    /// - Note: The document element is the top-level element in the document tree.
     var documentElement: Element? {
         let root = pugiDocument.__document_elementUnsafe()
         return root.empty() ? nil : element(for: root)
     }
 
-    /// Creates a new root element for the document with the specified name and optional default namespace URI.
+    /// Creates a new document (root) element for the document with the specified name and optional default namespace URI.
     ///
     /// - Parameters:
-    ///   - name: The name of the new root element.
-    ///   - uri: The default namespace URI to associate with the root element. Defaults to `nil`.
-    /// - Returns: The newly created root element.
+    ///   - name: The name of the new document element.
+    ///   - uri: The default namespace URI to associate with the document element. Defaults to `nil`.
+    /// - Returns: The newly created element.
     ///
-    /// - Note: If the document already has a root element, it is removed before creating the new one.
+    /// - Note: If the document already has a document element, it is removed before creating the new one.
     func makeDocumentElement(name: String, defaultNamespace uri: String? = nil) -> Element {
         let element = clearDocumentElement()
         element.name = name
@@ -37,14 +37,14 @@ public extension Document {
         return element
     }
 
-    /// Creates a new root element for the document using an expanded name and declares a namespace for a prefix.
+    /// Creates a new document (root) element for the document using an expanded name and declares a namespace for a prefix.
     ///
     /// - Parameters:
-    ///   - name: The expanded name of the new root element, which includes a local name and an optional namespace.
-    ///   - prefix: The prefix to declare for the namespace associated with the root element.
-    /// - Returns: The newly created root element.
+    ///   - name: The expanded name of the new document element, which includes a local name and an optional namespace.
+    ///   - prefix: The prefix to declare for the namespace associated with the document element.
+    /// - Returns: The newly created element.
     ///
-    /// - Note: If the document already has a root element, it is removed before creating the new one.
+    /// - Note: If the document already has a document element, it is removed before creating the new one.
     func makeDocumentElement(name: ExpandedName, declaringNamespaceFor prefix: String) -> Element {
         let element = clearDocumentElement()
         if let uri = name.namespaceName {

Sources/Nodal/Document/Document+Input.swift

@@ -46,9 +46,9 @@ public extension Document {
     /// - Throws: `ParseError` if the parsing fails due to malformed XML, file access issues, or other errors.
     ///
     /// - Note: This initializer reads the file from the provided URL and builds the corresponding document tree.
-    convenience init(url: URL, encoding: String.Encoding? = nil, options: ParseOptions = .default) throws(ParseError) {
+    convenience init(url fileURL: URL, encoding: String.Encoding? = nil, options: ParseOptions = .default) throws(ParseError) {
         self.init()
-        let result = url.withUnsafeFileSystemRepresentation { path in
+        let result = fileURL.withUnsafeFileSystemRepresentation { path in
             pugiDocument.load_file(path, options.rawValue, encoding?.pugiEncoding ?? pugi.encoding_auto)
         }
         if result.status != pugi.status_ok {

Sources/Nodal/Document/Error.swift

@@ -3,10 +3,13 @@ import pugixml
 
 public extension Document {
     /// Represents an error that occurs during the parsing of an XML document.
-    struct ParseError: Error {
+    struct ParseError: Error, LocalizedError {
         /// The reason for the parse failure.
         public let reason: Reason
 
+        /// A description of the error that occured.
+        public let description: String
+
         /// The character offset in the input where the error occurred.
         public let offset: Int
 
@@ -17,6 +20,7 @@ public extension Document {
             self.reason = .init(result.status)
             self.offset = result.offset
             self.encoding = .init(result.encoding)
+            self.description = String(cString: result.description())
         }
 
         /// Represents the specific reason for a parse failure.
@@ -25,43 +29,40 @@ public extension Document {
             case fileNotFound
 
             /// An I/O error occurred while reading the file or stream.
-            case ioError
+            case readError
 
             /// Memory allocation failed during parsing.
             case outOfMemory
 
-            /// An internal parser error occurred.
-            case internalError
+            /// The parser encountered a malformed tag name.
+            case badTagName
 
-            /// The parser encountered an unrecognized tag.
-            case unrecognizedTag
+            /// A start element tag was malformed.
+            case badStartElement
+
+            /// An end element tag was malformed.
+            case badEndElement
+
+            /// A mismatch occurred between a start tag and an end tag.
+            case endElementMismatch
+
+            /// An attribute was malformed.
+            case badAttribute
 
             /// A processing instruction or document declaration was malformed.
             case badProcessingInstruction
 
             /// A comment was malformed.
             case badComment
 
+            /// A text section was malformed.
+            case badText
+
             /// A CDATA section was malformed.
-            case badCData
+            case badCDATA
 
             /// A document type declaration was malformed.
-            case badDoctype
-
-            /// A PCDATA section was malformed.
-            case badPCDATA
-
-            /// A start element tag was malformed.
-            case badStartElement
-
-            /// An attribute was malformed.
-            case badAttribute
-
-            /// An end element tag was malformed.
-            case badEndElement
-
-            /// A mismatch occurred between a start tag and an end tag.
-            case endElementMismatch
+            case badDOCTYPE
 
             /// An attempt was made to append nodes to an invalid root type.
             case appendInvalidRoot
@@ -75,21 +76,21 @@ public extension Document {
             internal init(_ pugiStatus: pugi.xml_parse_status) {
                 switch pugiStatus {
                 case pugi.status_file_not_found: self = .fileNotFound
-                case pugi.status_io_error: self = .ioError
+                case pugi.status_io_error: self = .readError
                 case pugi.status_out_of_memory: self = .outOfMemory
-                case pugi.status_internal_error: self = .internalError
-                case pugi.status_unrecognized_tag: self = .unrecognizedTag
+                case pugi.status_unrecognized_tag: self = .badTagName
                 case pugi.status_bad_pi: self = .badProcessingInstruction
                 case pugi.status_bad_comment: self = .badComment
-                case pugi.status_bad_cdata: self = .badCData
-                case pugi.status_bad_doctype: self = .badDoctype
-                case pugi.status_bad_pcdata: self = .badPCDATA
+                case pugi.status_bad_cdata: self = .badCDATA
+                case pugi.status_bad_doctype: self = .badDOCTYPE
+                case pugi.status_bad_pcdata: self = .badText
                 case pugi.status_bad_start_element: self = .badStartElement
                 case pugi.status_bad_attribute: self = .badAttribute
                 case pugi.status_bad_end_element: self = .badEndElement
                 case pugi.status_end_element_mismatch: self = .endElementMismatch
                 case pugi.status_append_invalid_root: self = .appendInvalidRoot
                 case pugi.status_no_document_element: self = .noDocumentElement
+                case pugi.status_internal_error: self = .unknown
                 default: self = .unknown
                 }
             }

Sources/Nodal/Node/Node.swift

@@ -130,6 +130,17 @@ public extension Node {
             node.set_value(newValue)
         }
     }
+
+    /// The offset of this node from the beginning of the original XML buffer, if available.
+    ///
+    /// This property provides the offset in characters from the start of the XML data used to parse the document.
+    /// The offset is only available if he node was parsed from a stream or buffer and has not undergone significant changes since parsing.
+    ///
+    /// - Returns: The character offset from the beginning of the XML buffer, or `nil` if unavailable.
+    var sourceOffset: Int? {
+        let offset = node.offset_debug()
+        return offset == -1 ? nil : offset
+    }
 }
 
 internal extension Node {
@@ -151,7 +162,7 @@ extension Node: CustomDebugStringConvertible {
         case .text: "Text \"\(value)\""
         case .cdata: "CDATA \"\(value)\""
         case .comment: "Comment <!--\(value)-->"
-        case .doctype: "DOCTYPE <!DOCTYPE \(value)>"
+        case .doctype: "Document type declaration <!DOCTYPE \(value)>"
         case .processingInstruction: "PI <?\(name) \(value)?>"
         case .declaration: "Declaration <?\(name)...?>"
         case .document: "Document"

Sources/Tests/Tests.swift

@@ -163,6 +163,5 @@ struct Tests {
         #expect(Array(root.children) == [b, a], "Order of children")
         let c = root.addCDATA("c", at: .after(b))
         #expect(Array(root.children) == [b, c, a], "Order of children")
-
     }
 }