multi_xml 0.7.2 → 0.8.0

data/lib/multi_xml/helpers.rb

@@ -0,0 +1,228 @@
+module MultiXml
+  # Methods for transforming parsed XML hash structures
+  #
+  # These helper methods handle key transformation and type casting
+  # of parsed XML data structures.
+  #
+  # @api public
+  module Helpers
+    module_function
+
+    # Recursively convert all hash keys to symbols
+    #
+    # @api private
+    # @param data [Hash, Array, Object] Data to transform
+    # @return [Hash, Array, Object] Transformed data with symbolized keys
+    # @example Symbolize hash keys
+    #   symbolize_keys({"name" => "John"}) #=> {name: "John"}
+    def symbolize_keys(data)
+      transform_keys(data, &:to_sym)
+    end
+
+    # Recursively convert dashes in hash keys to underscores
+    #
+    # @api private
+    # @param data [Hash, Array, Object] Data to transform
+    # @return [Hash, Array, Object] Transformed data with undasherized keys
+    # @example Convert dashed keys
+    #   undasherize_keys({"first-name" => "John"}) #=> {"first_name" => "John"}
+    def undasherize_keys(data)
+      transform_keys(data) { |key| key.tr("-", "_") }
+    end
+
+    # Recursively typecast XML values based on type attributes
+    #
+    # @api private
+    # @param value [Hash, Array, Object] Value to typecast
+    # @param disallowed_types [Array<String>] Types to reject
+    # @return [Object] Typecasted value
+    # @raise [DisallowedTypeError] if a disallowed type is encountered
+    # @example Typecast integer value
+    #   typecast_xml_value({"__content__" => "42", "type" => "integer"})
+    #   #=> 42
+    def typecast_xml_value(value, disallowed_types = DISALLOWED_TYPES)
+      case value
+      when Hash then typecast_hash(value, disallowed_types)
+      when Array then typecast_array(value, disallowed_types)
+      else value
+      end
+    end
+
+    # Typecast array elements and unwrap single-element arrays
+    #
+    # @api private
+    # @param array [Array] Array to typecast
+    # @param disallowed_types [Array<String>] Types to reject
+    # @return [Object, Array] Typecasted array or single element
+    def typecast_array(array, disallowed_types)
+      array.map! { |item| typecast_xml_value(item, disallowed_types) }
+      array.one? ? array.first : array
+    end
+
+    # Typecast a hash based on its type attribute
+    #
+    # @api private
+    # @param hash [Hash] Hash to typecast
+    # @param disallowed_types [Array<String>] Types to reject
+    # @return [Object] Typecasted value
+    # @raise [DisallowedTypeError] if type is disallowed
+    def typecast_hash(hash, disallowed_types)
+      type = hash["type"]
+      raise DisallowedTypeError, type if disallowed_type?(type, disallowed_types)
+
+      convert_hash(hash, type, disallowed_types)
+    end
+
+    # Check if a type is in the disallowed list
+    #
+    # @api private
+    # @param type [String, nil] Type to check
+    # @param disallowed_types [Array<String>] Disallowed type list
+    # @return [Boolean] true if type is disallowed
+    def disallowed_type?(type, disallowed_types)
+      type && !type.is_a?(Hash) && disallowed_types.include?(type)
+    end
+
+    # Convert a hash based on its type and content
+    #
+    # @api private
+    # @param hash [Hash] Hash to convert
+    # @param type [String, nil] Type attribute value
+    # @param disallowed_types [Array<String>] Types to reject
+    # @return [Object] Converted value
+    def convert_hash(hash, type, disallowed_types)
+      return extract_array_entries(hash, disallowed_types) if type == "array"
+      return convert_text_content(hash) if hash.key?(TEXT_CONTENT_KEY)
+      return "" if type == "string" && !hash["nil"].eql?("true")
+      return nil if empty_value?(hash, type)
+
+      typecast_children(hash, disallowed_types)
+    end
+
+    # Typecast all child values in a hash
+    #
+    # @api private
+    # @param hash [Hash] Hash with children to typecast
+    # @param disallowed_types [Array<String>] Types to reject
+    # @return [Hash, StringIO] Typecasted hash or unwrapped file
+    def typecast_children(hash, disallowed_types)
+      result = hash.transform_values { |v| typecast_xml_value(v, disallowed_types) }
+      unwrap_file_if_present(result)
+    end
+
+    # Extract array entries from element with type="array"
+    #
+    # @api private
+    # @param hash [Hash] Hash containing array entries
+    # @param disallowed_types [Array<String>] Types to reject
+    # @return [Array] Extracted and typecasted entries
+    # @see https://github.com/jnunemaker/httparty/issues/102
+    def extract_array_entries(hash, disallowed_types)
+      entries = find_array_entries(hash)
+      return [] unless entries
+
+      wrap_and_typecast(entries, disallowed_types)
+    end
+
+    # Find array or hash entries in a hash, excluding the type key
+    #
+    # @api private
+    # @param hash [Hash] Hash to search
+    # @return [Array, Hash, nil] Found entries or nil
+    def find_array_entries(hash)
+      hash.each do |key, value|
+        return value if !key.eql?("type") && (value.is_a?(Array) || value.is_a?(Hash))
+      end
+      nil
+    end
+
+    # Wrap hash in array if needed and typecast all entries
+    #
+    # @api private
+    # @param entries [Array, Hash] Entries to process
+    # @param disallowed_types [Array<String>] Types to reject
+    # @return [Array] Typecasted entries
+    def wrap_and_typecast(entries, disallowed_types)
+      entries = [entries] if entries.is_a?(Hash)
+      entries.map { |entry| typecast_xml_value(entry, disallowed_types) }
+    end
+
+    # Convert text content using type converters
+    #
+    # @api private
+    # @param hash [Hash] Hash containing text content and type
+    # @return [Object] Converted value
+    def convert_text_content(hash)
+      content = hash.fetch(TEXT_CONTENT_KEY)
+      converter = TYPE_CONVERTERS[hash["type"]]
+
+      return unwrap_if_simple(hash, content) unless converter
+
+      apply_converter(hash, content, converter)
+    end
+
+    # Unwrap value if hash has no other significant keys
+    #
+    # @api private
+    # @param hash [Hash] Original hash
+    # @param value [Object] Converted value
+    # @return [Object, Hash] Value or hash with merged content
+    def unwrap_if_simple(hash, value)
+      (hash.size > 1) ? hash.merge(TEXT_CONTENT_KEY => value) : value
+    end
+
+    # Check if a hash represents an empty value
+    #
+    # @api private
+    # @param hash [Hash] Hash to check
+    # @param type [String, nil] Type attribute value
+    # @return [Boolean] true if value should be nil
+    def empty_value?(hash, type)
+      hash.empty? ||
+        hash["nil"] == "true" ||
+        (type && hash.size == 1 && !type.is_a?(Hash))
+    end
+
+    private
+
+    # Recursively transform hash keys using a block
+    #
+    # @api private
+    # @param data [Hash, Array, Object] Data to transform
+    # @return [Hash, Array, Object] Transformed data
+    def transform_keys(data, &block)
+      case data
+      when Hash then data.each_with_object(
+        {} #: Hash[Symbol, MultiXml::xmlValue] # rubocop:disable Layout/LeadingCommentSpace
+      ) { |(key, value), acc| acc[yield(key)] = transform_keys(value, &block) }
+      when Array then data.map { |item| transform_keys(item, &block) }
+      else data
+      end
+    end
+
+    # Unwrap a file object from the result hash if present
+    #
+    # @api private
+    # @param result [Hash] Hash that may contain a file
+    # @return [Hash, StringIO] The file if present, otherwise the hash
+    def unwrap_file_if_present(result)
+      file = result["file"]
+      file.is_a?(StringIO) ? file : result
+    end
+
+    # Apply a type converter to content
+    #
+    # @api private
+    # @param hash [Hash] Original hash with type info
+    # @param content [String] Content to convert
+    # @param converter [Proc] Converter to apply
+    # @return [Object] Converted value
+    def apply_converter(hash, content, converter)
+      # Binary converters need access to entity attributes (e.g., encoding, name)
+      return converter.call(content, hash) if converter.arity == 2
+
+      hash.delete("type")
+      unwrap_if_simple(hash, converter.call(content))
+    end
+  end
+end

