multi_xml 0.6.0 → 0.9.1

data/lib/multi_xml.rb

@@ -1,305 +1,208 @@
-require 'base64'
-require 'bigdecimal'
-require 'date'
-require 'stringio'
-require 'time'
-require 'yaml'
-
-module MultiXml # rubocop:disable ModuleLength
-  class ParseError < StandardError; end
-  class NoParserError < StandardError; end
-  class DisallowedTypeError < StandardError
-    def initialize(type)
-      super "Disallowed type attribute: #{type.inspect}"
+require "bigdecimal"
+require "date"
+require "stringio"
+require "time"
+require "yaml"
+require_relative "multi_xml/concurrency"
+require_relative "multi_xml/constants"
+require_relative "multi_xml/errors"
+require_relative "multi_xml/file_like"
+require_relative "multi_xml/helpers"
+require_relative "multi_xml/options"
+require_relative "multi_xml/options_normalization"
+require_relative "multi_xml/parser"
+require_relative "multi_xml/parser_resolution"
+require_relative "multi_xml/parse_support"
+
+# A generic swappable back-end for parsing XML
+#
+# MultiXML provides a unified interface for XML parsing across different
+# parser libraries. It automatically selects the best available parser
+# (Ox, LibXML, Nokogiri, Oga, or REXML) and converts XML to Ruby hashes.
+#
+# @api public
+# @example Parse XML
+#   MultiXML.parse('<root><name>John</name></root>')
+#   #=> {"root"=>{"name"=>"John"}}
+#
+# @example Set the parser
+#   MultiXML.parser = :nokogiri
+module MultiXML
+  extend Options
+
+  # Tracks which deprecation warnings have already been emitted so each
+  # one fires at most once per process. Stored as a Set rather than a
+  # Hash so presence checks have unambiguous semantics for mutation tests.
+  DEPRECATION_WARNINGS_SHOWN = Set.new
+  private_constant :DEPRECATION_WARNINGS_SHOWN
+
+  # Emit a deprecation warning at most once per process for the given key
+  #
+  # The warning is tagged with the :deprecated category so callers can
+  # silence the whole set with Warning[:deprecated] = false or surface
+  # it via ruby -W:deprecated — the standard Ruby idiom for library
+  # deprecations since 2.7.
+  #
+  # @api private
+  # @param key [Symbol] identifier for the deprecation (typically the method name)
+  # @param message [String] warning message to emit on first call
+  # @return [void]
+  def self.warn_deprecation_once(key, message)
+    Concurrency.synchronize(:deprecation_warnings) do
+      return if DEPRECATION_WARNINGS_SHOWN.include?(key)
+
+      Kernel.warn(message, category: :deprecated)
+      DEPRECATION_WARNINGS_SHOWN.add(key)
     end
   end
 
