multi_xml 0.7.2 → 0.8.0

data/lib/multi_xml.rb

@@ -3,309 +3,213 @@ require "date"
 require "stringio"
 require "time"
 require "yaml"
-
-module MultiXml # rubocop:disable Metrics/ModuleLength
-  class ParseError < StandardError; end
-
-  class NoParserError < StandardError; end
-
-  class DisallowedTypeError < StandardError
-    def initialize(type)
-      super("Disallowed type attribute: #{type.inspect}")
-    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 Style/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 Style/RescueModifier
-      "base64Binary" => proc { |binary| base64_decode(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
-
+require_relative "multi_xml/constants"
+require_relative "multi_xml/errors"
+require_relative "multi_xml/file_like"
+require_relative "multi_xml/helpers"
+
+# 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
   class << self
-    # Get the current parser class.
-    def parser
-      return @parser if defined?(@parser)
-
-      self.parser = default_parser
-      @parser
-    end
-
-    # 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)
+    include Helpers
 
-      REQUIREMENT_MAP.each do |library, parser|
-        require library
-        return parser
-      rescue LoadError
-        next
-      end
-      raise(NoParserError,
-        "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.")
+    # Get the current XML parser module
+    #
+    # Returns the currently configured parser, auto-detecting one if not set.
+    # Parsers are checked in order of performance: Ox, LibXML, Nokogiri, Oga, REXML.
+    #
+    # @api public
+    # @return [Module] the current parser module
+    # @example Get current parser
+    #   MultiXml.parser #=> MultiXml::Parsers::Ox
+    def parser
+      @parser ||= resolve_parser(detect_parser)
     end
 
-    # Set the XML parser utilizing a symbol, string, or class.
-    # Supported by default are:
+    # Set the XML parser to use
     #
-    # * <tt>:libxml</tt>
-    # * <tt>:nokogiri</tt>
-    # * <tt>:ox</tt>
-    # * <tt>:rexml</tt>
-    # * <tt>:oga</tt>
+    # @api public
+    # @param new_parser [Symbol, String, Module] Parser specification
+    #   - Symbol/String: :libxml, :nokogiri, :ox, :rexml, :oga
+    #   - Module: Custom parser implementing parse(io) 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)
-      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
+      @parser = resolve_parser(new_parser)
     end
 
-    # Parse an XML string or IO into Ruby.
-    #
-    # <b>Options</b>
+    # Parse XML into a Ruby Hash
     #
-    # <tt>:symbolize_keys</tt> :: If true, will use symbols instead of strings for the keys.
-    #
-    # <tt>:disallowed_types</tt> :: Types to disallow from being typecasted. Defaults to `['yaml', 'symbol']`. Use `[]` to allow all types.
-    #
-    # <tt>:typecast_xml_value</tt> :: If true, won't typecast values for parsed document
-    def parse(xml, options = {}) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
-      xml ||= ""
-
+    # @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_keys 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)
+    # @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 keys
+    #   MultiXml.parse('<root><name>John</name></root>', symbolize_keys: true)
+    #   #=> {root: {name: "John"}}
+    def parse(xml, options = {})
       options = DEFAULT_OPTIONS.merge(options)
+      xml_parser = options[:parser] ? resolve_parser(options.fetch(:parser)) : parser
 
-      xml = xml.strip if xml.respond_to?(:strip)
-      begin
-        xml = StringIO.new(xml) unless xml.respond_to?(:read)
+      io = normalize_input(xml)
+      return {} if io.eof?
 
-        char = xml.getc
-        return {} if char.nil?
-
-        xml.ungetc(char)
-
-        hash = undasherize_keys(parser.parse(xml) || {})
-        hash = typecast_xml_value(hash, options[:disallowed_types]) if options[:typecast_xml_value]
-      rescue DisallowedTypeError
-        raise
-      rescue parser.parse_error => e
-        raise(ParseError, e.message, e.backtrace)
-      end
-      hash = symbolize_keys(hash) if options[:symbolize_keys]
-      hash
+      result = parse_with_error_handling(io, xml, xml_parser)
+      result = typecast_xml_value(result, options.fetch(:disallowed_types)) if options.fetch(:typecast_xml_value)
+      result = symbolize_keys(result) if options.fetch(:symbolize_keys)
+      result
     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
+    private
 
-      def content_type
-        @content_type || "application/octet-stream"
+    # Resolve a parser specification to a module
+    #
+    # @api private
+    # @param spec [Symbol, String, Class, Module] Parser specification
+    # @return [Module] Resolved parser module
+    # @raise [RuntimeError] if spec is invalid
+    def resolve_parser(spec)
+      case spec
+      when String, Symbol then load_parser(spec)
+      when Module then spec
+      else raise "Invalid parser specification: expected Symbol, String, or Module"
       end
     end
 
-    private
-
-    # TODO: Add support for other encodings
-    def parse_binary(binary, entity) # :nodoc:
-      case entity["encoding"]
-      when "base64"
-        base64_decode(binary)
-      else
-        binary
-      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
 
-    def parse_file(file, entity)
-      f = StringIO.new(base64_decode(file))
-      f.extend(FileLike)
-      f.original_filename = entity["name"]
-      f.content_type = entity["content_type"]
-      f
+    # 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
 
-    def base64_decode(input)
-      input.unpack1("m")
+    # 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
 
-    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
+    # 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|
+        return parser_name if const_defined?(const_name)
       end
+      nil
     end
 
-    def undasherize_keys(params)
-      case params
-      when Hash
-        params.each_with_object({}) do |(key, value), hash|
-          hash[key.to_s.tr("-", "_")] = undasherize_keys(value)
-          hash
-        end
-      when Array
-        params.collect { |value| undasherize_keys(value) }
-      else
-        params
+    # 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|
+        return parser_name if try_require(library)
       end
+      nil
     end
 
-    def typecast_xml_value(value, disallowed_types = nil) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/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, 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'}
+    # 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
 
-          # 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)) }
+    # 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
 
-          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
+    # 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)
 
-        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.each_with_object({}) do |(k, v), hash|
-            hash[k] = typecast_xml_value(v, disallowed_types)
-            hash
-          end
+      StringIO.new(xml.to_s.strip)
+    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
+    # 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
+    # @return [Hash] Parsed XML with undasherized keys
+    # @raise [ParseError] if XML is malformed
+    def parse_with_error_handling(io, original_input, xml_parser)
+      undasherize_keys(xml_parser.parse(io) || {})
+    rescue xml_parser.parse_error => e
+      xml_string = original_input.respond_to?(:read) ? original_input.tap(&:rewind).read : original_input.to_s
+      raise(ParseError.new(e, xml: xml_string, cause: e))
     end
   end
 end