moxml 0.1.9 → 0.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4b2faed71c75f32fcfe528621b1d3ed01c603b04f81e75d5b45b6c525d9d1836
-  data.tar.gz: 68ead788c2e5098b2f1f88653443fe4d8ff1e76b17dab09c08badb64c7ab70a3
+  metadata.gz: 07caeff68b2413d8ccaab1e827b151c4b98381f76b0f1feb63cec118be54ae05
+  data.tar.gz: 76e3eb23022b6d49e5c265467966d29d6ad12617f2a00af3b34680b32f96b8ac
 SHA512:
-  metadata.gz: 8aa59a486d44d101e1c078fc6fde2eea1cad9d4d7690d937dc7faef233a4143206432ffab53da3a2ef01af9245d17f706ddb01bc55b2c3555b358a6a3df10143
-  data.tar.gz: b5256089daef1f94012046bd7ff0fcbff1827c615b46d416231933de3193f3a262063a6ad761a87c629cdfe15fc51644fc1887d43eaeff5f8710bd16a791ea3c
+  metadata.gz: e0a41270e30bca0664d5e4bf32019d82a262cbfe6c2d001879d8e6259bf06e80a24df2372698ecd651835e88b27be2b7f2552b0d26aaf40aa514de7a870bf5e8
+  data.tar.gz: 7ade8a4b671b3eb3fe06d2b909783f61bd5172d1645e3c1e9c6344d3e3fb01b5b1c32b8da09b39fedc2b73d04e52edb19956bf00240fbb145798f4be9c598058

data/.rubocop_todo.yml

@@ -1,12 +1,12 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2025-11-24 13:45:20 UTC using RuboCop version 1.80.0.
+# on 2025-11-26 03:06:16 UTC using RuboCop version 1.80.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
-# Offense count: 192
+# Offense count: 203
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, IgnoreCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
@@ -91,7 +91,7 @@ Metrics/MethodLength:
 Metrics/ParameterLists:
   Max: 7
 
-# Offense count: 42
+# Offense count: 43
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Enabled: false

data/README.adoc

@@ -26,6 +26,8 @@ Key features:
 
 == Supported XML libraries
 
+=== General
+
 Moxml supports the following XML libraries:
 
 REXML:: https://github.com/ruby/rexml[REXML], a pure Ruby XML parser
@@ -110,7 +112,9 @@ section.
 NOTE: HeadedOx provides full XPath 1.0 support via a pure Ruby XPath engine
 layered on top of Ox's C parser. See HeadedOx documentation for details.
 
-NOTE: Ox/HeadedOx SAX: Only core events supported (start_element, end_element, characters, errors). No separate CDATA, comment, or processing instruction events.
+NOTE: Ox/HeadedOx SAX: Only core events supported (start_element, end_element,
+characters, errors). No separate CDATA, comment, or processing instruction
+events.
 
 == Adapter comparison
 