-  unless defined?(REQUIREMENT_MAP)
-    REQUIREMENT_MAP = [
-      ['ox', :ox],
-      ['libxml', :libxml],
-      ['nokogiri', :nokogiri],
-      ['rexml/document', :rexml],
-      ['oga', :oga],
-    ].freeze
-  end
-
-  CONTENT_ROOT = '__content__'.freeze unless defined?(CONTENT_ROOT)
-
-  unless defined?(PARSING)
-    float_proc = proc { |float| float.to_f }
-    datetime_proc = proc { |time| Time.parse(time).utc rescue DateTime.parse(time).utc } # rubocop:disable RescueModifier
-
-    PARSING = {
-      'symbol'       => proc { |symbol| symbol.to_sym },
-      'date'         => proc { |date| Date.parse(date) },
-      'datetime'     => datetime_proc,
-      'dateTime'     => datetime_proc,
-      'integer'      => proc { |integer| integer.to_i },
-      'float'        => float_proc,
-      'double'       => float_proc,
-      'decimal'      => proc { |number| BigDecimal(number) },
-      'boolean'      => proc { |boolean| !%w(0 false).include?(boolean.strip) },
-      'string'       => proc { |string| string.to_s },
-      'yaml'         => proc { |yaml| YAML.load(yaml) rescue yaml }, # rubocop:disable RescueModifier
-      'base64Binary' => proc { |binary| ::Base64.decode64(binary) },
-      'binary'       => proc { |binary, entity| parse_binary(binary, entity) },
-      'file'         => proc { |file, entity| parse_file(file, entity) },
-    }.freeze
-  end
-
-  unless defined?(TYPE_NAMES)
-    TYPE_NAMES = {
-      'Symbol'     => 'symbol',
-      'Integer'    => 'integer',
-      'BigDecimal' => 'decimal',
-      'Float'      => 'float',
-      'TrueClass'  => 'boolean',
-      'FalseClass' => 'boolean',
-      'Date'       => 'date',
-      'DateTime'   => 'datetime',
-      'Time'       => 'datetime',
-      'Array'      => 'array',
-      'Hash'       => 'hash',
-    }.freeze
-  end
-
-  DISALLOWED_XML_TYPES = %w(symbol yaml).freeze
-
-  DEFAULT_OPTIONS = {
-    :typecast_xml_value => true,
-    :disallowed_types => DISALLOWED_XML_TYPES,
-    :symbolize_keys => false,
-  }.freeze
-
   class << self
-    # Get the current parser class.
-    def parser
-      return @parser if defined?(@parser)
-      self.parser = default_parser
-      @parser
-    end
+    include Helpers
+    include ParserResolution
+    include ParseSupport
 
-    # The default parser based on what you currently
-    # have loaded and installed. First checks to see
-    # if any parsers are already loaded, then checks
-    # to see which are installed if none are loaded.
-    def default_parser
-      return :ox if defined?(::Ox)
-      return :libxml if defined?(::LibXML)
-      return :nokogiri if defined?(::Nokogiri)
-      return :oga if defined?(::Oga)
-
-      REQUIREMENT_MAP.each do |library, parser|
-        begin
-          require library
-          return parser
-        rescue LoadError
-          next
-        end
-      end
-      raise(NoParserError.new("No XML parser detected. If you're using Rubinius and Bundler, try adding an XML parser to your Gemfile (e.g. libxml-ruby, nokogiri, or rubysl-rexml). For more information, see https://github.com/sferik/multi_xml/issues/42."))
-    end
-
-    # Set the XML parser utilizing a symbol, string, or class.
-    # Supported by default are:
-    #
-    # * <tt>:libxml</tt>
-    # * <tt>:nokogiri</tt>
-    # * <tt>:ox</tt>
-    # * <tt>:rexml</tt>
-    # * <tt>:oga</tt>
-    def parser=(new_parser)
-      case new_parser
-      when String, Symbol
-        require "multi_xml/parsers/#{new_parser.to_s.downcase}"
-        @parser = MultiXml::Parsers.const_get(new_parser.to_s.split('_').collect(&:capitalize).join('').to_s)
-      when Class, Module
-        @parser = new_parser
-      else
-        raise('Did not recognize your parser specification. Please specify either a symbol or a class.')
-      end
-    end
-
-    # Parse an XML string or IO into Ruby.
-    #
-    # <b>Options</b>
+    # Get the current XML parser module
     #
-    # <tt>:symbolize_keys</tt> :: If true, will use symbols instead of strings for the keys.
+    # Returns the currently configured parser, auto-detecting one if not set.
+    # Parsers are checked in order of performance: Ox, LibXML, Nokogiri, Oga, REXML.
     #
-    # <tt>:disallowed_types</tt> :: Types to disallow from being typecasted. Defaults to `['yaml', 'symbol']`. Use `[]` to allow all types.
+    # @api public
+    # @return [Module] the current parser module
+    # Honors a fiber-local override set by {.with_parser} so concurrent
+    # blocks observe their own parser without clobbering the process-wide
+    # default. Falls back to the process default when no override is set.
     #
