multi_xml 0.6.0 → 0.8.1

data/lib/multi_xml/version.rb

@@ -1,45 +1,7 @@
 module MultiXml
-  module Version
-  module_function
-
-    # @return [Integer]
-    def major
-      0
-    end
-
-    # @return [Integer]
-    def minor
-      6
-    end
-
-    # @return [Integer]
-    def patch
-      0
-    end
-
-    # @return [Integer, NilClass]
-    def pre
-      nil
-    end
-
-    # @return [Hash]
-    def to_h
-      {
-        :major => major,
-        :minor => minor,
-        :patch => patch,
-        :pre => pre,
-      }
-    end
-
-    # @return [Array]
-    def to_a
-      [major, minor, patch, pre].compact
-    end
-
-    # @return [String]
-    def to_s
-      to_a.join('.')
-    end
-  end
+  # The current version of MultiXml
+  #
+  # @api public
+  # @return [Gem::Version] the gem version
+  VERSION = Gem::Version.create("0.8.1")
 end

data/lib/multi_xml.rb

@@ -1,305 +1,215 @@
-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}"
-    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
-
+require "bigdecimal"
+require "date"
+require "stringio"
+require "time"
+require "yaml"
+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
+    include Helpers
 
-    # 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."))
+    # 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 AbcSize, CyclomaticComplexity, MethodLength, 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 = 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
+      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
+    # 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
 
-    # TODO: Add support for other encodings
-    def parse_binary(binary, entity) #:nodoc:
-      case entity['encoding']
-      when 'base64'
-        Base64.decode64(binary)
-      else
-        binary
-      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
 
-    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
+    # 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.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
+    # 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 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'}
+    # 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.inject({}) do |hash, (k, v)|
-            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