@@ -356,7 +360,7 @@ NOTE: Ox/HeadedOx SAX: Only core events supported (start_element, end_element, c
 | ✅ Full
 | ✅ Full
 | ✅ Full
-| ⚠️ Limited^4^
+| ✅ Full
 | ✅ Full
 | ✅ Full
 
@@ -400,13 +404,12 @@ NOTE: Ox/HeadedOx SAX: Only core events supported (start_element, end_element, c
 | ✅ Yes
 | ✅ Yes
 |===
-
++
 ^1^ Ox/HeadedOx: Text node replacement may fail in some cases due to internal node structure +
 ^2^ Ox: `//book[@id]` works (returns all book elements), but doesn't filter by attribute existence +
 ^3^ HeadedOx: Full XPath 1.0 with all 27 functions and 6 axes. Pure Ruby XPath engine on Ox's C parser. 99.20% pass rate. See link:docs/headed-ox.adoc[] +
 ^4^ Ox: Use `.find { |el| el["id"] == "123" }` instead of XPath attribute value predicates +
-^5^ LibXML: DOCTYPE parsing works, serialization is limited (no round-trip preservation) +
-^6^ HeadedOx limitations: Namespace introspection and 7 axes not implemented. See link:docs/HEADED_OX_LIMITATIONS.md[]
+^5^ HeadedOx limitations: Namespace introspection and 7 axes not implemented. See link:docs/HEADED_OX_LIMITATIONS.md[]
 
 === Adapter selection guide
 
@@ -453,10 +456,13 @@ NOTE: Ox/HeadedOx SAX: Only core events supported (start_element, end_element, c
 * Need more XPath capabilities than standard Ox provides
 * Memory efficiency is important but XPath features are required
 
-CAUTION: Ox's custom XPath engine supports common patterns but may not handle
+CAUTION: Ox's custom XPath engine supports common patterns but cannot handle
 complex XPath expressions. Test thoroughly if your use case requires advanced
 XPath.
 
+TODO: We should throw errors when unsupported XPath features are used with Ox
+or HeadedOx to prevent silent failures.
+
 
 == Getting started
 
@@ -643,6 +649,23 @@ For complete SAX documentation including all handler types, event methods, adapt
 
 For complete node API reference including traversal methods, manipulation, queries, type checking, and node information, see link:docs/_pages/node-api-reference.adoc[Node API Reference].
 
+=== Node identity
+
+Moxml provides a consistent `#identifier` method across all node types to safely identify nodes:
+
+[source,ruby]
+----
+element = doc.at_xpath("//book")
+puts element.identifier  # => "book"
+
+attr = element.attribute("id")
+puts attr.identifier     # => "id"
+----
+
+The `#identifier` method returns the primary identifier for each node type (tag name for elements, attribute name for attributes, target for processing instructions, or `nil` for content nodes).
+
+IMPORTANT: Always use type-safe patterns when working with mixed node types. See the link:docs/_guides/node-api-consistency.adoc[Node API Consistency Guide] for complete documentation on safe coding patterns, API surface by node type, and migration guidelines.
+
 
 == Advanced features
 
@@ -694,7 +717,8 @@ rescue Moxml::Error => e
 end
 ----
 
-For complete error class hierarchy, error types, best practices, and debugging techniques, see link:docs/_pages/error-handling.adoc[Error Handling Guide].
+For complete error class hierarchy, error types, best practices, and debugging
+techniques, see link:docs/_pages/error-handling.adoc[Error Handling Guide].
 
 
 == Configuration
@@ -717,22 +741,31 @@ context = Moxml.new do |config|
 end
 ----
 
-For all configuration options, adapter selection, serialization options, and environment-based configuration, see link:docs/_pages/configuration.adoc[Configuration Guide].
+For all configuration options, adapter selection, serialization options, and
+environment-based configuration, see
+link:docs/_pages/configuration.adoc[Configuration Guide].
 
 
 
 == Thread safety
 
-For complete information on thread-safe patterns, context management, and concurrent processing, see the link:docs/_pages/thread-safety.adoc[Thread Safety Guide].
+For complete information on thread-safe patterns, context management, and
+concurrent processing, see the link:docs/_pages/thread-safety.adoc[Thread Safety
+Guide].
 
 
 == Performance considerations
 
-For detailed performance optimization strategies, memory management best practices, and efficient querying patterns, see the link:docs/_pages/performance.adoc[Performance Considerations Guide].
+For detailed performance optimization strategies, memory management best
+practices, and efficient querying patterns, see the
+link:docs/_pages/performance.adoc[Performance Considerations Guide].
 
 == Best practices
 
-For comprehensive best practices covering XPath queries, adapter selection, error handling, namespace handling, memory management, thread safety, performance optimization, and testing strategies, see link:docs/_pages/best-practices.adoc[Best Practices Guide].
+For comprehensive best practices covering XPath queries, adapter selection,
+error handling, namespace handling, memory management, thread safety,
+performance optimization, and testing strategies, see
+link:docs/_pages/best-practices.adoc[Best Practices Guide].
 
 
 == Specific adapter limitations
@@ -756,11 +789,13 @@ The Ox adapter provides maximum parsing speed but has XPath limitations.
 doc.xpath("//book").find { |book| book["id"] == "123" }
 ----
 
-For complete Ox adapter documentation including all limitations and workarounds, see link:docs/_pages/adapters/ox.adoc[Ox Adapter Guide].
+For complete Ox adapter documentation including all limitations and workarounds,
+see link:docs/_pages/adapters/ox.adoc[Ox Adapter Guide].
 
 === HeadedOx adapter
 
-The HeadedOx adapter combines Ox's fast C-based XML parsing with Moxml's comprehensive pure Ruby XPath 1.0 engine.
+The HeadedOx adapter combines Ox's fast C-based XML parsing with Moxml's
+comprehensive pure Ruby XPath 1.0 engine.
 
 **Status:** Production-ready v1.2 (99.20% pass rate, 1,992/2,008 tests)
 
@@ -796,12 +831,6 @@ For complete HeadedOx documentation including architecture, XPath capabilities,
 
 ==== LibXML adapter
 
-*DOCTYPE Limitations:*
-
-* DOCTYPE parsing works
-* DOCTYPE round-trip preservation is limited
-* DOCTYPE cannot be reliably re-serialized after parsing
-
 *Performance:*
 
 * Serialization speed: ~120 ips (slower than target)
@@ -819,7 +848,9 @@ limitations. Use these adapters when you need full XPath and namespace support.
 
 == Development and testing
 
-For complete information on development setup, testing strategies, benchmarking, and coverage reporting, see the link:docs/_guides/development-testing.adoc[Development and Testing Guide].
+For complete information on development setup, testing strategies, benchmarking,
+and coverage reporting, see the
+link:docs/_guides/development-testing.adoc[Development and Testing Guide].
 
 == Contributing
 

data/docs/_guides/index.adoc

@@ -10,23 +10,25 @@ Task-oriented guides for common XML processing operations with Moxml.
 === Document operations
 
 link:parsing-xml[Parsing XML]::
-Parse XML from strings, files, and IO streams with different adapters.
+Parse XML from strings, files, and IO streams
 
-link:sax-parsing[SAX parsing]::
-Memory-efficient event-driven parsing for large XML files and streaming data.
+link:working-with-documents[Working with Documents]::
+Create and manipulate XML documents
 
-link:xml-declaration[XML declaration preservation]::
-Understand how Moxml preserves XML declarations for round-trip fidelity and standards compliance.
+link:modifying-xml[Modifying XML]::
+Edit elements, attributes, and content
 
-link:creating-documents[Creating documents]::
-Build XML documents from scratch using the builder pattern or direct
-manipulation.
+link:sax-parsing[SAX Parsing]::
+Memory-efficient event-driven parsing
 
-link:modifying-xml[Modifying XML]::
-Add, remove, and modify elements, attributes, and content in XML documents.
+link:advanced-features[Advanced Features]::
+Namespaces, XPath, and more
+
+link:node-api-consistency[Node API Consistency]::
+Understanding node types and their APIs
 
-link:serializing-xml[Serializing XML]::
-Convert XML documents to strings with formatting and encoding options.
+link:development-testing[Development & Testing]::
+Contributing to Moxml
 
 === Querying and traversal
 

data/docs/_guides/node-api-consistency.adoc

@@ -0,0 +1,572 @@
+= Node API consistency guide
+:toc:
+:toclevels: 3
+
+== Overview
+
+This guide documents the API surface of all node types in Moxml, providing clear
+expectations for developers about which methods are available on which node
+types.
+
+== Node Type Hierarchy
+
+[source]
+----
+Node (abstract base)
+├── Document
+├── Element
+├── Attribute
+├── Text
+├── Cdata
+├── Comment
+├── ProcessingInstruction
+├── Declaration
+└── Doctype
+----
+
+== Common Node Methods
+
+All node types inherit these methods from `Moxml::Node`:
+
+=== Document Navigation
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#document`
+| Returns the containing document
+| ✅ Yes
+
+| `#parent`
+| Returns the parent node
+| ✅ Yes
+
+| `#children`
+| Returns a NodeSet of child nodes
+| ✅ Yes (may be empty)
+
+| `#next_sibling`
+| Returns the next sibling node
+| ✅ Yes (may be nil)
+
+| `#previous_sibling`
+| Returns the previous sibling node
+| ✅ Yes (may be nil)
+|===
+
+=== Tree Manipulation
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#add_child(node)`
+| Adds a child node
+| ✅ Yes
+
+| `#add_previous_sibling(node)`
+| Adds a sibling before this node
+| ✅ Yes
+
+| `#add_next_sibling(node)`
+| Adds a sibling after this node
+| ✅ Yes
+
+| `#remove`
+| Removes this node from the tree
+| ✅ Yes
+
+| `#replace(node)`
+| Replaces this node with another
+| ✅ Yes
+|===
+
+=== Serialization
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#to_xml(options = {})`
+| Serializes node to XML string
+| ✅ Yes
+
+| `#clone` / `#dup`
+| Creates a deep copy of the node
+| ✅ Yes
+|===
+
+=== XPath Queries
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#xpath(expression, ns = {})`
+| Returns NodeSet matching XPath
+| ✅ Yes (adapter-dependent)
+
+| `#at_xpath(expression, ns = {})`
+| Returns first node matching XPath
+| ✅ Yes (adapter-dependent)
+|===
+
+=== Type Checking
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#element?`
+| Returns true if node is an Element
+| ✅ Yes
+
+| `#text?`
+| Returns true if node is a Text node
+| ✅ Yes
+
+| `#cdata?`
+| Returns true if node is a CDATA section
+| ✅ Yes
+
+| `#comment?`
+| Returns true if node is a Comment
+| ✅ Yes
+
+| `#processing_instruction?`
+| Returns true if node is a PI
+| ✅ Yes
+
+| `#document?`
+| Returns true if node is a Document
+| ✅ Yes
+
+| `#declaration?`
+| Returns true if node is a Declaration
+| ✅ Yes
+
+| `#doctype?`
+| Returns true if node is a Doctype
+| ✅ Yes
+
+| `#attribute?`
+| Returns true if node is an Attribute
+| ✅ Yes
+|===
+
+== Node Type-Specific APIs
+
+=== Document
+
+The root document node.
+
+==== Additional Methods
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#root`
+| Returns the root element
+| ✅ Yes
+
+| `#root=(element)`
+| Sets the root element
+| ✅ Yes
+
+| `#encoding`
+| Returns document encoding
+| ✅ Yes
+
+| `#create_element(name, content = nil)`
+| Creates a new element
+| ✅ Yes
+
+| `#create_text(content)`
+| Creates a new text node
+| ✅ Yes
+
+| `#create_comment(content)`
+| Creates a new comment
+| ✅ Yes
+
+| `#create_cdata(content)`
+| Creates a new CDATA section
+| ✅ Yes
+
+| `#create_processing_instruction(target, content)`
+| Creates a new processing instruction
+| ✅ Yes
+
+| `#create_declaration(version, encoding, standalone)`
+| Creates a new XML declaration
+| ✅ Yes (adapter-dependent)
+|===
+
+=== Element
+
+Elements are the primary structural nodes with tag names, attributes, and children.
+
+==== Identity Methods
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#name`
+| Returns the element tag name
+| ✅ Yes
+
+| `#name=(value)`
+| Sets the element tag name
+| ✅ Yes
+
+| `#identifier`
+| Returns the primary identifier (same as #name)
+| ✅ Yes
+|===
+
+==== Namespace Methods
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#namespace`
+| Returns the element's namespace
+| ✅ Yes (may be nil)
+
+| `#namespace=(ns_or_hash)`
+| Sets the element's namespace
+| ✅ Yes
+
+| `#namespace_prefix`
+| Returns the namespace prefix
+| ✅ Yes (may be nil)
+
+| `#namespace_uri`
+| Returns the namespace URI
+| ✅ Yes (may be nil)
+
+| `#namespaces`
+| Returns all namespace definitions
+| ✅ Yes
+
+| `#add_namespace(prefix, uri)`
+| Adds a namespace definition
+| ✅ Yes
+|===
+
+==== Attribute Methods
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#[](name)`
+| Gets attribute value
+| ✅ Yes
+
+| `#[]=(name, value)`
+| Sets attribute value
+| ✅ Yes
+
+| `#attribute(name)`
+| Returns Attribute object
+| ✅ Yes (may be nil)
+
+| `#attributes`
+| Returns array of all attributes
+| ✅ Yes
+
+| `#remove_attribute(name)`
+| Removes an attribute
+| ✅ Yes
+|===
+
+==== Content Methods
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#text`
+| Returns text content
+| ✅ Yes
+
+| `#text=(content)`
+| Sets text content
+| ✅ Yes
+
+| `#inner_text`
+| Returns inner text (concatenated)
+| ✅ Yes
+
+| `#inner_xml`
+| Returns inner XML as string
+| ✅ Yes
+
+| `#inner_xml=(xml)`
+| Sets inner XML from string
+| ✅ Yes
+|===
+
+=== Attribute
+
+Attributes are name-value pairs attached to elements.
+
+==== Identity Methods
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#name`
+| Returns the attribute name
+| ✅ Yes
+
+| `#name=(new_name)`
+| Sets the attribute name
+| ✅ Yes
+
+| `#identifier`
+| Returns the primary identifier (same as #name)
+| ✅ Yes
+|===
+
+==== Value Methods
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#value`
+| Returns the attribute value
+| ✅ Yes
+
+| `#value=(new_value)`
+| Sets the attribute value
+| ✅ Yes
+
+| `#text`
+| Alias for #value (XPath compatibility)
+| ✅ Yes
+|===
+
+==== Relationship Methods
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#element`
+| Returns the owning element
+| ✅ Yes
+
+| `#namespace`
+| Returns the attribute's namespace
+| ✅ Yes (may be nil)
+|===
+
+=== Text
+
+Text nodes contain character data.
+
+==== Content Methods
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#content`
+| Returns the text content
+| ✅ Yes
+
+| `#content=(text)`
+| Sets the text content
+| ✅ Yes
+
+| `#text`
+| Alias for #content
+| ✅ Yes
+|===
+
+==== Identity Methods
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#identifier`
+| Returns nil (content nodes have no identifier)
+| ✅ Yes
+|===
+
+=== Cdata
+
+CDATA sections contain character data that should not be parsed.
+
+==== Content Methods
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#content`
+| Returns the CDATA content
+| ✅ Yes
+
+| `#content=(text)`
+| Sets the CDATA content
+| ✅ Yes
+
+| `#text`
+| Alias for #content
+| ✅ Yes
+|===
+
+==== Identity Methods
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#identifier`
+| Returns nil (content nodes have no identifier)
+| ✅ Yes
+|===
+
+=== Comment
+
+Comment nodes contain XML comments.
+
+==== Content Methods
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#content`
+| Returns the comment text
+| ✅ Yes
+
+| `#content=(text)`
+| Sets the comment text
+| ✅ Yes
+
+| `#text`
+| Alias for #content
+| ✅ Yes
+|===
+
+==== Identity Methods
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#identifier`
+| Returns nil (content nodes have no identifier)
+| ✅ Yes
+|===
+
+=== ProcessingInstruction
+
+Processing instructions provide directives to applications.
+
+==== Identity Methods
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#target`
+| Returns the PI target
+| ✅ Yes
+
+| `#target=(new_target)`
+| Sets the PI target
+| ✅ Yes
+
+| `#identifier`
+| Returns the primary identifier (same as #target)
+| ✅ Yes
+|===
+
+==== Content Methods
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#content`
+| Returns the PI content
+| ✅ Yes
+
+| `#content=(new_content)`
+| Sets the PI content
+| ✅ Yes
+|===
+
+=== Declaration
+
+XML declarations specify document metadata.
+
+==== Property Methods
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#version`
+| Returns XML version (e.g., "1.0")
+| ✅ Yes
+
+| `#version=(new_version)`
+| Sets XML version
+| ✅ Yes
+
+| `#encoding`
+| Returns character encoding
+| ✅ Yes (may be nil)
+
+| `#encoding=(new_encoding)`
+| Sets character encoding
+| ✅ Yes
+
+| `#standalone`
+| Returns standalone status
+| ✅ Yes (may be nil)
+
+| `#standalone=(new_standalone)`
+| Sets standalone status
+| ✅ Yes
+|===
+
+==== Identity Methods
+
+[cols="1,3,1"]
+|===
+| Method | Description | Always Available?
+
+| `#identifier`
+| Returns nil (declarations have no identifier)
+| ✅ Yes
+|===
+
+=== Doctype
+
+Document type declarations specify DTD information.
+
+WARNING: Doctype accessor methods are **not fully implemented** across all adapters. The availability of these methods depends on the specific adapter being used.
+
+==== Identity Methods
+
+[cols="1,3,1"]
+|===
+|Doctype |`#name` |✅ Yes |Returns DOCTYPE name (root element)
+|Doctype |`#external_id` |✅ Yes |Returns PUBLIC identifier
+|Doctype |`#system_id` |✅ Yes |Returns SYSTEM identifier (DTD URI)
+|Doctype |`#identifier` |✅ Yes |Returns DOCTYPE name (same as `#name`)
+|===

data/docs/_guides/xml-declaration.adoc

@@ -439,12 +439,12 @@ doc.to_xml                       # Use automatic preservation
 Controls whether XML declaration is included in serialized output:
 
 * `true`: Always include declaration
-* `false`: Never include declaration  
+* `false`: Never include declaration
 * Not specified: Use `has_xml_declaration` value (automatic preservation)
 
 == See Also
 
-* link:parsing-xml.html[Parsing XML] - How to parse XML documents
-* link:modifying-xml.html[Modifying XML] - Working with parsed documents
-* link:../adapters/index.html[Adapters] - Adapter-specific behavior
-* link:../best-practices.html[Best Practices] - General XML processing guidelines
+* link:parsing-xml[Parsing XML] - How to parse XML documents
+* link:modifying-xml[Modifying XML] - Working with parsed documents
+* link:../adapters/index[Adapters] - Adapter-specific behavior
+* link:../best-practices[Best Practices] - General XML processing guidelines

data/docs/_pages/adapters/rexml.adoc

@@ -283,7 +283,7 @@ end
 === References
 
 * link:https://github.com/ruby/rexml[REXML on GitHub]
-* link:https://ruby-doc.org/stdlib/libdoc/rexml/rdoc/REXML.html[REXML documentation]
+* link:https://ruby-doc.org/stdlib/libdoc/rexml/rdoc/REXML[REXML documentation]
 
 === See also
 

data/docs/_pages/node-api-reference.adoc

@@ -1,9 +1,77 @@
 ---
-title: Node API reference
-nav_order: 5
+title: Node API Reference
+:toc:
+:toclevels: 3
 ---
 
-== Node API reference
+== Node API Reference
+
+This reference documents the API of all node types in Moxml. For a guide on API consistency and safe coding patterns, see the link:../guides/node-api-consistency[Node API Consistency Guide].
+
+== Node Identity: The #identifier Method
+
+All node types in Moxml support the `#identifier` method, which returns the primary identifier for a node:
+
+[cols="1,2,1"]
+|===
+| Node Type | #identifier Returns | Example
+
+| Element
+| The tag name
+| `"book"`, `"title"`
+
+| Attribute
+| The attribute name
+| `"id"`, `"class"`
+
+| ProcessingInstruction
+| The PI target
+| `"xml-stylesheet"`
+
+| Text, Comment, Cdata
+| `nil` (no identifier)
+| `nil`
+
+| Declaration
+| `nil` (no identifier)
+| `nil`
+
+| Document
+| `nil` (no identifier)
+| `nil`
+|===
+
+**Example usage:**
+
+[source,ruby]
+----
+element = doc.at_xpath("//book")
+puts element.identifier  # => "book"
+
+attr = element.attribute("id")
+puts attr.identifier     # => "id"
+
+pi = doc.children.find { |n| n.processing_instruction? }
+puts pi.identifier       # => "xml-stylesheet"
+
+text = element.children.find { |n| n.text? }
+puts text.identifier     # => nil
+----
+
+**Safe iteration over mixed nodes:**
+
+[source,ruby]
+----
+doc.root.children.each do |node|
+  if id = node.identifier
+    puts "#{node.class.name.split('::').last}: #{id}"
+  else
+    puts "#{node.class.name.split('::').last}: (no identifier)"
+  end
+end
+----
+
+== Common Node Methods
 
 == XML objects and their methods
 
@@ -47,3 +115,25 @@ See also:
 
 * link:../guides/working-with-documents[Working with documents guide]
 * link:../guides/advanced-features[Advanced features guide]
+=== Doctype nodes
+
+Doctype nodes represent DOCTYPE declarations in XML documents.
+
+[source,ruby]
+----
+doctype = doc.create_doctype("html", "-//W3C//DTD HTML 4.01//EN",
+                              "http://www.w3.org/TR/html4/strict.dtd")
+doctype.name         # => "html"
+doctype.external_id  # => "-//W3C//DTD HTML 4.01//EN"
+doctype.system_id    # => "http://www.w3.org/TR/html4/strict.dtd"
+doctype.identifier   # => "html"
+----
+
+*Available methods:*
+
+* `name` - Returns the DOCTYPE name (root element name)
+* `external_id` - Returns the PUBLIC identifier (or nil)
+* `system_id` - Returns the SYSTEM identifier (DTD URI, or nil)
+* `identifier` - Returns the primary identifier (same as `name`)
+
+All Doctype accessor methods are fully implemented across all 6 adapters.

data/lib/moxml/adapter/libxml.rb

@@ -788,6 +788,20 @@ module Moxml
           end
         end
 
+        # Doctype accessor methods
+        def doctype_name(native)
+          # LibXML uses DoctypeWrapper which stores the values
+          native.name
+        end
+
+        def doctype_external_id(native)
+          native.external_id
+        end
+
+        def doctype_system_id(native)
+          native.system_id
+        end
+
         def xpath(node, expression, namespaces = nil)
           native_node = unpatch_node(node)
           return [] unless native_node
@@ -1149,7 +1163,7 @@ module Moxml
           # Add namespace definitions (only on this element, not ancestors)
           if elem.respond_to?(:namespaces)
             seen_ns = {}
-            elem.namespaces.definitions.each do |ns|
+            elem.namespaces.each do |ns|
               prefix = ns.prefix
               uri = ns.href
               next if seen_ns.key?(prefix)

data/lib/moxml/adapter/nokogiri.rb

@@ -321,6 +321,19 @@ module Moxml
           node.namespace_definitions
         end
 
+        # Doctype accessor methods
+        def doctype_name(native)
+          native.name
+        end
+
+        def doctype_external_id(native)
+          native.external_id
+        end
+
+        def doctype_system_id(native)
+          native.system_id
+        end
+
         def xpath(node, expression, namespaces = nil)
           node.xpath(expression, namespaces).to_a
         rescue ::Nokogiri::XML::XPath::SyntaxError => e

data/lib/moxml/adapter/oga.rb

@@ -365,6 +365,19 @@ module Moxml
           node.namespaces.values
         end
 
+        # Doctype accessor methods
+        def doctype_name(native)
+          native.name
+        end
+
+        def doctype_external_id(native)
+          native.public_id
+        end
+
+        def doctype_system_id(native)
+          native.system_id
+        end
+
         def xpath(node, expression, namespaces = nil)
           node.xpath(expression, {},
                      namespaces: namespaces&.transform_keys(&:to_s)).to_a

data/lib/moxml/adapter/ox.rb

@@ -510,6 +510,31 @@ module Moxml
           end.values
         end
 
+        # Doctype accessor methods
+        # Ox stores DOCTYPE as a string, so we parse it
+        def doctype_name(native)
+          # Parse: "name PUBLIC \"external_id\" \"system_id\"" or "name SYSTEM \"system_id\""
+          value = native.value.to_s.strip
+          # Extract the first word (the name)
+          value.split(/\s+/).first
+        end
+
+        def doctype_external_id(native)
+          value = native.value.to_s
+          # Match PUBLIC "external_id"
+          match = value.match(/PUBLIC\s+"([^"]*)"/)
+          match ? match[1] : nil
+        end
+
+        def doctype_system_id(native)
+          value = native.value.to_s
+          # Match the last quoted string (system_id)
+          # For PUBLIC: "name PUBLIC \"external_id\" \"system_id\""
+          # For SYSTEM: "name SYSTEM \"system_id\""
+          matches = value.scan(/"([^"]*)"/)
+          matches.last&.first
+        end
+
         def xpath(node, expression, namespaces = {})
           # Translate common XPath patterns to Ox locate() syntax
           locate_expr = translate_xpath_to_locate(expression, namespaces)

data/lib/moxml/adapter/rexml.rb

@@ -426,6 +426,19 @@ module Moxml
           end
         end
 
+        # Doctype accessor methods
+        def doctype_name(native)
+          native.name
+        end
+
+        def doctype_external_id(native)
+          native.public
+        end
+
+        def doctype_system_id(native)
+          native.system
+        end
+
         # not used at the moment
         # but may be useful when the xpath is upgraded to work with namespaces
         def prepare_xpath_namespaces(node)

data/lib/moxml/attribute.rb

@@ -10,6 +10,12 @@ module Moxml
       adapter.set_attribute_name(@native, new_name)
     end
 
+    # Returns the primary identifier for this attribute (its name)
+    # @return [String] the attribute name
+    def identifier
+      name
+    end
+
     def value
       @native.value
     end

data/lib/moxml/doctype.rb

@@ -1,17 +1,50 @@
 # frozen_string_literal: true
 
 module Moxml
+  # Represents an XML DOCTYPE declaration
+  #
+  # @note Doctype accessor methods are not fully implemented across all adapters.
+  #   The availability of #name, #external_id, and #system_id depends on whether
+  #   the specific adapter implements the corresponding adapter methods:
+  #   - adapter.doctype_name(native)
+  #   - adapter.doctype_external_id(native)
+  #   - adapter.doctype_system_id(native)
+  #
+  #   Most adapters do not currently implement these methods. If you need DOCTYPE
+  #   information, consider using adapter-specific methods or parsing the serialized
+  #   XML manually.
   class Doctype < Node
+    # Returns the DOCTYPE name (root element name)
+    #
+    # @return [String, nil] the DOCTYPE name
+    # @raise [NotImplementedError] if the adapter doesn't implement doctype_name
     def name
       adapter.doctype_name(@native)
     end
 
+    # Returns the DOCTYPE external ID
+    #
+    # @return [String, nil] the external ID
+    # @raise [NotImplementedError] if the adapter doesn't implement doctype_external_id
     def external_id
       adapter.doctype_external_id(@native)
     end
 
+    # Returns the DOCTYPE system ID
+    #
+    # @return [String, nil] the system ID
+    # @raise [NotImplementedError] if the adapter doesn't implement doctype_system_id
     def system_id
       adapter.doctype_system_id(@native)
     end
+
+    # Returns the primary identifier for this doctype
+    # Since DOCTYPE information is not reliably available across adapters,
+    # this returns nil.
+    #
+    # @return [nil]
+    def identifier
+      name
+    end
   end
 end

data/lib/moxml/element.rb

@@ -13,6 +13,12 @@ module Moxml
       adapter.set_node_name(@native, value)
     end
 
+    # Returns the primary identifier for this element (its tag name)
+    # @return [String] the element name
+    def identifier
+      name
+    end
+
     # Returns the expanded name including namespace prefix
     def expanded_name
       if namespace_prefix && !namespace_prefix.empty?

data/lib/moxml/error.rb

@@ -40,7 +40,7 @@ module Moxml
       msg = super
       msg += "\n  Expression: #{@expression}" if @expression
       msg += "\n  Adapter: #{@adapter}" if @adapter
-      msg += "\n  Node: <#{@node.name}>" if @node.respond_to?(:name)
+      msg += "\n  Node: <#{@node.name}>" if @node.is_a?(Element) || @node.is_a?(Attribute)
       msg += "\n  Hint: Verify XPath syntax and ensure the adapter supports the expression"
       msg
     end
@@ -60,9 +60,9 @@ module Moxml
     def to_s
       msg = super
       # Only add extra details if any were provided
-      has_details = @node.respond_to?(:name) || @constraint || @value
+      has_details = (@node.is_a?(Element) || @node.is_a?(Attribute)) || @constraint || @value
       if has_details
-        msg += "\n  Node: <#{@node.name}>" if @node.respond_to?(:name)
+        msg += "\n  Node: <#{@node.name}>" if @node.is_a?(Element) || @node.is_a?(Attribute)
         msg += "\n  Constraint: #{@constraint}" if @constraint
         msg += "\n  Value: #{@value.inspect}" if @value
         msg += "\n  Hint: Ensure the value meets XML specification requirements"
@@ -119,7 +119,7 @@ module Moxml
 
     def to_s
       msg = super
-      msg += "\n  Node: <#{@node.name}>" if @node.respond_to?(:name)
+      msg += "\n  Node: <#{@node.name}>" if @node.is_a?(Element) || @node.is_a?(Attribute)
       msg += "\n  Adapter: #{@adapter}" if @adapter
       msg += "\n  Format: #{@format}" if @format
       msg += "\n  Hint: Check that the node structure is valid for serialization"
@@ -160,7 +160,7 @@ module Moxml
     def to_s
       msg = super
       msg += "\n  Attribute: #{@attribute_name}" if @attribute_name
-      msg += "\n  Element: <#{@element.name}>" if @element.respond_to?(:name)
+      msg += "\n  Element: <#{@element.name}>" if @element.is_a?(Element)
       msg += "\n  Value: #{@value.inspect}" if @value
       msg += "\n  Hint: Verify attribute name follows XML naming rules"
       msg

data/lib/moxml/node.rb

@@ -186,6 +186,18 @@ module Moxml
       end
     end
 
+    # Returns the primary identifier for this node type
+    # For Element: the tag name
+    # For Attribute: the attribute name
+    # For ProcessingInstruction: the target
+    # For content nodes (Text, Comment, Cdata, Declaration): nil (no identifier)
+    # For Doctype: nil (not fully implemented across adapters)
+    #
+    # @return [String, nil] the node's primary identifier or nil
+    def identifier
+      nil
+    end
+
     def self.wrap(node, context)
       return nil if node.nil?
 

data/lib/moxml/processing_instruction.rb

@@ -10,6 +10,12 @@ module Moxml
       adapter.set_node_name(@native, new_target.to_s)
     end
 
+    # Returns the primary identifier for this processing instruction (its target)
+    # @return [String] the PI target
+    def identifier
+      target
+    end
+
     def content
       adapter.processing_instruction_content(@native)
     end

data/lib/moxml/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Moxml
-  VERSION = "0.1.9"
+  VERSION = "0.1.10"
 end

data/lib/moxml/xpath/errors.rb

@@ -36,7 +36,7 @@ module Moxml
 
       def to_s
         msg = super
-        msg += "\n  Context node: <#{@context_node.name}>" if @context_node.respond_to?(:name)
+        msg += "\n  Context node: <#{@context_node.name}>" if @context_node.is_a?(Moxml::Element) || @context_node.is_a?(Moxml::Attribute)
         msg += "\n  Step: #{@step}" if @step
         msg
       end

data/spec/moxml/doctype_spec.rb

@@ -8,7 +8,6 @@ RSpec.describe Moxml::Doctype do
 
   describe "#name" do
     it "returns doctype name" do
-      skip "Doctype accessor methods not yet implemented in all adapters"
       doctype = doc.create_doctype("root", nil, "test.dtd")
       expect(doctype.name).to eq("root")
     end
@@ -16,15 +15,32 @@ RSpec.describe Moxml::Doctype do
 
   describe "#system_id" do
     it "returns system identifier" do
-      skip "Doctype accessor methods not yet implemented in all adapters"
       doctype = doc.create_doctype("root", nil, "test.dtd")
       expect(doctype.system_id).to eq("test.dtd")
     end
   end
 
+  describe "#external_id" do
+    it "returns external identifier when present" do
+      doctype = doc.create_doctype("html", "-//W3C//DTD HTML 4.01//EN", "http://www.w3.org/TR/html4/strict.dtd")
+      expect(doctype.external_id).to eq("-//W3C//DTD HTML 4.01//EN")
+    end
+
+    it "returns nil when not present" do
+      doctype = doc.create_doctype("root", nil, "test.dtd")
+      expect(doctype.external_id).to be_nil
+    end
+  end
+
+  describe "#identifier" do
+    it "returns the doctype name" do
+      doctype = doc.create_doctype("html", nil, nil)
+      expect(doctype.identifier).to eq("html")
+    end
+  end
+
   describe "creation" do
     it "creates a doctype" do
-      skip "Doctype accessor methods not yet implemented in all adapters"
       doctype = doc.create_doctype("html", nil, nil)
       expect(doctype).to be_a(described_class)
       expect(doctype.name).to eq("html")

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: moxml
 version: !ruby/object:Gem::Version
-  version: 0.1.9
+  version: 0.1.10
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-11-24 00:00:00.000000000 Z
+date: 2025-11-26 00:00:00.000000000 Z
 dependencies: []
 description: |
   Moxml is a unified XML manipulation library that provides a common API
@@ -29,7 +29,6 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".rubocop_todo.yml"
-- ".ruby-version"
 - Gemfile
 - LICENSE.md
 - README.adoc
@@ -44,6 +43,7 @@ files:
 - docs/_guides/development-testing.adoc
 - docs/_guides/index.adoc
 - docs/_guides/modifying-xml.adoc
+- docs/_guides/node-api-consistency.adoc
 - docs/_guides/parsing-xml.adoc
 - docs/_guides/sax-parsing.adoc
 - docs/_guides/working-with-documents.adoc

data/.ruby-version

@@ -1 +0,0 @@
-3.0.7@moxml