multi_xml 0.6.0 → 0.9.1

data/lib/multi_xml/parsers/libxml_sax.rb

@@ -0,0 +1,188 @@
+require "libxml-ruby"
+require "stringio"
+require_relative "sax_handler"
+require_relative "libxml"
+
+module MultiXML
+  module Parsers
+    # SAX-based parser using LibXML (faster for large documents)
+    #
+    # @api private
+    module LibxmlSax
+      extend MultiXML::Parser
+
+      module_function
+
+      # Exception class raised on LibXML parse failure
+      # @api private
+      ParseError = ::LibXML::XML::Error
+
+      # Parse XML from a string or IO object
+      #
+      # @api private
+      # @param xml [String, IO] XML content
+      # @param namespaces [Symbol] Namespace handling mode
+      # @return [Hash] Parsed XML as a hash
+      # @raise [LibXML::XML::Error] if XML is malformed
+      def parse(xml, namespaces: :strip)
+        source = xml.respond_to?(:read) ? xml.read : xml.to_s
+        return {} if source.empty?
+
+        return parse_with_dom(source, namespaces) if dom_fallback?(source, namespaces)
+
+        parse_with_sax(source, namespaces)
+      end
+
+      # Detect whether a start tag has attributes that collide after stripping
+      #
+      # @api private
+      # @param source [String] XML source
+      # @return [Boolean] true when stripped attribute locals collide
+      def stripped_attribute_collision?(source)
+        source.scan(%r{<(?![!?/])[^>]*>}m).any? do |tag|
+          local_names = attribute_names(tag).map { |name| name.split(":", 2).last }
+          local_names.uniq.length < local_names.length
+        end
+      end
+
+      # Extract non-xmlns attribute names from a start tag
+      #
+      # @api private
+      # @param tag [String] Start tag source
+      # @return [Array<String>] attribute names
+      def attribute_names(tag)
+        tag.scan(/\s([a-zA-Z_][\w.-]*(?::[a-zA-Z_][\w.-]*)?)\s*=/).flatten.reject do |name|
+          name == "xmlns" || name.start_with?("xmlns:")
+        end
+      end
+
+      # Determine whether libxml_sax must fall back to the DOM parser
+      #
+      # @api private
+      # @param source [String] XML source
+      # @param namespaces [Symbol] Namespace handling mode
+      # @return [Boolean] true when DOM parsing is required
+      def dom_fallback?(source, namespaces)
+        namespaces != :strip || stripped_attribute_collision?(source)
+      end
+
+      # Parse via the DOM libxml backend
+      #
+      # @api private
+      # @param source [String] XML source
+      # @param namespaces [Symbol] Namespace handling mode
+      # @return [Hash] Parsed XML as a hash
+      def parse_with_dom(source, namespaces)
+        Libxml.parse(StringIO.new(source), namespaces: namespaces)
+      end
+
+      # Parse via libxml-ruby's SAX parser
+      #
+      # @api private
+      # @param source [String] XML source
+      # @param namespaces [Symbol] Namespace handling mode
+      # @return [Hash] Parsed XML as a hash
+      def parse_with_sax(source, namespaces)
+        LibXML::XML::Error.set_handler(&LibXML::XML::Error::QUIET_HANDLER)
+        handler = Handler.new(namespaces)
+        parser = ::LibXML::XML::SaxParser.io(StringIO.new(source))
+        parser.callbacks = handler
+        parser.parse
+        handler.result
+      end
+
+      # LibXML SAX handler.
+      #
+      # libxml-ruby's namespace-aware callback strips prefixes from the attrs
+      # hash, so we rely on the qname-preserving `on_start_element` callback
+      # and resolve namespaces via SaxHandler's scope stack.
+      #
+      # @api private
+      class Handler
+        include ::LibXML::XML::SaxParser::Callbacks
+        include SaxHandler
+
+        # Create a new SAX handler
+        #
+        # @api private
+        # @param mode [Symbol] Namespace handling mode
+        # @return [Handler] new handler instance
+        def initialize(mode)
+          initialize_handler(mode)
+        end
+
+        # Handle start of document (no-op)
+        #
+        # @api private
+        # @return [void]
+        def on_start_document
+        end
+
+        # Handle end of document (no-op)
+        #
+        # @api private
+        # @return [void]
+        def on_end_document
+        end
+
+        # Handle parse errors (no-op; libxml-ruby raises directly)
+        #
+        # @api private
+        # @param _error [String] Error message (unused)
+        # @return [void]
+        def on_error(_error)
+        end
+
+        # Handle start of an element
+        #
+        # libxml-ruby strips xmlns declarations from attrs and passes through
+        # prefixed names for regular attributes. Since libxml_sax only uses
+        # this handler in :strip mode, we route through the namespace-aware
+        # entrypoint with empty ns_decls and treat attribute qnames as-if
+        # they had no namespace — matching the desired :strip output.
+        #
+        # @api private
+        # @param name [String] Element name (possibly prefixed)
+        # @param attrs [Hash] Attributes as name => value
+        # @return [void]
+        def on_start_element(name, attrs = {})
+          prefix, local = sax_split_qname(name.to_s)
+          tuples = attrs.map do |k, v|
+            ap, al = sax_split_qname(k.to_s)
+            [ap, al, v]
+          end
+          handle_start_element_ns(local, prefix, tuples, [])
+        end
+
+        # Handle end of an element
+        #
+        # @api private
+        # @param _name [String] Element name (unused)
+        # @return [void]
+        def on_end_element(_name)
+          handle_end_element
+        end
+
+        private
+
+        # Split a prefixed name into [prefix, local]
+        #
+        # @api private
+        # @param name [String] Prefixed or local name
+        # @return [Array<String, nil>] prefix and local name
+        def sax_split_qname(name)
+          p, l = name.split(":", 2)
+          l ? [p, l] : [nil, p]
+        end
+
+        # Handle character data (also aliased as `on_cdata_block`)
+        #
+        # @api private
+        # @param text [String] Text content
+        # @return [void]
+        def on_characters(text) = append_text(text)
+        alias_method :on_cdata_block, :on_characters
+      end
+    end
+  end
+end

