multi_xml 0.8.0 → 0.9.0

data/lib/multi_xml/parser_resolution.rb

@@ -0,0 +1,150 @@
+module MultiXML
+  # Internal helpers for resolving and loading parser backends
+  #
+  # @api private
+  module ParserResolution
+    private
+
+    # Resolve a parser specification to a module
+    #
+    # @api private
+    # @param spec [Symbol, String, Class, Module] Parser specification
+    # @return [Module] Resolved parser module
+    # @raise [ParserLoadError] if spec is invalid, the parser file
+    #   can't be required, or the resolved parser doesn't satisfy
+    #   the parser contract
+    def resolve_parser(spec)
+      parser = case spec
+      when String, Symbol then load_parser(spec)
+      when Module then spec
+      else raise ParserLoadError, "expected parser to be a Symbol, String, or Module, got #{spec.inspect}"
+      end
+      validate_parser!(parser)
+    rescue ::LoadError => e
+      raise ParserLoadError.build(e)
+    end
+
+    # Load a parser by name
+    #
+    # @api private
+    # @param name [Symbol, String] Parser name
+    # @return [Module] Loaded parser module
+    def load_parser(name)
+      name = name.to_s.downcase
+      require "multi_xml/parsers/#{name}"
+      Parsers.const_get(camelize(name))
+    end
+
+    # Validate that a parser satisfies the documented contract
+    #
+    # Custom parsers are accepted as modules/classes, so fail fast
+    # during parser resolution rather than later on the first parse
+    # call. A parser must respond to ``.parse`` and must either
+    # define a ``ParseError`` constant or respond to ``.parse_error``.
+    #
+    # @api private
+    # @param parser [Module] parser class or module
+    # @return [Module] the validated parser
+    # @raise [ParserLoadError] when the parser is missing a required method
+    def validate_parser!(parser)
+      raise ParserLoadError, "Parser #{parser} must respond to .parse" unless parser.respond_to?(:parse)
+      unless parser.const_defined?(:ParseError, false) || parser.respond_to?(:parse_error)
+        raise ParserLoadError, "Parser #{parser} must define a ParseError constant or a .parse_error method"
+      end
+
+      parser
+    end
+
+    # Convert underscored string to CamelCase
+    #
+    # @api private
+    # @param name [String] Underscored string
+    # @return [String] CamelCased string
+    def camelize(name)
+      name.split("_").map(&:capitalize).join
+    end
+
+    # Detect the best available parser
+    #
+    # @api private
+    # @return [Symbol] Parser name
+    # @raise [NoParserError] if no parser is available
+    def detect_parser
+      find_loaded_parser || find_available_parser || raise_no_parser_error
+    end
+
+    # Parser constant names mapped to their symbols, in preference order
+    #
+    # @api private
+    LOADED_PARSER_CHECKS = {
+      Ox: :ox,
+      LibXML: :libxml,
+      Nokogiri: :nokogiri,
+      Oga: :oga
+    }.freeze
+    private_constant :LOADED_PARSER_CHECKS
+
+    # Find an already-loaded parser library
+    #
+    # @api private
+    # @return [Symbol, nil] Parser name or nil if none loaded
+    def find_loaded_parser
+      LOADED_PARSER_CHECKS.each do |const_name, parser_name|
+        next if skip_on_platform?(parser_name)
+        return parser_name if Object.const_defined?(const_name)
+      end
+      nil
+    end
+
+    # Try to load and find an available parser
+    #
+    # @api private
+    # @return [Symbol, nil] Parser name or nil if none available
+    def find_available_parser
+      PARSER_PREFERENCE.each do |library, parser_name|
+        next if skip_on_platform?(parser_name)
+        return parser_name if try_require(library)
+      end
+      nil
+    end
+
+    # Whether a parser should be skipped during auto-detection
+    #
+    # Ox loads on TruffleRuby but its SAX callbacks misbehave under the
+    # native interpreter, so type-attributed XML parses to an empty hash
+    # and the disallowed-type check is silently bypassed. Skip it during
+    # auto-detection so MultiXML falls through to a working backend.
+    # Callers that pass ``parser: :ox`` explicitly still get Ox.
+    #
+    # @api private
+    # @param parser_name [Symbol] parser symbol from preference list
+    # @return [Boolean] true when this parser must be skipped
+    def skip_on_platform?(parser_name)
+      parser_name == :ox && RUBY_ENGINE == "truffleruby"
+    end
+
+    # Attempt to require a library
+    #
+    # @api private
+    # @param library [String] Library to require
+    # @return [Boolean] true if successful, false if LoadError
+    def try_require(library)
+      require library
+      true
+    rescue LoadError
+      false
+    end
+
+    # Raise an error indicating no parser is available
+    #
+    # @api private
+    # @return [void]
+    # @raise [NoParserError] always
+    def raise_no_parser_error
+      raise NoParserError, <<~MSG.chomp
+        No XML parser detected. Install one of: ox, nokogiri, libxml-ruby, or oga.
+        See https://github.com/sferik/multi_xml for more information.
+      MSG
+    end
+  end
+end

