moxml 0.1.8 → 0.1.10

data/docs/_pages/headed-ox-limitations.adoc

@@ -77,6 +77,7 @@ all_attrs = books.flat_map { |book| book.attributes.values }
 ----
 
 **Test failures:**
+
 * `spec/moxml/xpath/compiler_spec.rb:189` - Attribute axis wildcards
 * `spec/moxml/xpath/axes_spec.rb:220` - Attribute + predicate combinations
 
@@ -85,6 +86,7 @@ all_attrs = books.flat_map { |book| book.attributes.values }
 **Status:** Not implemented in HeadedOx adapter
 
 **What's missing:**
+
 * `adapter.namespace(node)` - Get primary namespace of element
 * `adapter.namespace_definitions(node)` - Get all namespace definitions
 * `node.namespace` - Access element's namespace
@@ -114,6 +116,7 @@ end
 None. These operations require Ox enhancements.
 
 **Test failures:**
+
 * `spec/integration/shared_examples/edge_cases.rb:102` - Default namespace changes
 * `spec/integration/shared_examples/edge_cases.rb:120` - Recursive namespace definitions
 * `spec/integration/shared_examples/integration_workflows.rb:98` - Complex namespace scenarios
@@ -148,6 +151,7 @@ value = attr&.value
 ----
 
 **Test failures:**
+
 * `spec/integration/shared_examples/edge_cases.rb:134` - Attributes with same local name
 
 === 4. Parent Node Setter
@@ -189,6 +193,7 @@ new_parent.add_child(node)  # Add to new parent
 **Note:** This workaround is used internally where needed, but the getter/setter syntax is not supported.
 
 **Test failures:**
+
 * `spec/integration/shared_examples/integration_workflows.rb:122` - Complex modifications
 
 === 5. CDATA End Marker Escaping
@@ -224,6 +229,7 @@ doc.create_cdata(safe_content)
 ----
 
 **Test failures:**
+
 * `spec/integration/shared_examples/edge_cases.rb:41` - CDATA nested markers
 * `spec/integration/shared_examples/node_wrappers/cdata_behavior.rb:44` - CDATA escaping
 
@@ -263,6 +269,7 @@ second_title = titles[1].text  # Works correctly
 ----
 
 **Test failures:**
+
 * `spec/moxml/adapter/headed_ox_spec.rb:77` - String functions in predicates
 * `spec/moxml/adapter/headed_ox_spec.rb:84` - Position functions
 * `spec/moxml/adapter/headed_ox_spec.rb:304` - last() function
@@ -277,6 +284,7 @@ second_title = titles[1].text  # Works correctly
 **Why it fails:**
 
 When using `//*` to select all elements, HeadedOx returns 6 elements while Nokogiri returns 7+. This is likely due to differences in:
+
 * Document node counting
 * Text node inclusion/exclusion
 * Ox's internal DOM structure
@@ -297,6 +305,7 @@ result = doc.xpath("//*")
 Use specific element names instead of wildcards.
 
 **Test failures:**
+
 * `spec/moxml/xpath/compiler_spec.rb:160` - Descendant-or-self wildcards
 
 === 8. Namespace-Aware XPath with Predicates
@@ -340,6 +349,7 @@ result = items.select { |item| item['id'] == '123' }
 ----
 
 **Test failures:**
+
 * `spec/integration/shared_examples/integration_workflows.rb:69` - XPath queries
 
 == Ox Enhancement Requirements
@@ -477,6 +487,7 @@ Ensure element counting matches other parsers' conventions when using wildcard s
 === If Ox Adds Namespace API (v1.3)
 
 With namespace methods (`namespace()`, `namespace_definitions()`):
+
 * **Target:** 99.5% pass rate
 * **Adds:** 4 more passing tests
 * **Still limited:** Parent setter, CDATA escaping, attribute wildcards
@@ -484,6 +495,7 @@ With namespace methods (`namespace()`, `namespace_definitions()`):
 === If Ox Adds Reparenting API (v1.4)
 
 With `reparent(new_parent)` method:
+
 * **Target:** 99.6% pass rate
 * **Adds:** 1 more passing test
 * **Still limited:** CDATA escaping, attribute wildcards
@@ -491,6 +503,7 @@ With `reparent(new_parent)` method:
 === If Ox Fixes CDATA Escaping (v1.5)
 
 With proper `]]>` handling:
+
 * **Target:** 99.7% pass rate
 * **Adds:** 2 more passing tests
 * **Still limited:** Attribute wildcards
@@ -498,6 +511,7 @@ With proper `]]>` handling:
 === Full Feature Parity (v2.0)
 
 Would require:
+
 * All Ox enhancements above
 * XPath parser support for `@*` wildcard
 * Investigation and fixes for text content access
@@ -546,11 +560,13 @@ Total passing: **1,992 / 2,008** (99.20%)
 HeadedOx v1.2 successfully delivers on its core promise: **fast XML parsing with comprehensive XPath support**. The 99.20% pass rate demonstrates excellent compatibility with Moxml's test suite, with the 0.80% of failures representing clear architectural boundaries in the Ox gem rather than bugs in HeadedOx.
 
 **Use HeadedOx when:**
+
 - Speed + XPath coverage matter most
 - Basic namespace queries are sufficient
 - DOM is mostly read-only
 
 **Use Nokogiri/Oga when:**
+
 - Need full namespace API
 - Heavy DOM modifications required
 - 100% feature parity is critical

data/docs/_pages/installation.adoc

@@ -1,6 +1,5 @@
 ---
 title: Installation
-parent: Overview
 nav_order: 2
 ---
 

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

@@ -1,10 +1,77 @@
 ---
-title: Node API reference
-parent: Overview
-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
 
@@ -48,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/docs/_pages/performance.adoc

@@ -1,6 +1,5 @@
 ---
 title: Performance considerations
-parent: Overview
 nav_order: 11
 ---
 

data/docs/_pages/quick-start.adoc

@@ -1,6 +1,5 @@
 ---
 title: Quick start
-parent: Overview
 nav_order: 3
 ---
 

data/docs/_pages/thread-safety.adoc

@@ -1,6 +1,5 @@
 ---
 title: Thread safety
-parent: Overview
 nav_order: 10
 ---
 

data/docs/_references/document-api.adoc

@@ -1,6 +1,5 @@
 ---
 title: Document API
-parent: Overview
 nav_order: 2
 ---
 

data/docs/_tutorials/basic-usage.adoc

@@ -1,6 +1,5 @@
 ---
 title: Basic usage
-parent: Overview
 nav_order: 2
 ---
 

data/docs/_tutorials/builder-pattern.adoc

@@ -1,6 +1,5 @@
 ---
 title: Builder pattern
-parent: Overview
 nav_order: 5
 ---
 

data/docs/_tutorials/namespace-handling.adoc

@@ -1,6 +1,5 @@
 ---
 title: Namespace handling
-parent: Overview
 nav_order: 4
 ---
 

data/docs/_tutorials/xpath-queries.adoc

@@ -1,6 +1,5 @@
 ---
 title: XPath queries
-parent: Overview
 nav_order: 3
 ---
 

data/lib/moxml/adapter/customized_rexml/formatter.rb

@@ -166,7 +166,7 @@ module Moxml
           end
 
           # Then write regular attributes
-          node.attributes.each do |name, attr|
+          node.attributes.each do |name, attr| # rubocop:disable Style/CombinableLoops
             next if name.to_s.start_with?("xmlns:") || name.to_s == "xmlns"
 
             output << " "
@@ -180,7 +180,7 @@ module Moxml
             value = attr.respond_to?(:value) ? attr.value : attr
             output << escape_attribute_value(value.to_s)
             output << "\""
-          end
+          end # rubocop:enable Style/CombinableLoops
         end
 
         def escape_attribute_value(value)