-    # <tt>:typecast_xml_value</tt> :: If true, won't typecast values for parsed document
-    def parse(xml, options = {}) # rubocop:disable AbcSize, CyclomaticComplexity, MethodLength, PerceivedComplexity
-      xml ||= ''
-
-      options = DEFAULT_OPTIONS.merge(options)
-
-      xml = xml.strip if xml.respond_to?(:strip)
-      begin
-        xml = StringIO.new(xml) unless xml.respond_to?(:read)
-
-        char = xml.getc
-        return {} if char.nil?
-        xml.ungetc(char)
-
-        hash = undasherize_keys(parser.parse(xml) || {})
-        hash = options[:typecast_xml_value] ? typecast_xml_value(hash, options[:disallowed_types]) : hash
-      rescue DisallowedTypeError
-        raise
-      rescue parser.parse_error => error
-        raise(ParseError, error.message, error.backtrace) # rubocop:disable RaiseArgs
-      end
-      hash = symbolize_keys(hash) if options[:symbolize_keys]
-      hash
-    end
-
-    # This module decorates files with the <tt>original_filename</tt>
-    # and <tt>content_type</tt> methods.
-    module FileLike #:nodoc:
-      attr_writer :original_filename, :content_type
-
-      def original_filename
-        @original_filename || 'untitled'
-      end
+    # @example Get current parser
+    #   MultiXML.parser #=> MultiXML::Parsers::Ox
+    def parser
+      override = Fiber[:multi_xml_parser]
+      return override if override
 
-      def content_type
-        @content_type || 'application/octet-stream'
-      end
+      @parser ||= resolve_parser(detect_parser)
     end
 
-  private
-
-    # TODO: Add support for other encodings
-    def parse_binary(binary, entity) #:nodoc:
-      case entity['encoding']
-      when 'base64'
-        Base64.decode64(binary)
-      else
-        binary
-      end
+    # Set the XML parser to use
+    #
+    # @api public
+    # @param new_parser [Symbol, String, Module] Parser specification
+    #   - Symbol/String: :libxml, :nokogiri, :ox, :rexml, :oga
+    #   - Module: Custom parser implementing parse(io) or
+    #             parse(io, namespaces: ...) and parse_error
+    # @return [Module] the newly configured parser module
+    # @example Set parser by symbol
+    #   MultiXML.parser = :nokogiri
+    # @example Set parser by module
+    #   MultiXML.parser = MyCustomParser
+    def parser=(new_parser)
+      @parser = resolve_parser(new_parser)
     end
 
-    def parse_file(file, entity)
-      f = StringIO.new(Base64.decode64(file))
-      f.extend(FileLike)
-      f.original_filename = entity['name']
-      f.content_type = entity['content_type']
-      f
+    # Parse XML into a Ruby Hash
+    #
+    # @api public
+    # @param xml [String, IO] XML content as a string or IO-like object
+    # @param options [Hash] Parsing options
+    # @option options [Symbol, String, Module] :parser Parser to use for this call
+    # @option options [Boolean] :symbolize_names Convert keys to symbols (default: false)
+    # @option options [Array<String>] :disallowed_types Types to reject (default: ['yaml', 'symbol'])
+    # @option options [Boolean] :typecast_xml_value Apply type conversions (default: true)
+    # @option options [Symbol] :namespaces Namespace handling mode (:strip or :preserve)
+    # @return [Hash] Parsed XML as nested hash
+    # @raise [ParseError] if XML is malformed
+    # @raise [DisallowedTypeError] if XML contains a disallowed type attribute
+    # @example Parse simple XML
+    #   MultiXML.parse('<root><name>John</name></root>')
+    #   #=> {"root"=>{"name"=>"John"}}
+    # @example Parse with symbolized names
+    #   MultiXML.parse('<root><name>John</name></root>', symbolize_names: true)
+    #   #=> {root: {name: "John"}}
+    def parse(xml, options = {})
+      call_site = OptionsNormalization.normalize_symbolize_option(options)
+      global = OptionsNormalization.normalize_symbolize_option(parse_options(call_site))
+      options = DEFAULT_OPTIONS.merge(global, call_site)
+      namespaces = validate_namespaces_mode(options.fetch(:namespaces))
+      io = normalize_input(xml)
+      return {} if io.eof?
+
+      result = parse_with_error_handling(io, xml, resolve_parse_parser(options), namespaces)
+      apply_postprocessing(result, options)
     end
