multi_xml 0.8.1 → 0.9.1

data/lib/multi_xml/parsers/nokogiri_sax.rb

@@ -2,36 +2,41 @@ require "nokogiri"
 require "stringio"
 require_relative "sax_handler"
 
-module MultiXml
+module MultiXML
   module Parsers
     # SAX-based parser using Nokogiri (faster for large documents)
     #
     # @api private
     module NokogiriSax
+      extend MultiXML::Parser
+
       module_function
 
-      # Get the parse error class for this parser
-      #
+      # Exception class raised on Nokogiri parse failure
       # @api private
-      # @return [Class] Nokogiri::XML::SyntaxError
-      def parse_error = ::Nokogiri::XML::SyntaxError
+      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)
+      def parse(xml, namespaces: :strip)
         io = xml.respond_to?(:read) ? xml : StringIO.new(xml)
         return {} if io.eof?
 
-        handler = Handler.new
+        handler = Handler.new(namespaces)
         ::Nokogiri::XML::SAX::Parser.new(handler).parse(io)
         handler.result
       end
 
-      # Nokogiri SAX handler that builds a hash tree while parsing
+      # 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
@@ -40,10 +45,11 @@ module MultiXml
         # Create a new SAX handler
         #
         # @api private
+        # @param mode [Symbol] Namespace handling mode
         # @return [Handler] new handler instance
-        def initialize
-          super
-          initialize_handler
+        def initialize(mode)
+          super()
+          initialize_handler(mode)
         end
 
         # Handle start of document (no-op)
@@ -70,22 +76,33 @@ module MultiXml
           raise ::Nokogiri::XML::SyntaxError, message
         end
 
-        # Handle start of an element
+        # Handle start of a namespaced element
+        #
+        # Signature is fixed by the Nokogiri SAX protocol.
         #
         # @api private
-        # @param name [String] Element name
-        # @param attrs [Array] Element attributes as pairs
+        # @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]
-        def start_element(name, attrs = [])
-          handle_start_element(name, attrs)
+        # 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 an element
+        # Handle end of a namespaced element
         #
         # @api private
-        # @param _name [String] Element name (unused)
+        # @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(_name)
+        def end_element_namespace(_local, _prefix = nil, _uri = nil)
           handle_end_element
         end
 
@@ -96,6 +113,17 @@ module MultiXml
         # @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

data/lib/multi_xml/parsers/oga.rb

@@ -1,30 +1,30 @@
 require "oga"
 require_relative "dom_parser"
 
-module MultiXml
+module MultiXML
   module Parsers
     # XML parser using the Oga library
     #
     # @api private
     module Oga
+      extend MultiXML::Parser
       include DomParser
       extend self
 
-      # Get the parse error class for this parser
-      #
+      # Exception class raised on Oga parse failure
       # @api private
-      # @return [Class] LL::ParserError
-      def parse_error = LL::ParserError
+      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)
+      def parse(io, namespaces: :strip)
         doc = ::Oga.parse_xml(io)
-        node_to_hash(doc.children.first)
+        node_to_hash(doc.children.first, mode: namespaces)
       end
 
       # Collect child nodes into a hash (Oga-specific implementation)
@@ -34,11 +34,12 @@ module MultiXml
       # @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)
+      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)
+          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
@@ -48,21 +49,92 @@ module MultiXml
 
       # Iterate over child nodes
       #
+      # @api private
       # @param node [Oga::XML::Element] Parent node
       # @return [void]
       def each_child(node, &) = node.children.each(&)
 
-      # Iterate over attribute nodes
+      # Iterate over attribute nodes (excludes xmlns declarations)
       #
+      # @api private
       # @param node [Oga::XML::Element] Element node
       # @return [void]
-      def each_attr(node, &) = node.attributes.each(&)
+      def each_element_attr(node)
+        node.attributes.each do |attr|
+          next if oga_xmlns_attr?(attr)
+
+          yield attr
+        end
+      end
+
+      # 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
+
+      # 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
 