data/lib/multi_xml/parsers/nokogiri.rb

@@ -1,34 +1,75 @@
-require 'nokogiri' unless defined?(Nokogiri)
-require 'multi_xml/parsers/libxml2_parser'
+require "nokogiri"
+require_relative "dom_parser"
 
-module MultiXml
+module MultiXML
   module Parsers
-    module Nokogiri #:nodoc:
-      include Libxml2Parser
+    # XML parser using the Nokogiri library
+    #
+    # @api private
+    module Nokogiri
+      extend MultiXML::Parser
+      include DomParser
       extend self
 
-      def parse_error
-        ::Nokogiri::XML::SyntaxError
-      end
+      # Exception class raised on Nokogiri parse failure
+      # @api private
+      ParseError = ::Nokogiri::XML::SyntaxError
+
+      # Parse XML from an IO object
+      #
+      # @api private
+      # @param io [IO] IO-like object containing XML
+      # @param namespaces [Symbol] Namespace handling mode
+      # @return [Hash] Parsed XML as a hash
+      # @raise [Nokogiri::XML::SyntaxError] if XML is malformed
+      def parse(io, namespaces: :strip)
+        doc = ::Nokogiri::XML(io)
+        raise doc.errors.first unless doc.errors.empty?
 
-      def parse(xml)
-        doc = ::Nokogiri::XML(xml)
-        raise(doc.errors.first) unless doc.errors.empty?
-        node_to_hash(doc.root)
+        node_to_hash(doc.root, mode: namespaces)
       end
 