+  end
 
-    def symbolize_keys(params)
-      case params
-      when Hash
-        params.inject({}) do |result, (key, value)|
-          result.merge(key.to_sym => symbolize_keys(value))
-        end
-      when Array
-        params.collect { |value| symbolize_keys(value) }
-      else
-        params
-      end
-    end
+  # Execute a block with a temporarily-swapped parser
+  #
+  # The override is stored in fiber-local storage so concurrent fibers
+  # and threads each see their own parser without racing on a shared
+  # module variable; nested calls save and restore the previous
+  # fiber-local value. Matches {MultiJSON.with_adapter}.
+  #
+  # @api public
+  # @param new_parser [Symbol, String, Module] parser to use
+  # @yield block to execute with the temporary parser
+  # @return [Object] result of the block
+  # @example
+  #   MultiXML.with_parser(:rexml) { MultiXML.parse("<a>1</a>") }
+  def self.with_parser(new_parser)
+    previous_override = Fiber[:multi_xml_parser]
+    Fiber[:multi_xml_parser] = resolve_parser(new_parser)
+    yield
+  ensure
+    Fiber[:multi_xml_parser] = previous_override
+  end
+end
 
-    def undasherize_keys(params)
-      case params
-      when Hash
-        params.inject({}) do |hash, (key, value)|
-          hash[key.to_s.tr('-'.freeze, '_'.freeze)] = undasherize_keys(value)
-          hash
-        end
-      when Array
-        params.collect { |value| undasherize_keys(value) }
-      else
-        params
-      end
+require_relative "multi_xml/deprecated"
+
+# Backward-compatible alias for the legacy MultiXml constant name
+#
+# Downstream code that still writes MultiXml.parse(...) or
+# rescue MultiXml::ParseError continues to work, but emits a one-time
+# deprecation warning pointing at MultiXML. Each public method on
+# {MultiXML} gets an explicit forwarder defined on this module, and
+# constant access resolves via {.const_missing}, so both dotted calls
+# and :: constant lookups (including rescue clauses) route through
+# the canonical module.
+#
+# @api public
+# @deprecated Use {MultiXML} (all-caps) instead. Will be removed in v1.0.
+module MultiXml
+  # Forward every public method MultiXML exposes through an explicit
+  # singleton method on the legacy MultiXml module, so callers that
+  # capture the method as a Method object (``MultiXml.method(:load)``)
+  # find this forwarder instead of falling back to inherited methods like
+  # ``Kernel#load``. The earlier ``method_missing``-based shim left
+  # ``MultiXml.method(:load)`` resolving to ``Kernel#load`` (because
+  # ``Module#method`` doesn't consult ``method_missing``) so a captured
+  # ``MultiXml.method(:load)`` would interpret the XML payload as a file
+  # path and crash with ``LoadError``. Forwarding eagerly fixes the
+  # capture path while preserving the one-time deprecation warning each
+  # call emits.
+  (::MultiXML.public_methods - ::Module.public_methods).each do |forwarded|
+    define_singleton_method(forwarded) do |*args, **kwargs, &block|
+      ::MultiXML.warn_deprecation_once(:multi_xml_constant,
+        "The MultiXml constant is deprecated and will be removed in v1.0. Use MultiXML instead.")
+      ::MultiXML.public_send(forwarded, *args, **kwargs, &block)
     end
+  end
 
