multi_xml 0.6.0 → 0.9.1

data/lib/multi_xml/options.rb

@@ -0,0 +1,63 @@
+module MultiXML
+  # Mixin providing configurable parse options
+  #
+  # Supports static hashes or dynamic callables (procs/lambdas). Extended
+  # into MultiXML so callers configure process-wide defaults via
+  # {MultiXML.parse_options=}.
+  #
+  # @api private
+  module Options
+    # Frozen empty hash used as the zero-default for parse options.
+    EMPTY_OPTIONS = {}.freeze
+
+    # Set options for parse operations
+    #
+    # @api public
+    # @param options [Hash, Proc] options hash or callable
+    # @return [Hash, Proc] the options
+    # @example
+    #   MultiXML.parse_options = {symbolize_names: true}
+    def parse_options=(options)
+      @parse_options = options
+    end
+
+    # Get options for parse operations
+    #
+    # When ``@parse_options`` is a callable (proc/lambda), it's invoked
+    # with ``args`` as positional arguments — typically the call-site
+    # options hash. When it's a plain hash, ``args`` is ignored.
+    #
+    # @api public
+    # @param args [Array<Object>] forwarded to the callable, ignored otherwise
+    # @return [Hash] resolved options hash
+    # @example
+    #   MultiXML.parse_options  #=> {}
+    def parse_options(*)
+      resolve_options(@parse_options, *) || EMPTY_OPTIONS
+    end
+
+    private
+
+    # Resolves options from a hash or callable
+    #
+    # @api private
+    # @param options [Hash, Proc, nil] options configuration
+    # @param args [Array<Object>] arguments forwarded to a callable provider
+    # @return [Hash, nil] resolved options hash
+    def resolve_options(options, *)
+      return invoke_callable(options, *) if options.respond_to?(:call)
+
+      options.to_hash if options.respond_to?(:to_hash)
+    end
+
+    # Invokes a callable options provider
+    #
+    # @api private
+    # @param callable [Proc] options provider
+    # @param args [Array<Object>] arguments forwarded when the callable is non-arity-zero
+    # @return [Hash] options returned by the callable
+    def invoke_callable(callable, *)
+      callable.arity.zero? ? callable.call : callable.call(*)
+    end
+  end
+end

data/lib/multi_xml/options_normalization.rb

@@ -0,0 +1,40 @@
+module MultiXML
+  # Helpers for normalizing the options hash passed to {MultiXML.parse}
+  #
+  # Lives in its own module (rather than inside {ParseSupport}, which is
+  # mixed into MultiXML's singleton class) so ``self`` inside these
+  # methods is ``OptionsNormalization`` rather than ``MultiXML``. That
+  # separation is what lets mutation testing distinguish
+  # ``MultiXML.warn_deprecation_once(...)`` from
+  # ``self.warn_deprecation_once(...)``.
+  #
+  # @api private
+  module OptionsNormalization
+    # Translate the deprecated ``:symbolize_keys`` option to ``:symbolize_names``
+    #
+    # Matches Ruby stdlib's ``JSON.parse`` and sister library MultiJSON
+    # naming. Emits a one-time deprecation warning on first encounter
+    # of ``:symbolize_keys``. When both names appear together (unusual
+    # — only possible if the caller explicitly set both), the canonical
+    # ``:symbolize_names`` value wins and ``:symbolize_keys`` is
+    # silently dropped.
+    #
+    # @api private
+    # @param options [Hash] options layer to normalize
+    # @return [Hash] hash with ``:symbolize_keys`` translated, or the
+    #   original hash when no translation is needed
+    # @example
+    #   MultiXML::OptionsNormalization.normalize_symbolize_option(symbolize_keys: true)
+    def self.normalize_symbolize_option(options)
+      return options unless options.key?(:symbolize_keys)
+
+      MultiXML.warn_deprecation_once(:symbolize_keys_option,
+        "The :symbolize_keys option is deprecated and will be removed in v1.0. Use :symbolize_names instead.")
+
+      new_opts = options.dup
+      legacy_value = new_opts.delete(:symbolize_keys)
+      new_opts[:symbolize_names] = legacy_value unless new_opts.key?(:symbolize_names)
+      new_opts
+    end
+  end
+end

data/lib/multi_xml/parse_support.rb