-    private
+      private
+
+      # Iterate over child nodes
+      #
+      # @api private
+      # @param node [Nokogiri::XML::Node] Parent node
+      # @return [void]
+      def each_child(node, &) = node.children.each(&)
+
+      # Iterate over attribute nodes (excludes xmlns declarations)
+      #
+      # @api private
+      # @param node [Nokogiri::XML::Node] Element node
+      # @return [void]
+      def each_element_attr(node, &) = node.attribute_nodes.each(&)
 
-      def each_child(node, &block)
-        node.children.each(&block)
+      # Yield each xmlns declaration on this element
+      #
+      # @api private
+      # @param node [Nokogiri::XML::Node] Element node
+      # @return [void]
+      def each_namespace_decl(node)
+        node.namespace_definitions.each { |ns| yield ns.prefix, ns.href }
       end
 
-      def each_attr(node, &block)
-        node.attribute_nodes.each(&block)
+      # Return [prefix, local] for an element
+      #
+      # @api private
+      # @param node [Nokogiri::XML::Node] Element node
+      # @return [Array<String, nil>] prefix and local name
+      def element_parts(node)
+        [node.namespace&.prefix, node.name]
       end
 
-      def node_name(node)
-        node.node_name
+      # Return [prefix, local] for an attribute
+      #
+      # @api private
+      # @param attr [Nokogiri::XML::Attr] Attribute node
+      # @return [Array<String, nil>] prefix and local name
+      def attr_parts(attr)
+        [attr.namespace&.prefix, attr.name]
       end
     end
   end

data/lib/multi_xml/parsers/nokogiri_sax.rb

@@ -0,0 +1,130 @@
+require "nokogiri"
+require "stringio"
+require_relative "sax_handler"
+
+module MultiXML
+  module Parsers
+    # SAX-based parser using Nokogiri (faster for large documents)
+    #
+    # @api private
+    module NokogiriSax
+      extend MultiXML::Parser
+
+      module_function
+
+      # Exception class raised on Nokogiri parse failure
+      # @api private
+      ParseError = ::Nokogiri::XML::SyntaxError
+
+      # Parse XML from a string or IO object
+      #
+      # @api private
+      # @param xml [String, IO] XML content
+      # @param namespaces [Symbol] Namespace handling mode
+      # @return [Hash] Parsed XML as a hash
+      # @raise [Nokogiri::XML::SyntaxError] if XML is malformed
+      def parse(xml, namespaces: :strip)
+        io = xml.respond_to?(:read) ? xml : StringIO.new(xml)
+        return {} if io.eof?
+
+        handler = Handler.new(namespaces)
+        ::Nokogiri::XML::SAX::Parser.new(handler).parse(io)
+        handler.result
+      end
+
+      # Nokogiri SAX handler.
+      #
+      # Nokogiri always invokes `start_element_namespace` (even for documents
+      # without namespaces — prefix/uri come through as nil). We don't define
+      # `start_element` because it would never fire.
+      #
+      # @api private
+      class Handler < ::Nokogiri::XML::SAX::Document
+        include SaxHandler
+
+        # Create a new SAX handler
+        #
+        # @api private
+        # @param mode [Symbol] Namespace handling mode
+        # @return [Handler] new handler instance
+        def initialize(mode)
+          super()
+          initialize_handler(mode)
+        end
+
+        # Handle start of document (no-op)
+        #
+        # @api private
+        # @return [void]
+        def start_document
+        end
+
+        # Handle end of document (no-op)
+        #
+        # @api private
+        # @return [void]
+        def end_document
+        end
+
+        # Handle parse errors
+        #
+        # @api private
+        # @param message [String] Error message
+        # @return [void]
+        # @raise [Nokogiri::XML::SyntaxError] always
+        def error(message)
+          raise ::Nokogiri::XML::SyntaxError, message
+        end
+
+        # Handle start of a namespaced element
+        #
+        # Signature is fixed by the Nokogiri SAX protocol.
+        #
+        # @api private
+        # @param local [String] Local element name
+        # @param attrs [Array<Nokogiri::XML::SAX::Parser::Attribute>] Attributes
+        # @param prefix [String, nil] Element namespace prefix
+        # @param _uri [String, nil] Element namespace URI (unused)
+        # @param ns [Array] Namespace declarations as [prefix, uri] pairs
+        # @return [void]
+        # rubocop:disable Metrics/ParameterLists, Naming/MethodParameterName
+        def start_element_namespace(local, attrs = [], prefix = nil, _uri = nil, ns = [])
+          ns_decls = ns.map { |p, u| [normalize(p), u] }
+          attr_tuples = attrs.map { |a| [normalize(a.prefix), a.localname, a.value] }
+          handle_start_element_ns(local, normalize(prefix), attr_tuples, ns_decls)
+        end
+        # rubocop:enable Metrics/ParameterLists, Naming/MethodParameterName
+
+        # Handle end of a namespaced element
+        #
+        # @api private
+        # @param _local [String] Local element name (unused)
+        # @param _prefix [String, nil] Namespace prefix (unused)
+        # @param _uri [String, nil] Namespace URI (unused)
+        # @return [void]
+        def end_element_namespace(_local, _prefix = nil, _uri = nil)
+          handle_end_element
+        end
+
+        # Handle character data
+        #
+        # @api private
+        # @param text [String] Text content
+        # @return [void]
+        def characters(text) = append_text(text)
+        alias_method :cdata_block, :characters
+
+        private
+
+        # Normalize a value, returning nil for empty or nil input
+        #
+        # @api private
+        # @param value [String, nil] Value to normalize
+        # @return [String, nil] value or nil if empty
+        def normalize(value)
+          (value.nil? || value.to_s.empty?) ? nil : value
+        end
+      end
+    end
+  end
+end

