multi_xml 0.8.1 → 0.9.1

data/lib/multi_xml/parsers/rexml.rb

@@ -1,28 +1,28 @@
 require "rexml/document"
 
-module MultiXml
+module MultiXML
   module Parsers
     # XML parser using Ruby's built-in REXML library
     #
     # @api private
     module Rexml
+      extend MultiXML::Parser
       extend self
 
-      # Get the parse error class for this parser
-      #
+      # Exception class raised on REXML parse failure
       # @api private
-      # @return [Class] REXML::ParseException
-      def parse_error = ::REXML::ParseException
+      ParseError = ::REXML::ParseException
 
       # 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 [REXML::ParseException] if XML is malformed
-      def parse(io)
+      def parse(io, namespaces: :strip)
         doc = REXML::Document.new(io)
-        element_to_hash({}, doc.root)
+        element_to_hash({}, doc.root, namespaces)
       end
 
       private
@@ -32,21 +32,54 @@ module MultiXml
       # @api private
       # @param hash [Hash] Accumulator hash
       # @param element [REXML::Element] Element to convert
+      # @param mode [Symbol] Namespace handling mode
       # @return [Hash] Updated hash
-      def element_to_hash(hash, element)
-        add_to_hash(hash, element.name, collapse_element(element))
+      def element_to_hash(hash, element, mode)
+        add_to_hash(hash, format_element_name(element, mode), collapse_element(element, mode))
+      end
+
+      # Format element name using prefix/local and namespace mode
+      #
+      # @api private
+      # @param element [REXML::Element] Element node
+      # @param mode [Symbol] Namespace handling mode
+      # @return [String] formatted element name
+      def format_element_name(element, mode)
+        format_name(element.prefix, element.name, mode)
+      end
+
+      # Format attribute name using prefix/local and namespace mode
+      #
+      # @api private
+      # @param attr [REXML::Attribute] Attribute node
+      # @param mode [Symbol] Namespace handling mode
+      # @return [String] formatted attribute name
+      def format_attr_name(attr, mode)
+        format_name(attr.prefix, attr.name, mode)
+      end
+
+      # Produce a name string for a given [prefix, local] tuple
+      #
+      # @api private
+      # @param prefix [String, nil] Namespace prefix
+      # @param local [String] Local part of the name
+      # @param mode [Symbol] Namespace handling mode
+      # @return [String] formatted name
+      def format_name(prefix, local, mode)
+        (mode == :preserve && prefix && !prefix.empty?) ? "#{prefix}:#{local}" : local
       end
 
       # Collapse an element into a hash with attributes and content
       #
       # @api private
       # @param element [REXML::Element] Element to collapse
+      # @param mode [Symbol] Namespace handling mode
       # @return [Hash] Hash representation
-      def collapse_element(element)
-        node_hash = collect_attributes(element)
+      def collapse_element(element, mode)
+        node_hash = collect_attributes(element, mode)
 
         if element.has_elements?
-          collect_child_elements(element, node_hash)
+          collect_child_elements(element, node_hash, mode)
           add_text_content(node_hash, element) unless whitespace_only?(element)
         elsif node_hash.empty? || !whitespace_only?(element)
           add_text_content(node_hash, element)
@@ -59,9 +92,34 @@ module MultiXml
       #
       # @api private
       # @param element [REXML::Element] Element with attributes
+      # @param mode [Symbol] Namespace handling mode
       # @return [Hash] Hash of attribute name-value pairs