data/lib/moxml/adapter/libxml.rb

@@ -332,7 +332,13 @@ module Moxml
 
         def document(node)
           native_node = unpatch_node(node)
-          native_node&.doc
+          return nil unless native_node
+
+          # Handle documents themselves
+          return native_node if native_node.is_a?(::LibXML::XML::Document)
+
+          # For other nodes, return their document
+          native_node.doc
         end
 
         def root(document)
@@ -782,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
@@ -831,7 +851,16 @@ module Moxml
           if native_node.is_a?(::LibXML::XML::Document)
             output = +""
 
-            unless options[:no_declaration]
+            # Check if we should include declaration
+            # Priority: explicit no_declaration option > default (include)
+            should_include_decl = if options.key?(:no_declaration)
+                                    !options[:no_declaration]
+                                  else
+                                    # Default: include declaration
+                                    true
+                                  end
+
+            if should_include_decl
               # Check if declaration was explicitly managed
               if native_node.instance_variable_defined?(:@moxml_declaration)
                 decl = native_node.instance_variable_get(:@moxml_declaration)
@@ -1134,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)
@@ -1301,7 +1330,7 @@ module Moxml
           # - On child elements, output namespace definitions that override parent namespaces
           if elem.respond_to?(:namespaces) && elem.namespaces.respond_to?(:definitions)
             # Get parent's namespace definitions to detect overrides
-            parent_ns_defs = if !include_ns && elem.respond_to?(:parent) && elem.parent
+            parent_ns_defs = if !include_ns && elem.respond_to?(:parent) && elem.parent && !elem.parent.is_a?(::LibXML::XML::Document)
                                parent_namespaces = {}
                                if elem.parent.respond_to?(:namespaces)
                                  elem.parent.namespaces.each do |ns|
@@ -1444,6 +1473,7 @@ module Moxml
           node.each_child do |child|
             collect_ns_from_subtree(child, ns_defs) if child.element?
           end
+          ns_defs
         end
 
         def build_xpath_namespaces(node, user_namespaces)

data/lib/moxml/adapter/nokogiri.rb

@@ -221,6 +221,23 @@ module Moxml
         end
 
         def add_child(element, child)