data/lib/multi_xml/parsers/oga.rb

@@ -1,73 +1,140 @@
-require 'oga' unless defined?(Oga)
-require 'multi_xml/parsers/libxml2_parser'
+require "oga"
+require_relative "dom_parser"
 
-module MultiXml
+module MultiXML
   module Parsers
-    module Oga #:nodoc:
-      include Libxml2Parser
+    # XML parser using the Oga library
+    #
+    # @api private
+    module Oga
+      extend MultiXML::Parser
+      include DomParser
       extend self
 
-      def parse_error
-        LL::ParserError
+      # Exception class raised on Oga parse failure
+      # @api private
+      ParseError = LL::ParserError
+
+      # Parse XML from an IO object
+      #
+      # @api private
+      # @param io [IO] IO-like object containing XML
+      # @param namespaces [Symbol] Namespace handling mode
+      # @return [Hash] Parsed XML as a hash
+      # @raise [LL::ParserError] if XML is malformed
+      def parse(io, namespaces: :strip)
+        doc = ::Oga.parse_xml(io)
+        node_to_hash(doc.children.first, mode: namespaces)
       end
 
-      def parse(io)
-        document = ::Oga.parse_xml(io)
-        node_to_hash(document.children[0])
+      # Collect child nodes into a hash (Oga-specific implementation)
+      #
+      # Oga uses different node types than Nokogiri/LibXML.
+      #
+      # @api private
+      # @param node [Oga::XML::Element] Parent node
+      # @param node_hash [Hash] Hash to populate
+      # @param mode [Symbol] Namespace handling mode
+      # @return [void]
+      def collect_children(node, node_hash, mode)
+        each_child(node) do |child|
+          case child
+          when ::Oga::XML::Element then node_to_hash(child, node_hash, mode: mode)
+          when ::Oga::XML::Text, ::Oga::XML::Cdata then node_hash[TEXT_CONTENT_KEY] << child.text
+          end
+        end
       end
 
-      def node_to_hash(node, hash = {}) # rubocop:disable AbcSize, CyclomaticComplexity, MethodLength, PerceivedComplexity
-        node_hash = {MultiXml::CONTENT_ROOT => ''}
+      private
 
-        name = node_name(node)
+      # Iterate over child nodes
+      #
+      # @api private
+      # @param node [Oga::XML::Element] Parent node
+      # @return [void]
+      def each_child(node, &) = node.children.each(&)
 