-      def collect_attributes(element)
-        element.attributes.each_with_object({}) { |(name, value), hash| hash[name] = value }
+      def collect_attributes(element, mode)
+        element.attributes.each_attribute.with_object({}) do |attr, hash|
+          if xmlns_decl?(attr)
+            add_attribute_value(hash, xmlns_decl_key(attr), attr.value) if mode == :preserve
+          else
+            add_attribute_value(hash, format_attr_name(attr, mode), attr.value)
+          end
+        end
+      end
+
+      # Check whether an attribute represents an xmlns declaration
+      #
+      # @api private
+      # @param attr [REXML::Attribute] Attribute to inspect
+      # @return [Boolean] true if xmlns declaration
+      def xmlns_decl?(attr)
+        attr.prefix == "xmlns" || ((attr.prefix.nil? || attr.prefix.empty?) && attr.name == "xmlns")
+      end
+
+      # Build the key for an xmlns declaration under :preserve
+      #
+      # @api private
+      # @param attr [REXML::Attribute] Declaration attribute
+      # @return [String] key such as "xmlns" or "xmlns:atom"
+      def xmlns_decl_key(attr)
+        (attr.prefix == "xmlns") ? "xmlns:#{attr.name}" : "xmlns"
       end
 
       # Collect all child elements into a hash
@@ -69,9 +127,10 @@ module MultiXml
       # @api private
       # @param element [REXML::Element] Parent element
       # @param node_hash [Hash] Hash to populate
+      # @param mode [Symbol] Namespace handling mode
       # @return [void]
-      def collect_child_elements(element, node_hash)
-        element.each_element { |child| element_to_hash(node_hash, child) }
+      def collect_child_elements(element, node_hash, mode)
+        element.each_element { |child| element_to_hash(node_hash, child, mode) }
       end
 
       # Add text content from an element to a hash
@@ -106,6 +165,35 @@ module MultiXml
         hash
       end
 
+      # 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 [Hash] Updated hash
+      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
+        hash
+      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
+
       # Check if element contains only whitespace text
       #
       # @api private

data/lib/multi_xml/parsers/sax_handler.rb

@@ -1,23 +1,29 @@
 require "cgi/escape"
 
-module MultiXml
+module MultiXML
   module Parsers
-    # Shared SAX handler logic for building hash trees from XML events
+    # Shared SAX handler logic for building hash trees from XML events.
     #
-    # This module provides the core stack-based parsing logic used by both
-    # NokogiriSax and LibxmlSax parsers. Including classes must implement
-    # the callback methods that their respective SAX libraries expect.
+    # Provides a stack machine used by both NokogiriSax and LibxmlSax
+    # handlers. Parser-specific subclasses translate their native callbacks
+    # into calls on this entrypoint:
+    #
+    # - handle_start_element_ns(local, prefix, attr_tuples, ns_decls)
+    #     where attr_tuples = [[attr_prefix_or_nil, local, value], ...]
+    #           ns_decls    = [[prefix_or_nil, uri], ...]
     #
     # @api private
     module SaxHandler
       # Initialize the handler state
       #
       # @api private
+      # @param mode [Symbol] Namespace handling mode
       # @return [void]
-      def initialize_handler
+      def initialize_handler(mode)
+        @mode = mode
         @result = {}
         @stack = [@result]
-        @pending_attrs = []
+        @pending = []
       end
 
       # Get the parsed result
@@ -28,31 +34,34 @@ module MultiXml
 
       private
 
-      # Get the current element hash
+      # Get the current element hash on top of the stack
       #
       # @api private
       # @return [Hash] current hash being built
       def current = @stack.last
 
-      # Handle start of an element by pushing onto the stack
+      # Entry point for namespace-aware start events
       #
       # @api private
-      # @param name [String] Element name
-      # @param attrs [Hash, Array] Element attributes
+      # @param local [String] Local element name
+      # @param prefix [String, nil] Element namespace prefix
+      # @param attr_tuples [Array] Attributes as [prefix, local, value]
+      # @param ns_decls [Array] xmlns declarations as [prefix, uri] pairs
       # @return [void]
-      def handle_start_element(name, attrs)
+      def handle_start_element_ns(local, prefix, attr_tuples, ns_decls)
         child = {TEXT_CONTENT_KEY => +""}
-        add_child_to_current(name, child)
+        add_child_to_current(format_name(prefix, local), child)
         @stack << child