@@ -0,0 +1,113 @@
+module MultiXML
+  # Internal helpers for parsing and post-processing XML
+  #
+  # @api private
+  module ParseSupport
+    private
+
+    # Normalize input to an IO-like object
+    #
+    # @api private
+    # @param xml [String, IO] Input to normalize
+    # @return [IO] IO-like object
+    def normalize_input(xml)
+      return xml if xml.respond_to?(:read)
+
+      StringIO.new(xml.to_s.strip)
+    end
+
+    # Parse XML with error handling and key normalization
+    #
+    # @api private
+    # @param io [IO] IO-like object containing XML
+    # @param original_input [String, IO] Original input for error reporting
+    # @param xml_parser [Module] Parser to use
+    # @param namespaces [Symbol] Namespace handling mode
+    # @return [Hash] Parsed XML (undasherized only when mode is :strip)
+    # @raise [ParseError] if XML is malformed
+    def parse_with_error_handling(io, original_input, xml_parser, namespaces)
+      result = parse_with_namespaces_compatibility(io, xml_parser, namespaces) || {}
+      (namespaces == :strip) ? undasherize_keys(result) : result
+    rescue xml_parser.parse_error => e
+      xml_string = extract_xml_for_error(original_input)
+      raise(ParseError.new(e, xml: xml_string, cause: e))
+    end
+
+    # Call the parser while preserving legacy custom parser compatibility
+    #
+    # @api private
+    # @param io [IO] IO-like object containing XML
+    # @param xml_parser [Module] Parser to use
+    # @param namespaces [Symbol] Namespace handling mode
+    # @return [Hash, nil] Parsed XML result
+    def parse_with_namespaces_compatibility(io, xml_parser, namespaces)
+      if parser_supports_namespaces_keyword?(xml_parser)
+        xml_parser.parse(io, namespaces: namespaces)
+      else
+        xml_parser.parse(io)
+      end
+    end
+
+    # Validate the :namespaces mode option
+    #
+    # @api private
+    # @param mode [Symbol] Namespace handling mode to validate
+    # @return [Symbol] the validated mode
+    # @raise [ArgumentError] if mode is not a recognized value
+    def validate_namespaces_mode(mode)
+      return mode if NAMESPACE_MODES.include?(mode)
+
+      expected_modes = "[#{NAMESPACE_MODES.map(&:inspect).join(", ")}]"
+      raise ArgumentError, "invalid :namespaces mode #{mode.inspect}; expected one of #{expected_modes}"
+    end
+
+    # Pick the parser to use for this call, honoring the :parser option
+    #
+    # @api private
+    # @param options [Hash] Parsing options
+    # @return [Module] Resolved parser module
+    def resolve_parse_parser(options)
+      options[:parser] ? resolve_parser(options.fetch(:parser)) : parser
+    end
+
+    # Check whether the parser accepts a `namespaces:` keyword
+    #
+    # @api private
+    # @param xml_parser [Module] Parser to inspect
+    # @return [Boolean] true when the parser accepts `namespaces:`
+    def parser_supports_namespaces_keyword?(xml_parser)
+      xml_parser.public_method(:parse).parameters.any? do |kind, name|
+        kind == :keyrest || (name == :namespaces && %i[key keyreq].include?(kind))
+      end
+    end
+
+    # Extract the original XML for ParseError reporting
+    #
+    # Some parser backends mutate or close IO objects on error. JRuby's
+    # Nokogiri path closes StringIO instances, so prefer rewind/read when
+    # available but fall back to the underlying string buffer when present.
+    #
+    # @api private
+    # @param original_input [String, IO] original parse input
+    # @return [String] XML payload for ParseError context
+    def extract_xml_for_error(original_input)
+      return original_input.to_s unless original_input.respond_to?(:read)
+
+      original_input.tap(&:rewind).read
+    rescue IOError
+      original_input.respond_to?(:string) ? original_input.string : original_input.to_s
+    end
+
+    # Apply typecasting and key-symbolization as configured
+    #
+    # @api private
+    # @param result [Hash] Parsed hash
+    # @param options [Hash] Parsing options
+    # @return [Hash] Post-processed hash
+    def apply_postprocessing(result, options)
+      result = typecast_xml_value(result, options.fetch(:disallowed_types)) if options.fetch(:typecast_xml_value)
+      result = symbolize_keys(result) if options.fetch(:symbolize_names)
+      result
+    end
+  end
+end

data/lib/multi_xml/parser.rb