data/lib/multi_xml/parsers/dom_parser.rb

@@ -0,0 +1,97 @@
+module MultiXml
+  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
+    #
+    # @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
+      # @return [Hash] Hash representation of the node
+      def node_to_hash(node, hash = {})
+        node_hash = {TEXT_CONTENT_KEY => +""}
+        add_value(hash, node_name(node), node_hash)
+        collect_children(node, node_hash)
+        collect_attributes(node, node_hash)
+        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
+      # @return [void]
+      def collect_children(node, node_hash)
+        each_child(node) do |child|
+          if child.element?
+            node_to_hash(child, node_hash)
+          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 all attributes from a node
+      #
+      # @api private
+      # @param node [Object] Node with attributes
+      # @param node_hash [Hash] Hash to populate
+      # @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
+        end
+      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,33 +1,50 @@
-require "libxml" unless defined?(LibXML)
-require "multi_xml/parsers/libxml2_parser"
+require "libxml"
+require_relative "dom_parser"
 
 module MultiXml
   module Parsers
-    module Libxml # :nodoc:
-      include Libxml2Parser
+    # XML parser using the LibXML library
+    #
+    # @api private
+    module Libxml
+      include DomParser
       extend self
 
-      def parse_error
-        ::LibXML::XML::Error
-      end
+      # Get the parse error class for this parser
+      #
+      # @api private
+      # @return [Class] LibXML::XML::Error
+      def parse_error = ::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
+      # @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)
       end
 
       private
 