-      # Get the name of a node or attribute
+      # Return [prefix, local] for an attribute
       #
-      # @param node [Oga::XML::Node] Node to get name from
-      # @return [String] Node name
-      def node_name(node) = node.name
+      # @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
+
+      # 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
+
+        (namespace.name == "xmlns") ? nil : namespace.name
+      end
+
+      # 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
+
+      # 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
   end
 end

data/lib/multi_xml/parsers/ox.rb

@@ -1,89 +1,106 @@
 require "ox"
 
-module MultiXml
+module MultiXML
   module Parsers
     # XML parser using the Ox library (fastest pure-Ruby parser)
     #
     # @api private
     module Ox
+      extend MultiXML::Parser
+
       module_function
 
-      # Get the parse error class for this parser
-      #
+      # Exception class raised on Ox parse failure
       # @api private
-      # @return [Class] Ox::ParseError
-      def parse_error = ::Ox::ParseError
+      ParseError = ::Ox::ParseError
 
       # 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
-      def parse(io)
-        handler = Handler.new
+      def parse(io, namespaces: :strip)
+        handler = Handler.new(namespaces)
         ::Ox.sax_parse(handler, io, convert_special: true, skip: :skip_return)
         handler.result
       end
 
-      # SAX event handler that builds a hash tree while parsing
+      # SAX event handler that builds a hash tree while parsing.
+      #
+      # Ox's SAX callbacks expose element and attribute names in prefixed
+      # form (e.g. "atom:feed"). Under :preserve we keep the source form
+      # verbatim; under :strip we drop the prefix and filter xmlns
+      # declarations out of the attribute stream.
       #
       # @api private
       class Handler
         # Create a new SAX handler
         #
+        # @api private
+        # @param mode [Symbol] Namespace handling mode
         # @return [Handler] new handler instance
-        def initialize
-          @stack = []
+        def initialize(mode)
+          @mode = mode
+          @stack = [{}]
         end
 
         # Get the parsed result
         #
-        # @return [Hash, nil] the root hash or nil if empty
+        # @api private
+        # @return [Hash] the parsed hash
         def result = @stack.first
 
         # Handle start of an element
         #
-        # @param name [Symbol] Element name
+        # @api private
+        # @param name [Symbol, String] Element name
         # @return [void]
         def start_element(name)
-          @stack << {} if @stack.empty?
           child = {}
-          add_value(name.to_s, child)
+          add_value(current, format_name(name.to_s), child)
           @stack << child
         end
 
-        # Handle end of an element
-        #
-        # @param _name [Symbol] Element name (unused)
-        # @return [void]
-        def end_element(_name)
-          strip_whitespace_content if current.key?(TEXT_CONTENT_KEY)
-          @stack.pop
-        end
-
         # Handle an attribute
         #
-        # @param name [Symbol] Attribute name
+        # Ignored outside an element (e.g. attributes on the XML declaration
+        # such as `<?xml version="1.0"?>`, which fire before any `start_element`).
+        #
+        # @api private
+        # @param name [Symbol, String] Attribute name
         # @param value [String] Attribute value
         # @return [void]
         def attr(name, value)
-          add_value(name.to_s, value) unless @stack.empty?
+          return if @stack.size < 2
+
+          name = name.to_s
+          return if xmlns_decl?(name) && @mode != :preserve
+
+          add_attribute_value(current, format_name(name), value)
         end
 
-        # Handle text content
+        # Handle text content (also aliased as `cdata`)
         #
+        # @api private
         # @param value [String] Text content
         # @return [void]
-        def text(value) = add_value(TEXT_CONTENT_KEY, value)
+        def text(value) = append_text(current, value)
+        alias_method :cdata, :text
 
-        # Handle CDATA content
+        # Handle end of an element
         #