-    def typecast_xml_value(value, disallowed_types = nil) # rubocop:disable AbcSize, CyclomaticComplexity, MethodLength, PerceivedComplexity
-      disallowed_types ||= DISALLOWED_XML_TYPES
-
-      case value
-      when Hash
-        if value.include?('type') && !value['type'].is_a?(Hash) && disallowed_types.include?(value['type'])
-          raise(DisallowedTypeError.new(value['type']))
-        end
-
-        if value['type'] == 'array'
-
-          # this commented-out suggestion helps to avoid the multiple attribute
-          # problem, but it breaks when there is only one item in the array.
-          #
-          # from: https://github.com/jnunemaker/httparty/issues/102
-          #
-          # _, entries = value.detect { |k, v| k != 'type' && v.is_a?(Array) }
-
-          # This attempt fails to consider the order that the detect method
-          # retrieves the entries.
-          # _, entries = value.detect {|key, _| key != 'type'}
-
-          # This approach ignores attribute entries that are not convertable
-          # to an Array which allows attributes to be ignored.
-          _, entries = value.detect { |k, v| k != 'type' && (v.is_a?(Array) || v.is_a?(Hash)) }
-
-          case entries
-          when NilClass
-            []
-          when String
-            [] if entries.strip.empty?
-          when Array
-            entries.collect { |entry| typecast_xml_value(entry, disallowed_types) }
-          when Hash
-            [typecast_xml_value(entries, disallowed_types)]
-          else
-            raise("can't typecast #{entries.class.name}: #{entries.inspect}")
-          end
-
-        elsif value.key?(CONTENT_ROOT)
-          content = value[CONTENT_ROOT]
-          block = PARSING[value['type']]
-          if block
-            if block.arity == 1
-              value.delete('type') if PARSING[value['type']]
-              if value.keys.size > 1
-                value[CONTENT_ROOT] = block.call(content)
-                value
-              else
-                block.call(content)
-              end
-            else
-              block.call(content, value)
-            end
-          else
-            value.keys.size > 1 ? value : content
-          end
-        elsif value['type'] == 'string' && value['nil'] != 'true'
-          ''
-        # blank or nil parsed values are represented by nil
-        elsif value.empty? || value['nil'] == 'true'
-          nil
-        # If the type is the only element which makes it then
-        # this still makes the value nil, except if type is
-        # a XML node(where type['value'] is a Hash)
-        elsif value['type'] && value.size == 1 && !value['type'].is_a?(Hash)
-          nil
-        else
-          xml_value = value.inject({}) do |hash, (k, v)|
-            hash[k] = typecast_xml_value(v, disallowed_types)
-            hash
-          end
-
-          # Turn {:files => {:file => #<StringIO>} into {:files => #<StringIO>} so it is compatible with
-          # how multipart uploaded files from HTML appear
-          xml_value['file'].is_a?(StringIO) ? xml_value['file'] : xml_value
-        end
-      when Array
-        value.map! { |i| typecast_xml_value(i, disallowed_types) }
-        value.length > 1 ? value : value.first
-      when String
-        value
-      else
-        raise("can't typecast #{value.class.name}: #{value.inspect}")
-      end
+  class << self
+    # Resolve missing constants to their {MultiXML} counterparts
+    #
+    # The lookup is performed with ``inherit: false`` so a stray
+    # top-level ``::ParseError`` constant in the host process (Racc
+    # defines one when Nokogiri is loaded) is correctly ignored. Enables
+    # rescue MultiXml::ParseError and MultiXml::Parsers::Ox to keep
+    # working during the deprecation cycle.
+    #
+    # @api public
+    # @param name [Symbol] constant name
+    # @return [Object] the resolved constant from {MultiXML}
+    # @example
+    #   MultiXml::Parsers::Ox  # returns MultiXML::Parsers::Ox
+    def const_missing(name)
+      ::MultiXML.warn_deprecation_once(:multi_xml_constant,
+        "The MultiXml constant is deprecated and will be removed in v1.0. Use MultiXML instead.")
+      ::MultiXML.const_get(name, false)
     end
   end
 end