+          # Special handling for declarations on Nokogiri documents
+          if element.is_a?(::Nokogiri::XML::Document) &&
+              child.is_a?(::Nokogiri::XML::ProcessingInstruction) &&
+              child.name == "xml"
+            # Set document's xml_decl property
+            version = declaration_attribute(child, "version") || "1.0"
+            encoding = declaration_attribute(child, "encoding")
+            standalone = declaration_attribute(child, "standalone")
+
+            # Nokogiri's xml_decl can only be set via instance variable
+            element.instance_variable_set(:@xml_decl, {
+              version: version,
+              encoding: encoding,
+              standalone: standalone,
+            }.compact)
+          end
+
           if node_type(child) == :doctype
             # avoid exceptions: cannot reparent Nokogiri::XML::DTD there
             element.create_internal_subset(
@@ -240,6 +257,14 @@ module Moxml
         end
 
         def remove(node)
+          # Special handling for declarations on Nokogiri documents
+          if node.is_a?(::Nokogiri::XML::ProcessingInstruction) &&
+              node.name == "xml" &&
+              node.parent.is_a?(::Nokogiri::XML::Document)
+            # Clear document's xml_decl when removing declaration
+            node.parent.instance_variable_set(:@xml_decl, nil)
+          end
+
           node.remove
         end
 
@@ -296,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
@@ -328,8 +366,18 @@ module Moxml
           if options[:indent].to_i.positive?
             save_options |= ::Nokogiri::XML::Node::SaveOptions::FORMAT
           end
-          if options[:no_declaration]
-            save_options |= ::Nokogiri::XML::Node::SaveOptions::NO_DECLARATION
+
+          # Handle declaration option
+          # Priority:
+          # 1. Explicit no_declaration option
+          # 2. Check Nokogiri's internal @xml_decl (when remove is called, this becomes nil)
+          if options.key?(:no_declaration)
+            save_options |= ::Nokogiri::XML::Node::SaveOptions::NO_DECLARATION if options[:no_declaration]
+          elsif node.respond_to?(:instance_variable_get) &&
+              node.instance_variable_defined?(:@xml_decl)
+            # Nokogiri's internal state - if nil, declaration was removed
+            xml_decl = node.instance_variable_get(:@xml_decl)
+            save_options |= ::Nokogiri::XML::Node::SaveOptions::NO_DECLARATION if xml_decl.nil?
           end
 
           node.to_xml(

data/lib/moxml/adapter/oga.rb

@@ -10,7 +10,10 @@ module Moxml
     class Oga < Base
       class << self
         def set_root(doc, element)
-          doc.children.clear # Clear any existing children
+          # Clear existing root element if any - Oga's NodeSet needs special handling
+          # We need to manually remove elements since NodeSet doesn't support clear or delete_if
+          elements_to_remove = doc.children.select { |child| child.is_a?(::Oga::XML::Element) }
+          elements_to_remove.each { |elem| doc.children.delete(elem) }
           doc.children << element
         end
 
@@ -247,6 +250,13 @@ module Moxml
               child_or_text
             end
 
+          # Special handling for declarations on Oga documents
+          if element.is_a?(::Oga::XML::Document) &&
+              child.is_a?(::Oga::XML::XmlDeclaration)
+            # Set as document's xml_declaration
+            element.instance_variable_set(:@xml_declaration, child)
+          end
+
           element.children << child
         end
 
@@ -273,6 +283,13 @@ module Moxml
         end
 
         def remove(node)
+          # Special handling for declarations on Oga documents
+          if node.is_a?(::Oga::XML::XmlDeclaration) &&
+              node.parent.is_a?(::Oga::XML::Document)
+            # Clear document's xml_declaration when removing declaration
+            node.parent.instance_variable_set(:@xml_declaration, nil)
+          end
+
           node.remove
         end
 
@@ -348,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
@@ -371,8 +401,55 @@ module Moxml
           )
         end
 
-        def serialize(node, _options = {})
-          # Expand empty tags, encode attributes, etc
+        def serialize(node, options = {})
+          # Oga's XmlGenerator doesn't support options directly
+          # We need to handle declaration options ourselves for Document nodes
+          if node.is_a?(::Oga::XML::Document)
+            # Check if we should include declaration
+            # Priority: explicit option > existence of xml_declaration node
+            should_include_decl = if options.key?(:no_declaration)
+                                    !options[:no_declaration]
+                                  elsif options.key?(:declaration)
+                                    options[:declaration]
+                                  else
+                                    # Default: include if document has xml_declaration node
+                                    node.xml_declaration ? true : false
+                                  end
+
+            if should_include_decl && !node.xml_declaration
+              # Need to add declaration - create default one
+              output = +""
+              output << '<?xml version="1.0" encoding="UTF-8"?>'
+              output << "\n"
+
+              # Serialize doctype if present
+              output << node.doctype.to_xml << "\n" if node.doctype
+
+              # Serialize children
+              node.children.each do |child|
+                output << ::Moxml::Adapter::CustomizedOga::XmlGenerator.new(child).to_xml
+              end
+
+              return output
+            elsif !should_include_decl
+              # Skip xml_declaration
+              output = +""
+
+              # Serialize doctype if present
+              output << node.doctype.to_xml << "\n" if node.doctype
+
+              # Serialize root and other children
+              node.children.each do |child|
+                next if child.is_a?(::Oga::XML::XmlDeclaration)
+
+                output << ::Moxml::Adapter::CustomizedOga::XmlGenerator.new(child).to_xml
+              end
+
+              return output
+            end
+          end
+
+          # Default: use XmlGenerator
           ::Moxml::Adapter::CustomizedOga::XmlGenerator.new(node).to_xml
         end
       end