data/lib/multi_xml/parsers/dom_parser.rb

@@ -1,12 +1,21 @@
-module MultiXml
+module MultiXML
+  # Namespace for all supported XML parser backends
+  #
+  # Each parser (Nokogiri, LibXML, Ox, Oga, REXML, plus SAX variants) is
+  # defined as a module under this namespace and exposes a common `parse`
+  # and `parse_error` interface.
+  #
+  # @api private
   module Parsers
     # Shared DOM traversal logic for converting XML nodes to hashes
     #
     # Used by Nokogiri, LibXML, and Oga parsers.
     # Including modules must implement:
     # - each_child(node) { |child| ... }
-    # - each_attr(node) { |attr| ... }
-    # - node_name(node) -> String
+    # - each_element_attr(node) { |attr| ... } (non-namespace-decl attrs only)
+    # - each_namespace_decl(node) { |prefix_or_nil, uri| ... }
+    # - element_parts(node) -> [prefix_or_nil, local_name]
+    # - attr_parts(attr)    -> [prefix_or_nil, local_name]
     #
     # @api private
     module DomParser
@@ -15,12 +24,14 @@ module MultiXml
       # @api private
       # @param node [Object] XML node to convert
       # @param hash [Hash] Accumulator hash for results
+      # @param mode [Symbol] Namespace handling mode (:strip, :preserve)
       # @return [Hash] Hash representation of the node
-      def node_to_hash(node, hash = {})
+      def node_to_hash(node, hash = {}, mode: :strip)
         node_hash = {TEXT_CONTENT_KEY => +""}
-        add_value(hash, node_name(node), node_hash)
-        collect_children(node, node_hash)
-        collect_attributes(node, node_hash)
+        add_value(hash, format_element_name(node, mode), node_hash)
+        collect_children(node, node_hash, mode)
+        collect_namespace_decls(node, node_hash, mode)
+        collect_attributes(node, node_hash, mode)
         strip_whitespace_content(node_hash)
         hash
       end
@@ -48,11 +59,12 @@ module MultiXml
       # @api private
       # @param node [Object] 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|
           if child.element?
-            node_to_hash(child, node_hash)
+            node_to_hash(child, node_hash, mode: mode)
           elsif text_or_cdata?(child)
             node_hash[TEXT_CONTENT_KEY] << child.content
           end
@@ -68,20 +80,101 @@ module MultiXml
         node.text? || node.cdata?
       end
 
+      # Collect xmlns declarations into the hash under :preserve mode
+      #
+      # Declarations are unique per prefix on a given element, so no
+      # collision handling is needed here.
+      #
+      # @api private
+      # @param node [Object] Node with potential xmlns declarations
+      # @param node_hash [Hash] Hash to populate
+      # @param mode [Symbol] Namespace handling mode
+      # @return [void]
+      def collect_namespace_decls(node, node_hash, mode)
+        return unless mode == :preserve
+
+        each_namespace_decl(node) do |prefix, uri|
+          node_hash[prefix ? "xmlns:#{prefix}" : "xmlns"] = uri
+        end
+      end
+
       # Collect all attributes from a node
       #