-      def each_child(node, &)
-        node.each_child(&)
-      end
+      # Iterate over child nodes
+      #
+      # @param node [LibXML::XML::Node] Parent node
+      # @return [void]
+      def each_child(node, &) = node.each_child(&)
 
-      def each_attr(node, &)
-        node.each_attr(&)
-      end
+      # Iterate over attribute nodes
+      #
+      # @param node [LibXML::XML::Node] Element node
+      # @return [void]
+      def each_attr(node, &) = node.each_attr(&)
 
-      def node_name(node)
-        node.name
-      end
+      # Get the name of a node or attribute
+      #
+      # @param node [LibXML::XML::Node] Node to get name from
+      # @return [String] Node name
+      def node_name(node) = node.name
     end
   end
 end

data/lib/multi_xml/parsers/libxml_sax.rb

@@ -0,0 +1,103 @@
+require "libxml"
+require "stringio"
+require_relative "sax_handler"
+
+module MultiXml
+  module Parsers
+    # SAX-based parser using LibXML (faster for large documents)
+    #
+    # @api private
+    module LibxmlSax
+      module_function
+
+      # Get the parse error class for this parser
+      #
+      # @api private
+      # @return [Class] LibXML::XML::Error
+      def parse_error = ::LibXML::XML::Error
+
+      # Parse XML from a string or IO object
+      #
+      # @api private
+      # @param xml [String, IO] XML content
+      # @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?
+
+        LibXML::XML::Error.set_handler(&LibXML::XML::Error::QUIET_HANDLER)
+        handler = Handler.new
+        parser = ::LibXML::XML::SaxParser.io(io)
+        parser.callbacks = handler
+        parser.parse
+        handler.result
+      end
+
+      # LibXML SAX handler that builds a hash tree while parsing
+      #
+      # @api private
+      class Handler
+        include ::LibXML::XML::SaxParser::Callbacks
+        include SaxHandler
+
+        # Create a new SAX handler
+        #
+        # @api private
+        # @return [Handler] new handler instance
+        def initialize
+          initialize_handler
+        end
+
+        # Handle start of document (no-op)
+        #
+        # @api private
+        # @return [void]
+        def on_start_document
+        end
+
+        # Handle end of document (no-op)
+        #
+        # @api private
+        # @return [void]
+        def on_end_document
+        end
+
+        # Handle parse errors (no-op, LibXML raises directly)
+        #
+        # @api private
+        # @param _error [String] Error message (unused)
+        # @return [void]
+        def on_error(_error)
+        end
+
+        # Handle start of an element
+        #
+        # @api private
+        # @param name [String] Element name
+        # @param attrs [Hash] Element attributes
+        # @return [void]
+        def on_start_element(name, attrs = {})
+          handle_start_element(name, attrs)
+        end
+
+        # Handle end of an element
+        #
+        # @api private
+        # @param _name [String] Element name (unused)
+        # @return [void]
+        def on_end_element(_name)
+          handle_end_element
+        end
+
+        # Handle character data
+        #
+        # @api private
+        # @param text [String] Text content
+        # @return [void]
+        def on_characters(text) = append_text(text)
+        alias_method :on_cdata_block, :on_characters
+      end
+    end
+  end
+end

data/lib/multi_xml/parsers/nokogiri.rb

@@ -1,36 +1,53 @@
-require "nokogiri" unless defined?(Nokogiri)
-require "multi_xml/parsers/libxml2_parser"
+require "nokogiri"
+require_relative "dom_parser"
 
 module MultiXml
   module Parsers
