moxml 0.1.8 → 0.1.9

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

@@ -1,12 +1,12 @@
 ---
-title: HeadedOx adapter
+title: HeadedOx
 parent: Adapters
 nav_order: 6
 ---
 
-=== HeadedOx adapter
+== HeadedOx adapter
 
-==== General
+=== General
 
 The HeadedOx adapter combines Ox's fast C-based XML parsing with Moxml's
 comprehensive pure Ruby XPath 1.0 engine.
@@ -39,7 +39,7 @@ cheap = doc.xpath('//book[@price <= sum(//book/@price) div count(//book)]')
 IMPORTANT: For complete XPath 1.0 specification with zero limitations today, use
 Nokogiri or Oga adapters.
 
-==== Features
+=== Features
 
 * Fast XML parsing (Ox C extension) - Same speed as standard Ox
 * 6 of 13 XPath axes (46% - covers 80% of common usage patterns)
@@ -48,7 +48,7 @@ Nokogiri or Oga adapters.
 * Expression compilation and caching (1000-entry LRU cache)
 * Document construction and serialization through Ox
 
-==== Architecture
+=== Architecture
 
 HeadedOx is a **hybrid adapter** that layers Moxml's pure Ruby XPath engine on
 top of Ox's fast C parser:
@@ -78,7 +78,7 @@ top of Ox's fast C parser:
              └─────────────────────────┘
 ----
 
-==== Known limitations
+=== Known limitations
 
 The following 16 test failures represent architectural boundaries in the Ox gem,
 not bugs in HeadedOx:
@@ -100,7 +100,7 @@ See link:docs/HEADED_OX_LIMITATIONS.md[HEADED_OX_LIMITATIONS.md] for:
 * When to use HeadedOx vs other adapters decision guide
 * Future roadmap if Ox adds namespace introspection API
 
-==== When to Use HeadedOx
+=== When to Use HeadedOx
 
 You can use HeadedOx instead of Ox for all XML parsing needs, except when
 certain advanced XPath features are required.
@@ -126,7 +126,7 @@ link:docs/headed-ox.adoc[HeadedOx Implementation Guide] and
 link:docs/HEADED_OX_LIMITATIONS.md[HeadedOx Limitations Documentation].
 
 
-==== XPath capabilities
+=== XPath capabilities
 
 [cols="1,1,4"]
 |===
@@ -169,7 +169,7 @@ operator predicates, complex nested expressions
 |===
 
 
-==== What XPath queries work in HeadedOx
+=== What XPath queries work in HeadedOx
 
 NOTE: This table is of v0.2.0.
 

data/docs/_pages/adapters/index.adoc

@@ -1,6 +1,5 @@
 ---
 title: Adapters
-parent: Overview
 nav_order: 5
 has_children: true
 ---

data/docs/_pages/adapters/libxml.adoc

@@ -1,7 +1,6 @@
 ---
-title: LibXML adapter
+title: LibXML
 parent: Adapters
-grand_parent: Overview
 nav_order: 2
 ---
 

data/docs/_pages/adapters/nokogiri.adoc

@@ -1,7 +1,6 @@
 ---
-title: Nokogiri adapter
+title: Nokogiri
 parent: Adapters
-grand_parent: Overview
 nav_order: 1
 ---
 

data/docs/_pages/adapters/oga.adoc

@@ -1,7 +1,6 @@
 ---
-title: Oga adapter
+title: Oga
 parent: Adapters
-grand_parent: Overview
 nav_order: 3
 ---
 

data/docs/_pages/adapters/ox.adoc

@@ -1,5 +1,5 @@
 ---
-title: Ox adapter
+title: Ox
 parent: Adapters
 nav_order: 5
 ---
@@ -11,6 +11,7 @@ nav_order: 5
 Ox is the fastest XML parser available for Ruby, providing excellent performance for simple to moderately complex XML documents.
 
 **Best for:**
+
 * Maximum parsing speed
 * Simple document structures
 * Memory-constrained environments

data/docs/_pages/adapters/rexml.adoc

@@ -1,7 +1,6 @@
 ---
-title: REXML adapter
+title: REXML
 parent: Adapters
-grand_parent: Overview
 nav_order: 4
 ---
 

data/docs/_pages/best-practices.adoc

@@ -1,6 +1,5 @@
 ---
 title: Best practices
-parent: Overview
 nav_order: 9
 ---
 

data/docs/_pages/compatibility.adoc

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

data/docs/_pages/configuration.adoc

@@ -1,6 +1,5 @@
 ---
 title: Configuration
-parent: Overview
 nav_order: 7
 ---
 

data/docs/_pages/error-handling.adoc

@@ -1,6 +1,5 @@
 ---
 title: Error handling
-parent: Overview
 nav_order: 8
 ---
 

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,6 +1,5 @@
 ---
 title: Node API reference
-parent: Overview
 nav_order: 5
 ---
 

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)
@@ -831,7 +837,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)
@@ -1301,7 +1316,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 +1459,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
 
@@ -328,8 +353,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
 
@@ -371,8 +388,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

data/lib/moxml/adapter/ox.rb

@@ -348,6 +348,24 @@ module Moxml
         end
 
         def add_child(element, child)
+          # Special handling for declarations on Ox documents
+          if element.is_a?(::Ox::Document) && child.is_a?(::Ox::Instruct) && child.target == "xml"
+            # Transfer declaration attributes to document
+            element.attributes ||= {}
+            if child.attributes["version"]
+              element.attributes[:version] =
+                child.attributes["version"]
+            end
+            if child.attributes["encoding"]
+              element.attributes[:encoding] =
+                child.attributes["encoding"]
+            end
+            if child.attributes["standalone"]
+              element.attributes[:standalone] =
+                child.attributes["standalone"]
+            end
+          end
+
           child.parent = element if child.respond_to?(:parent)
           element.nodes ||= []
           element.nodes << child
@@ -380,6 +398,15 @@ module Moxml
 
           return unless parent(node)
 
+          # Special handling for declarations on Ox documents
+          if parent(node).is_a?(::Ox::Document) && node.is_a?(::Ox::Instruct) && node.target == "xml"
+            # Clear declaration attributes from document
+            doc = parent(node)
+            doc.attributes&.delete(:version)
+            doc.attributes&.delete(:encoding)
+            doc.attributes&.delete(:standalone)
+          end
+
           parent(node).nodes.delete(unpatch_node(node))
         end
 
@@ -524,13 +551,24 @@ module Moxml
         def serialize(node, options = {})
           output = ""
           if node.is_a?(::Ox::Document)
-            # add declaration
-            version = node[:version] || "1.0"
-            encoding = options[:encoding] || node[:encoding]
-            standalone = node[:standalone]
-
-            decl = create_native_declaration(version, encoding, standalone)
-            output = ::Ox.dump(::Ox::Document.new << decl).strip
+            # Check if we should include declaration
+            # Priority: explicit option > document attributes
+            should_include_decl = if options.key?(:no_declaration)
+                                    !options[:no_declaration]
+                                  else
+                                    # Check if document has declaration attributes
+                                    node[:version] || node[:encoding] || node[:standalone]
+                                  end
+
+            # Only add declaration if should_include_decl is true
+            if should_include_decl
+              version = node[:version] || "1.0"
+              encoding = options[:encoding] || node[:encoding]
+              standalone = node[:standalone]
+
+              decl = create_native_declaration(version, encoding, standalone)
+              output = ::Ox.dump(::Ox::Document.new << decl).strip
+            end
           end
 
           ox_options = {