+      # Attributes arrive after child elements. When an attribute collides
+      # with a child of the same name, the attribute is placed first in the
+      # resulting array (e.g. `<user name="A"><name>B</name></user>` →
+      # `["A", "B"]`). See `test/attribute_tests.rb`.
+      #
       # @api private
       # @param node [Object] Node with attributes
       # @param node_hash [Hash] Hash to populate
+      # @param mode [Symbol] Namespace handling mode
       # @return [void]
-      def collect_attributes(node, node_hash)
-        each_attr(node) do |attr|
-          name = node_name(attr)
-          existing = node_hash[name]
-          node_hash[name] = existing ? [attr.value, existing] : attr.value
+      def collect_attributes(node, node_hash, mode)
+        each_element_attr(node) do |attr|
+          add_attribute_value(node_hash, format_attr_name(attr, mode), attr.value)
         end
       end
 
+      # Format an element's name according to the namespace mode
+      #
+      # @api private
+      # @param node [Object] Element node
+      # @param mode [Symbol] Namespace handling mode
+      # @return [String] formatted element name
+      def format_element_name(node, mode)
+        format_name(*element_parts(node), mode)
+      end
+
+      # Format an attribute's name according to the namespace mode
+      #
+      # @api private
+      # @param attr [Object] Attribute node
+      # @param mode [Symbol] Namespace handling mode
+      # @return [String] formatted attribute name
+      def format_attr_name(attr, mode)
+        format_name(*attr_parts(attr), mode)
+      end
+
+      # Produce a name string for a given [prefix, local] tuple
+      #
+      # @api private
+      # @param prefix [String, nil] Namespace prefix (nil for default / unprefixed)
+      # @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}:#{local}" : local
+      end
+
+      # Add an attribute value, preserving attr-before-child collision order
+      #
+      # @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
       #
       # @api private

data/lib/multi_xml/parsers/libxml.rb

@@ -1,50 +1,73 @@
-require "libxml"
+require "libxml-ruby"
 require_relative "dom_parser"
 
-module MultiXml
+module MultiXML
   module Parsers
     # XML parser using the LibXML library
     #
     # @api private
     module Libxml
+      extend MultiXML::Parser
       include DomParser
       extend self
 
-      # Get the parse error class for this parser
-      #
+      # Exception class raised on LibXML parse failure
       # @api private
-      # @return [Class] LibXML::XML::Error
-      def parse_error = ::LibXML::XML::Error
+      ParseError = ::LibXML::XML::Error
 
       # 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 [LibXML::XML::Error] if XML is malformed
-      def parse(io)
-        node_to_hash(LibXML::XML::Parser.io(io).parse.root)
+      def parse(io, namespaces: :strip)
+        node_to_hash(::LibXML::XML::Parser.io(io).parse.root, mode: namespaces)
       end
 
       private
 
       # Iterate over child nodes
       #
+      # @api private
       # @param node [LibXML::XML::Node] Parent node
       # @return [void]
       def each_child(node, &) = node.each_child(&)
 
       # Iterate over attribute nodes
       #
+      # @api private
+      # @param node [LibXML::XML::Node] Element node
+      # @return [void]
+      def each_element_attr(node, &) = node.each_attr(&)
+
+      # Yield each xmlns declaration on this element
+      #
+      # @api private
       # @param node [LibXML::XML::Node] Element node
       # @return [void]
-      def each_attr(node, &) = node.each_attr(&)
+      def each_namespace_decl(node)
+        node.namespaces.definitions.each { |ns| yield ns.prefix, ns.href }
+      end
+
+      # Return [prefix, local] for an element
+      #
+      # @api private
+      # @param node [LibXML::XML::Node] Element node
+      # @return [Array<String, nil>] prefix and local name
+      def element_parts(node)
+        [node.namespaces.namespace&.prefix, node.name]
+      end
 