-        # Insert node hash into parent hash correctly.
-        case hash[name]
-        when Array
-          hash[name] << node_hash
-        when Hash
-          hash[name] = [hash[name], node_hash]
-        when NilClass
-          hash[name] = node_hash
-        end
+      # Iterate over attribute nodes (excludes xmlns declarations)
+      #
+      # @api private
+      # @param node [Oga::XML::Element] Element node
+      # @return [void]
+      def each_element_attr(node)
+        node.attributes.each do |attr|
+          next if oga_xmlns_attr?(attr)
 
-        # Handle child elements
-        each_child(node) do |c|
-          if c.is_a?(::Oga::XML::Element)
-            node_to_hash(c, node_hash)
-          elsif c.is_a?(::Oga::XML::Text) || c.is_a?(::Oga::XML::Cdata)
-            node_hash[MultiXml::CONTENT_ROOT] << c.text
-          end
+          yield attr
         end
+      end
 
-        # Remove content node if it is empty
-        if node_hash[MultiXml::CONTENT_ROOT].strip.empty?
-          node_hash.delete(MultiXml::CONTENT_ROOT)
+      # Yield each xmlns declaration on this element
+      #
+      # Oga stores only locally declared namespaces on each element
+      # (inherited ones are resolved via lookup, not merged into
+      # #namespaces), so we can yield them directly.
+      #
+      # @api private
+      # @param node [Oga::XML::Element] Element node
+      # @return [void]
+      def each_namespace_decl(node)
+        namespace_scope(node).each do |key, ns|
+          prefix = (key == "xmlns") ? nil : key
+          yield prefix, ns.uri
         end
+      end
 
-        # Handle attributes
-        each_attr(node) do |a|
-          key = node_name(a)
-          v = node_hash[key]
-          node_hash[key] = (v ? [a.value, v] : a.value)
-        end
+      # Return [prefix, local] for an element
+      #
+      # @api private
+      # @param node [Oga::XML::Element] Element node
+      # @return [Array<String, nil>] prefix and local name
+      def element_parts(node)
+        [oga_prefix(node.namespace), node.name]
+      end
 
-        hash
+      # Return [prefix, local] for an attribute
+      #
+      # @api private
+      # @param attr [Oga::XML::Attribute] Attribute node
+      # @return [Array<String, nil>] prefix and local name
+      def attr_parts(attr)
+        [oga_prefix(attr.namespace), attr.name]
       end
 
-    private
+      # Translate Oga's default-namespace sentinel to nil
+      #
+      # Oga represents the default namespace with the sentinel name "xmlns";
+      # we translate that to nil so it isn't emitted as a prefix.
+      #
+      # @api private
+      # @param namespace [Oga::XML::Namespace, nil] Namespace object
+      # @return [String, nil] prefix or nil
+      def oga_prefix(namespace)
+        return nil unless namespace
 
-      def each_child(node, &block)
-        node.children.each(&block)
+        (namespace.name == "xmlns") ? nil : namespace.name
       end
 
-      def each_attr(node, &block)
-        node.attributes.each(&block)
+      # Check whether an Oga attribute is actually an xmlns declaration
+      #
+      # Oga exposes xmlns declarations via Element#namespaces but may also
+      # surface them as raw attributes in some cases — filter either shape.
+      #
+      # @api private
+      # @param attr [Oga::XML::Attribute] Attribute node
+      # @return [Boolean] true if it's an xmlns declaration
+      def oga_xmlns_attr?(attr)
+        attr.name == "xmlns" || attr.namespace_name == "xmlns"
       end
 
-      def node_name(node)
-        node.name
+      # Local namespace scope for a node
+      #
+      # @api private
+      # @param node [Oga::XML::Element] Element node
+      # @return [Hash{String => Oga::XML::Namespace}] scope
+      def namespace_scope(node)
+        node.namespaces || {}
       end
-    end # Oga
-  end # Parsers
-end # MultiXml
+    end
+  end
+end