-        # @param value [String] CDATA content
+        # @api private
+        # @param _name [Symbol, String] Element name (unused)
         # @return [void]
-        def cdata(value) = add_value(TEXT_CONTENT_KEY, value)
+        def end_element(_name)
+          strip_whitespace_content if current.key?(TEXT_CONTENT_KEY)
+          @stack.pop
+        end
 
         # Handle parse errors
         #
+        # @api private
         # @param message [String] Error message
         # @param line [Integer] Line number
         # @param column [Integer] Column number
@@ -95,23 +112,60 @@ module MultiXml
 
         private
 
-        # Get the current element hash
+        # Current element hash on top of the stack
         #
+        # @api private
         # @return [Hash] current hash being built
         def current = @stack.last
 
-        # Add a value to the current hash, merging with existing if needed
+        # Format a prefixed-or-local name according to the namespace mode
         #
+        # @api private
+        # @param name [String] Prefixed or local name
+        # @return [String] formatted name
+        def format_name(name)
+          (@mode == :preserve) ? name : name.split(":", 2).last
+        end
+
+        # Check whether an attribute name is an xmlns declaration
+        #
+        # @api private
+        # @param name [String] Attribute name
+        # @return [Boolean] true if xmlns or xmlns:*
+        def xmlns_decl?(name)
+          name == "xmlns" || name.start_with?("xmlns:")
+        end
+
+        # Add a value to a hash, folding into an array on collision
+        #
+        # @api private
+        # @param hash [Hash] Target hash
         # @param key [String] Key to add
         # @param value [Object] Value to add
         # @return [void]
-        def add_value(key, value)
-          existing = current[key]
-          current[key] = existing ? merge_values(existing, value) : value
+        def add_value(hash, key, value)
+          existing = hash[key]
+          hash[key] = existing ? merge_values(existing, value) : value
         end
 
-        # Merge a value with an existing value, creating array if needed
+        # Append a text fragment to the current node's content
+        #
+        # SAX parsers may deliver element text in multiple callbacks when
+        # inline elements split the text stream. MultiXML represents that
+        # as one concatenated ``__content__`` string, not an array.
         #
+        # @api private
+        # @param hash [Hash] Target hash
+        # @param value [String] Text fragment
+        # @return [void]
+        def append_text(hash, value)
+          existing = hash[TEXT_CONTENT_KEY]
+          hash[TEXT_CONTENT_KEY] = existing ? "#{existing}#{value}" : value
+        end
+
+        # Merge a value with an existing value, creating an array if needed
+        #
+        # @api private
         # @param existing [Object] Existing value
         # @param value [Object] Value to append
         # @return [Array] array with both values
@@ -119,8 +173,37 @@ module MultiXml
           existing.is_a?(Array) ? existing << value : [existing, value]
         end
 
-        # Remove empty or whitespace-only text content
+        # Add an attribute value while keeping document order on collisions
+        #
+        # @api private
+        # @param hash [Hash] Target hash
+        # @param key [String] Attribute key
+        # @param value [String] Attribute value
+        # @return [void]
+        def add_attribute_value(hash, key, value)
+          existing = hash[key]
+          hash[key] = case existing
+          when nil then value
+          when Array then insert_attribute_before_children(existing, value)
+          when Hash then [value, existing]
+          else [existing, value]
+          end
+        end
+
+        # Insert a later attribute before any child-element entries
+        #
+        # @api private
+        # @param values [Array] Existing colliding values
+        # @param value [String] Attribute value to insert
+        # @return [Array] Updated value list
+        def insert_attribute_before_children(values, value)
+          child_index = values.index { |entry| entry.is_a?(Hash) } || values.length
+          values.dup.insert(child_index, value)
+        end
+
+        # Remove empty or whitespace-only text content from the current hash
         #
+        # @api private
         # @return [void]
         def strip_whitespace_content
           content = current[TEXT_CONTENT_KEY]