-    module Nokogiri # :nodoc:
-      include Libxml2Parser
+    # XML parser using the Nokogiri library
+    #
+    # @api private
+    module Nokogiri
+      include DomParser
       extend self
 
-      def parse_error
-        ::Nokogiri::XML::SyntaxError
-      end
-
-      def parse(xml)
-        doc = ::Nokogiri::XML(xml)
-        raise(doc.errors.first) unless doc.errors.empty?
+      # Get the parse error class for this parser
+      #
+      # @api private
+      # @return [Class] Nokogiri::XML::SyntaxError
+      def parse_error = ::Nokogiri::XML::SyntaxError
+
+      # Parse XML from an IO object
+      #
+      # @api private
+      # @param io [IO] IO-like object containing XML
+      # @return [Hash] Parsed XML as a hash
+      # @raise [Nokogiri::XML::SyntaxError] if XML is malformed
+      def parse(io)
+        doc = ::Nokogiri::XML(io)
+        raise doc.errors.first unless doc.errors.empty?
 
         node_to_hash(doc.root)
       end
 
       private
 
-      def each_child(node, &)
-        node.children.each(&)
-      end
-
-      def each_attr(node, &)
-        node.attribute_nodes.each(&)
-      end
-
-      def node_name(node)
-        node.node_name
-      end
+      # Iterate over child nodes
+      #
+      # @param node [Nokogiri::XML::Node] Parent node
+      # @return [void]
+      def each_child(node, &) = node.children.each(&)
+
+      # Iterate over attribute nodes
+      #
+      # @param node [Nokogiri::XML::Node] Element node
+      # @return [void]
+      def each_attr(node, &) = node.attribute_nodes.each(&)
+
+      # Get the name of a node or attribute
+      #
+      # @param node [Nokogiri::XML::Node] Node to get name from
+      # @return [String] Node name
+      def node_name(node) = node.node_name
     end
   end
 end

data/lib/multi_xml/parsers/nokogiri_sax.rb

@@ -0,0 +1,102 @@
+require "nokogiri"
+require "stringio"
+require_relative "sax_handler"
+
+module MultiXml
+  module Parsers
+    # SAX-based parser using Nokogiri (faster for large documents)
+    #
+    # @api private
+    module NokogiriSax
+      module_function
+
+      # Get the parse error class for this parser
+      #
+      # @api private
+      # @return [Class] Nokogiri::XML::SyntaxError
+      def parse_error = ::Nokogiri::XML::SyntaxError
+
+      # Parse XML from a string or IO object
+      #
+      # @api private
+      # @param xml [String, IO] XML content
+      # @return [Hash] Parsed XML as a hash
+      # @raise [Nokogiri::XML::SyntaxError] if XML is malformed
+      def parse(xml)
+        io = xml.respond_to?(:read) ? xml : StringIO.new(xml)
+        return {} if io.eof?
+
+        handler = Handler.new
+        ::Nokogiri::XML::SAX::Parser.new(handler).parse(io)
+        handler.result
+      end
+
+      # Nokogiri SAX handler that builds a hash tree while parsing
+      #
+      # @api private
+      class Handler < ::Nokogiri::XML::SAX::Document
+        include SaxHandler
+
+        # Create a new SAX handler
+        #
+        # @api private
+        # @return [Handler] new handler instance
+        def initialize
+          super
+          initialize_handler
+        end
+
+        # Handle start of document (no-op)
+        #
+        # @api private
+        # @return [void]
+        def start_document
+        end
+
+        # Handle end of document (no-op)
+        #
+        # @api private
+        # @return [void]
+        def end_document
+        end
+
+        # Handle parse errors
+        #
+        # @api private
+        # @param message [String] Error message
+        # @return [void]
+        # @raise [Nokogiri::XML::SyntaxError] always
+        def error(message)
+          raise ::Nokogiri::XML::SyntaxError, message
+        end
+
+        # Handle start of an element
+        #
+        # @api private
+        # @param name [String] Element name
+        # @param attrs [Array] Element attributes as pairs
+        # @return [void]
+        def start_element(name, attrs = [])
+          handle_start_element(name, attrs)
+        end
+
+        # Handle end of an element
+        #
+        # @api private
+        # @param _name [String] Element name (unused)
+        # @return [void]
+        def end_element(_name)
+          handle_end_element
+        end
+
+        # Handle character data
+        #
+        # @api private
+        # @param text [String] Text content
+        # @return [void]
+        def characters(text) = append_text(text)
+        alias_method :cdata_block, :characters
+      end
+    end
+  end
+end