-        @pending_attrs << normalize_attrs(attrs)
+
+        @pending << build_pending_attrs(ns_decls, attr_tuples)
       end
 
-      # Handle end of an element by applying attributes and popping the stack
+      # Apply attributes and pop the current element from the stack
       #
       # @api private
       # @return [void]
       def handle_end_element
-        apply_attributes(@pending_attrs.pop)
+        @pending.pop.each { |key, value| add_attr_to_current(key, value) }
         strip_whitespace_content
         @stack.pop
       end
@@ -66,7 +75,40 @@ module MultiXml
         current[TEXT_CONTENT_KEY] << text
       end
 
-      # Add a child hash to the current element
+      # Build the list of attributes to apply at element-end
+      #
+      # @api private
+      # @param ns_decls [Array] xmlns declarations
+      # @param attr_tuples [Array] Attribute [prefix, local, value] tuples
+      # @return [Array<Array>] list of [key, value] pairs
+      def build_pending_attrs(ns_decls, attr_tuples)
+        preserved_ns_decls(ns_decls) + attr_tuples.map do |prefix, local, value|
+          [format_name(prefix, local), CGI.unescapeHTML(value)]
+        end
+      end
+
+      # Transform xmlns declarations into attribute pairs for :preserve mode
+      #
+      # @api private
+      # @param ns_decls [Array] Declarations as [prefix, uri]
+      # @return [Array<Array>] [xmlns key, uri] pairs (empty outside :preserve)
+      def preserved_ns_decls(ns_decls)
+        return [] unless @mode == :preserve
+
+        ns_decls.map { |prefix, uri| [prefix ? "xmlns:#{prefix}" : "xmlns", uri] }
+      end
+
+      # Produce a name string for a [prefix, local] tuple
+      #
+      # @api private
+      # @param prefix [String, nil] Namespace prefix
+      # @param local [String] Local part of the name
+      # @return [String] formatted name
+      def format_name(prefix, local)
+        (@mode == :preserve && prefix) ? "#{prefix}:#{local}" : local
+      end
+
+      # Add a child element to the current hash, folding on collision
       #
       # @api private
       # @param name [String] Child element name
@@ -81,29 +123,39 @@ module MultiXml
         end
       end
 
-      # Normalize attributes to a hash
+      # Add an attribute value to the current hash (attr wins on collision)
+      #
+      # Attributes are applied at end_element, after children have already
+      # populated the hash. When an attribute collides with a child of the
+      # same local name, the attribute is placed first in the resulting
+      # array (matching DomParser / REXML behavior and existing tests).
       #
       # @api private
-      # @param attrs [Hash, Array] Attributes as hash or array of pairs
-      # @return [Hash] Normalized attributes hash
-      def normalize_attrs(attrs)
-        attrs.is_a?(Hash) ? attrs : attrs.to_h
+      # @param key [String] Attribute key
+      # @param value [String] Attribute value
+      # @return [void]
+      def add_attr_to_current(key, value)
+        existing = current[key]
+        current[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
 
-      # Apply pending attributes to the current element
+      # Insert a later attribute before any child-element entries
       #
       # @api private
-      # @param attrs [Hash] Attributes to apply
-      # @return [void]
-      def apply_attributes(attrs)
-        attrs.each do |name, value|
-          unescaped = CGI.unescapeHTML(value)
-          existing = current[name]
-          current[name] = existing ? [unescaped, existing] : unescaped
-        end
+      # @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
+      # Remove empty or whitespace-only text content from the current hash
       #
       # @api private
       # @return [void]

data/lib/multi_xml/version.rb

@@ -1,7 +1,7 @@
-module MultiXml
-  # The current version of MultiXml
+module MultiXML
+  # The current version of MultiXML
   #
   # @api public
   # @return [Gem::Version] the gem version
-  VERSION = Gem::Version.create("0.8.1")
+  VERSION = Gem::Version.create("0.9.1")
 end