@@ -0,0 +1,47 @@
+module MultiXML
+  # Base module for XML parser implementations
+  #
+  # Built-in parsers ``extend`` this module and declare the XML library's
+  # native parse-error class as a ``ParseError`` constant. The inherited
+  # {#parse_error} method reads that constant so {MultiXML.parse} can
+  # wrap backend-specific parse failures uniformly.
+  #
+  # Matches the role of {MultiJSON::Adapter} — a shared contract that
+  # custom parsers can pick up by extending this module, while keeping
+  # backwards compatibility with parsers that instead define a
+  # ``parse_error`` method directly.
+  #
+  # @example Writing a custom parser
+  #   module MyParser
+  #     extend MultiXML::Parser
+  #
+  #     ParseError = Class.new(StandardError)
+  #
+  #     def self.parse(io, namespaces: :strip)
+  #       # parse io into a Hash, raising ParseError on failure
+  #     end
+  #   end
+  #
+  #   MultiXML.parser = MyParser
+  #
+  # @api public
+  module Parser
+    # Return the parse-error class declared on the including parser
+    #
+    # The lookup uses ``inherit: false`` so a stray top-level
+    # ``::ParseError`` in the host process (Racc defines one when
+    # Nokogiri is loaded) is correctly ignored.
+    #
+    # @api public
+    # @return [Class] the ParseError class declared on ``self``
+    # @raise [ParserLoadError] when ``self`` doesn't define ParseError
+    # @example
+    #   MultiXML::Parsers::Nokogiri.parse_error
+    #   #=> Nokogiri::XML::SyntaxError
+    def parse_error
+      const_get(:ParseError, false)
+    rescue NameError
+      raise ParserLoadError, "Parser #{self} must define a ParseError constant"
+    end
+  end
+end

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

@@ -0,0 +1,190 @@
+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_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
+      # Convert an XML node to a hash representation
+      #
+      # @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 = {}, mode: :strip)
+        node_hash = {TEXT_CONTENT_KEY => +""}
+        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
+
+      private
+
+      # Add a value to a hash, converting to array on duplicates
+      #
+      # @api private
+      # @param hash [Hash] Target hash
+      # @param key [String] Key to add
+      # @param value [Object] Value to add
+      # @return [void]
+      def add_value(hash, key, value)
+        existing = hash[key]
+        hash[key] = case existing
+        when Array then existing << value
+        when Hash then [existing, value]
+        else value
+        end
+      end
+
+      # Collect all child nodes into a hash
+      #
+      # @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, mode)
+        each_child(node) do |child|
+          if child.element?
+            node_to_hash(child, node_hash, mode: mode)
+          elsif text_or_cdata?(child)
+            node_hash[TEXT_CONTENT_KEY] << child.content
+          end
+        end
+      end
+
+      # Check if a node is text or CDATA
+      #
+      # @api private
+      # @param node [Object] Node to check
+      # @return [Boolean] true if text or CDATA
+      def text_or_cdata?(node)
+        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, 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
+      # @param node_hash [Hash] Hash to clean up
+      # @return [void]
+      def strip_whitespace_content(node_hash)
+        content = node_hash[TEXT_CONTENT_KEY]
+        should_remove = content.empty? || (node_hash.size > 1 && content.strip.empty?)
+        node_hash.delete(TEXT_CONTENT_KEY) if should_remove
+      end
+    end
+  end
+end

data/lib/multi_xml/parsers/libxml.rb

@@ -1,32 +1,72 @@
-require 'libxml' unless defined?(LibXML)
-require 'multi_xml/parsers/libxml2_parser'
+require "libxml-ruby"
+require_relative "dom_parser"
 
-module MultiXml
+module MultiXML
   module Parsers
-    module Libxml #:nodoc:
-      include Libxml2Parser
+    # XML parser using the LibXML library
+    #
+    # @api private
+    module Libxml
+      extend MultiXML::Parser
+      include DomParser
       extend self
 
-      def parse_error
-        ::LibXML::XML::Error
-      end
+      # Exception class raised on LibXML parse failure
+      # @api private
+      ParseError = ::LibXML::XML::Error
 
-      def parse(xml)
-        node_to_hash(LibXML::XML::Parser.io(xml).parse.root)
+      # 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, namespaces: :strip)
+        node_to_hash(::LibXML::XML::Parser.io(io).parse.root, mode: namespaces)
       end
 
-    private
+      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(&)
 
-      def each_child(node, &block)
-        node.each_child(&block)
+      # Yield each xmlns declaration on this element
+      #
+      # @api private
+      # @param node [LibXML::XML::Node] Element node
+      # @return [void]
+      def each_namespace_decl(node)
+        node.namespaces.definitions.each { |ns| yield ns.prefix, ns.href }
       end
 
-      def each_attr(node, &block)
-        node.each_attr(&block)
+      # 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
 
-      def node_name(node)
-        node.name
+      # Return [prefix, local] for an attribute
+      #
+      # @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