-      # Get the name of a node or attribute
+      # Return [prefix, local] for an attribute
       #
-      # @param node [LibXML::XML::Node] Node to get name from
-      # @return [String] Node name
-      def node_name(node) = node.name
+      # @api private
+      # @param attr [LibXML::XML::Attr] Attribute node
+      # @return [Array<String, nil>] prefix and local name
+      def attr_parts(attr)
+        [attr.ns? ? attr.ns.prefix : nil, attr.name]
+      end
     end
   end
 end

data/lib/multi_xml/parsers/libxml_sax.rb

@@ -1,40 +1,101 @@
-require "libxml"
+require "libxml-ruby"
 require "stringio"
 require_relative "sax_handler"
+require_relative "libxml"
 
-module MultiXml
+module MultiXML
   module Parsers
     # SAX-based parser using LibXML (faster for large documents)
     #
     # @api private
     module LibxmlSax
+      extend MultiXML::Parser
+
       module_function
 
-      # Get the parse error class for this parser
-      #
+      # Exception class raised on LibXML parse failure
       # @api private
-      # @return [Class] LibXML::XML::Error
-      def parse_error = ::LibXML::XML::Error
+      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)
-        io = xml.respond_to?(:read) ? xml : StringIO.new(xml)
-        return {} if io.eof?
+      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
-        parser = ::LibXML::XML::SaxParser.io(io)
+        handler = Handler.new(namespaces)
+        parser = ::LibXML::XML::SaxParser.io(StringIO.new(source))
         parser.callbacks = handler
         parser.parse
         handler.result
       end
 
-      # LibXML SAX handler that builds a hash tree while parsing
+      # 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
@@ -44,9 +105,10 @@ module MultiXml
         # Create a new SAX handler
         #
         # @api private
+        # @param mode [Symbol] Namespace handling mode
         # @return [Handler] new handler instance
-        def initialize
-          initialize_handler
+        def initialize(mode)
+          initialize_handler(mode)
         end
 
         # Handle start of document (no-op)
@@ -63,7 +125,7 @@ module MultiXml
         def on_end_document
         end
 
-        # Handle parse errors (no-op, LibXML raises directly)
+        # Handle parse errors (no-op; libxml-ruby raises directly)
         #
         # @api private
         # @param _error [String] Error message (unused)
@@ -73,12 +135,23 @@ module MultiXml
 
         # 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
-        # @param attrs [Hash] Element attributes
+        # @param name [String] Element name (possibly prefixed)
+        # @param attrs [Hash] Attributes as name => value
         # @return [void]
         def on_start_element(name, attrs = {})
-          handle_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
@@ -90,7 +163,19 @@ module MultiXml
           handle_end_element
         end
 
-        # Handle character data
+        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

data/lib/multi_xml/parsers/nokogiri.rb

@@ -1,53 +1,76 @@
 require "nokogiri"
 require_relative "dom_parser"
 
-module MultiXml
+module MultiXML
   module Parsers
     # XML parser using the Nokogiri library
     #
     # @api private
     module Nokogiri
+      extend MultiXML::Parser
       include DomParser
       extend self
 
-      # 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 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)
+      def parse(io, namespaces: :strip)
         doc = ::Nokogiri::XML(io)
         raise doc.errors.first unless doc.errors.empty?
 
-        node_to_hash(doc.root)
+        node_to_hash(doc.root, mode: namespaces)
       end
 
       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
+      # 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(&)
+
+      # Yield each xmlns declaration on this element
       #
+      # @api private
       # @param node [Nokogiri::XML::Node] Element node
       # @return [void]
-      def each_attr(node, &) = node.attribute_nodes.each(&)
+      def each_namespace_decl(node)
+        node.namespace_definitions.each { |ns| yield ns.prefix, ns.href }
+      end
+
+      # 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
 
-      # Get the name of a node or attribute
+      # Return [prefix, local] for an attribute
       #
-      # @param node [Nokogiri::XML::Node] Node to get name from
-      # @return [String] Node name
-      def node_name(node) = node.node_name
+      # @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
 end