multi_xml 0.7.2 → 0.8.0

data/lib/multi_xml/parsers/oga.rb

@@ -1,71 +1,68 @@
-require "oga" unless defined?(Oga)
-require "multi_xml/parsers/libxml2_parser"
+require "oga"
+require_relative "dom_parser"
 
 module MultiXml
   module Parsers
-    module Oga # :nodoc:
-      include Libxml2Parser
+    # XML parser using the Oga library
+    #
+    # @api private
+    module Oga
+      include DomParser
       extend self
 
-      def parse_error
-        LL::ParserError
-      end
+      # Get the parse error class for this parser
+      #
+      # @api private
+      # @return [Class] LL::ParserError
+      def parse_error = LL::ParserError
 
+      # Parse XML from an IO object
+      #
+      # @api private
+      # @param io [IO] IO-like object containing XML
+      # @return [Hash] Parsed XML as a hash
+      # @raise [LL::ParserError] if XML is malformed
       def parse(io)
-        document = ::Oga.parse_xml(io)
-        node_to_hash(document.children[0])
+        doc = ::Oga.parse_xml(io)
+        node_to_hash(doc.children.first)
       end
 
-      def node_to_hash(node, hash = {}) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
-        node_hash = {MultiXml::CONTENT_ROOT => ""}
-
-        name = node_name(node)
-
-        # Insert node hash into parent hash correctly.
-        case hash[name]
-        when Array
-          hash[name] << node_hash
-        when Hash
-          hash[name] = [hash[name], node_hash]
-        when NilClass
-          hash[name] = node_hash
-        end
-
-        # Handle child elements
-        each_child(node) do |c|
-          if c.is_a?(::Oga::XML::Element)
-            node_to_hash(c, node_hash)
-          elsif c.is_a?(::Oga::XML::Text) || c.is_a?(::Oga::XML::Cdata)
-            node_hash[MultiXml::CONTENT_ROOT] += c.text
+      # Collect child nodes into a hash (Oga-specific implementation)
+      #
+      # Oga uses different node types than Nokogiri/LibXML.
+      #
+      # @api private
+      # @param node [Oga::XML::Element] Parent node
+      # @param node_hash [Hash] Hash to populate
+      # @return [void]
+      def collect_children(node, node_hash)
+        each_child(node) do |child|
+          case child
+          when ::Oga::XML::Element then node_to_hash(child, node_hash)
+          when ::Oga::XML::Text, ::Oga::XML::Cdata then node_hash[TEXT_CONTENT_KEY] << child.text
           end
         end
-
-        # Remove content node if it is empty
-        node_hash.delete(MultiXml::CONTENT_ROOT) if node_hash[MultiXml::CONTENT_ROOT].strip.empty?
-
-        # Handle attributes
-        each_attr(node) do |a|
-          key = node_name(a)
-          v = node_hash[key]
-          node_hash[key] = ((v) ? [a.value, v] : a.value)
-        end
-
-        hash
       end
 
       private
 
-      def each_child(node, &)
-        node.children.each(&)
-      end
+      # Iterate over child nodes
+      #
+      # @param node [Oga::XML::Element] Parent node
+      # @return [void]
+      def each_child(node, &) = node.children.each(&)
 
-      def each_attr(node, &)
-        node.attributes.each(&)
-      end
+      # Iterate over attribute nodes
+      #
+      # @param node [Oga::XML::Element] Element node
+      # @return [void]
+      def each_attr(node, &) = node.attributes.each(&)
 
-      def node_name(node)
-        node.name
-      end
+      # Get the name of a node or attribute
+      #
+      # @param node [Oga::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/ox.rb

@@ -1,89 +1,131 @@
-require "ox" unless defined?(Ox)
-
-# Each MultiXml parser is expected to parse an XML document into a Hash. The
-# conversion rules are:
-#
-# - Each document starts out as an empty Hash.
-#
-# - Reading an element created an entry in the parent Hash that has a key of
-#   the element name and a value of a Hash with attributes as key value
-#   pairs. Children are added as described by this rule.
-#
-# - Text and CDATE is stored in the parent element Hash with a key of
-#   MultiXml::CONTENT_ROOT and a value of the text itself.
-#
-# - If a key already exists in the Hash then the value associated with the key
-#   is converted to an Array with the old and new value in it.
-#
-# - Other elements such as the xml prolog, doctype, and comments are ignored.
-#
+require "ox"
 
 module MultiXml
   module Parsers
-    module Ox # :nodoc:
+    # XML parser using the Ox library (fastest pure-Ruby parser)
+    #
+    # @api private
+    module Ox
       module_function
 
-      def parse_error
-        Exception
-      end
+      # Get the parse error class for this parser
+      #
+      # @api private
+      # @return [Class] Ox::ParseError
+      def parse_error = ::Ox::ParseError
 
+      # Parse XML from an IO object
+      #
+      # @api private
+      # @param io [IO] IO-like object containing XML
+      # @return [Hash] Parsed XML as a hash
       def parse(io)
         handler = Handler.new
         ::Ox.sax_parse(handler, io, convert_special: true, skip: :skip_return)
-        handler.doc
+        handler.result
       end
 
+      # SAX event handler that builds a hash tree while parsing
+      #
+      # @api private
       class Handler
-        attr_accessor :stack
-
+        # Create a new SAX handler
+        #
+        # @return [Handler] new handler instance
         def initialize
           @stack = []
         end
 
-        def doc
-          @stack[0]
-        end
+        # Get the parsed result
+        #
+        # @return [Hash, nil] the root hash or nil if empty
+        def result = @stack.first
 
-        def attr(name, value)
-          append(name, value) unless @stack.empty?
+        # Handle start of an element
+        #
+        # @param name [Symbol] Element name
+        # @return [void]
+        def start_element(name)
+          @stack << {} if @stack.empty?
+          child = {}
+          add_value(name.to_s, child)
+          @stack << child
         end
 
-        def text(value)
-          append(MultiXml::CONTENT_ROOT, value)
+        # Handle end of an element
+        #
+        # @param _name [Symbol] Element name (unused)
+        # @return [void]
+        def end_element(_name)
+          strip_whitespace_content if current.key?(TEXT_CONTENT_KEY)
+          @stack.pop
         end
 
-        def cdata(value)
-          append(MultiXml::CONTENT_ROOT, value)
+        # Handle an attribute
+        #
+        # @param name [Symbol] Attribute name
+        # @param value [String] Attribute value
+        # @return [void]
+        def attr(name, value)
+          add_value(name.to_s, value) unless @stack.empty?
         end
 
-        def start_element(name)
-          @stack.push({}) if @stack.empty?
-          h = {}
-          append(name, h)
-          @stack.push(h)
+        # Handle text content
+        #
+        # @param value [String] Text content
+        # @return [void]
+        def text(value) = add_value(TEXT_CONTENT_KEY, value)
+
+        # Handle CDATA content
+        #
+        # @param value [String] CDATA content
+        # @return [void]
+        def cdata(value) = add_value(TEXT_CONTENT_KEY, value)
+
+        # Handle parse errors
+        #
+        # @param message [String] Error message
+        # @param line [Integer] Line number
+        # @param column [Integer] Column number
+        # @return [void]
+        # @raise [Ox::ParseError] always
+        def error(message, line, column)
+          raise ::Ox::ParseError, "#{message} at #{line}:#{column}"
         end
 
-        def end_element(_)
-          @stack.pop
+        private
+
+        # Get the current element hash
+        #
+        # @return [Hash] current hash being built
+        def current = @stack.last
+
+        # Add a value to the current hash, merging with existing if needed
+        #
+        # @param key [String] Key to add
+        # @param value [Object] Value to add
+        # @return [void]
+        def add_value(key, value)
+          existing = current[key]
+          current[key] = existing ? merge_values(existing, value) : value
         end
 
-        def error(message, line, column)
-          raise(StandardError, "#{message} at #{line}:#{column}")
+        # Merge a value with an existing value, creating array if needed
+        #
+        # @param existing [Object] Existing value
+        # @param value [Object] Value to append
+        # @return [Array] array with both values
+        def merge_values(existing, value)
+          existing.is_a?(Array) ? existing << value : [existing, value]
         end
 
-        def append(key, value)
-          key = key.to_s
-          h = @stack.last
-          if h.key?(key)
-            v = h[key]
-            if v.is_a?(Array)
-              v << value
-            else
-              h[key] = [v, value]
-            end
-          else
-            h[key] = value
-          end
+        # Remove empty or whitespace-only text content
+        #
+        # @return [void]
+        def strip_whitespace_content
+          content = current[TEXT_CONTENT_KEY]
+          should_remove = content.empty? || (current.size > 1 && content.strip.empty?)
+          current.delete(TEXT_CONTENT_KEY) if should_remove
         end
       end
     end

data/lib/multi_xml/parsers/rexml.rb

@@ -1,111 +1,117 @@
-require "rexml/document" unless defined?(REXML::Document)
+require "rexml/document"
 
 module MultiXml
   module Parsers
-    module Rexml # :nodoc:
+    # XML parser using Ruby's built-in REXML library
+    #
+    # @api private
+    module Rexml
       extend self
 
-      def parse_error
-        ::REXML::ParseException
-      end
-
-      # Parse an XML Document IO into a simple hash using REXML
+      # Get the parse error class for this parser
       #
-      # xml::
-      #   XML Document IO to parse
-      def parse(xml)
-        doc = REXML::Document.new(xml)
-        raise(REXML::ParseException, "The document #{doc.to_s.inspect} does not have a valid root") unless doc.root
+      # @api private
+      # @return [Class] REXML::ParseException
+      def parse_error = ::REXML::ParseException
 
-        merge_element!({}, doc.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 [REXML::ParseException] if XML is malformed
+      def parse(io)
+        doc = REXML::Document.new(io)
+        element_to_hash({}, doc.root)
       end
 
       private
 
-      # Convert an XML element and merge into the hash
+      # Convert an element to hash format
       #
-      # hash::
-      #   Hash to merge the converted element into.
-      # element::
-      #   XML element to merge into hash
-      def merge_element!(hash, element)
-        merge!(hash, element.name, collapse(element))
+      # @api private
+      # @param hash [Hash] Accumulator hash
+      # @param element [REXML::Element] Element to convert
+      # @return [Hash] Updated hash
+      def element_to_hash(hash, element)
+        add_to_hash(hash, element.name, collapse_element(element))
       end
 
-      # Actually converts an XML document element into a data structure.
+      # Collapse an element into a hash with attributes and content
       #
-      # element::
-      #   The document element to be collapsed.
-      def collapse(element)
-        hash = get_attributes(element)
+      # @api private
+      # @param element [REXML::Element] Element to collapse
+      # @return [Hash] Hash representation
+      def collapse_element(element)
+        node_hash = collect_attributes(element)
 
         if element.has_elements?
-          element.each_element { |child| merge_element!(hash, child) }
-          merge_texts!(hash, element) unless empty_content?(element)
-          hash
-        else
-          merge_texts!(hash, element)
+          collect_child_elements(element, node_hash)
+          add_text_content(node_hash, element) unless whitespace_only?(element)
+        elsif node_hash.empty? || !whitespace_only?(element)
+          add_text_content(node_hash, element)
         end
+
+        node_hash
       end
 
-      # Merge all the texts of an element into the hash
+      # Collect all attributes from an element into a hash
       #
-      # hash::
-      #   Hash to add the converted element to.
-      # element::
-      #   XML element whose texts are to me merged into the hash
-      def merge_texts!(hash, element)
-        if element.has_text?
-          # must use value to prevent double-escaping
-          texts = element.texts.map(&:value).join
-          merge!(hash, MultiXml::CONTENT_ROOT, texts)
-        else
-          hash
-        end
+      # @api private
+      # @param element [REXML::Element] Element with attributes
+      # @return [Hash] Hash of attribute name-value pairs
+      def collect_attributes(element)
+        element.attributes.each_with_object({}) { |(name, value), hash| hash[name] = value }
       end
 
-      # Adds a new key/value pair to an existing Hash. If the key to be added
-      # already exists and the existing value associated with key is not
-      # an Array, it will be wrapped in an Array. Then the new value is
-      # appended to that Array.
+      # Collect all child elements into a hash
       #
-      # hash::
-      #   Hash to add key/value pair to.
-      # key::
-      #   Key to be added.
-      # value::
-      #   Value to be associated with key.
-      def merge!(hash, key, value)
-        if hash.key?(key)
-          if hash[key].instance_of?(Array)
-            hash[key] << value
-          else
-            hash[key] = [hash[key], value]
-          end
-        elsif value.instance_of?(Array)
-          hash[key] = [value]
-        else
-          hash[key] = value
-        end
-        hash
+      # @api private
+      # @param element [REXML::Element] Parent element
+      # @param node_hash [Hash] Hash to populate
+      # @return [void]
+      def collect_child_elements(element, node_hash)
+        element.each_element { |child| element_to_hash(node_hash, child) }
+      end
+
+      # Add text content from an element to a hash
+      #
+      # @api private
+      # @param hash [Hash] Target hash
+      # @param element [REXML::Element] Element with text
+      # @return [Hash] Updated hash
+      def add_text_content(hash, element)
+        return hash unless element.has_text?
+
+        text = element.texts.map(&:value).join
+        add_to_hash(hash, TEXT_CONTENT_KEY, text)
       end
 
-      # Converts the attributes array of an XML element into a hash.
-      # Returns an empty Hash if node has no attributes.
+      # Add a value to a hash, handling duplicates as arrays
       #
-      # element::
-      #   XML element to extract attributes from.
-      def get_attributes(element)
-        attributes = {}
-        element.attributes.each { |n, v| attributes[n] = v }
-        attributes
+      # @api private
+      # @param hash [Hash] Target hash
+      # @param key [String] Key to add
+      # @param value [Object] Value to add
+      # @return [Hash] Updated hash
+      def add_to_hash(hash, key, value)
+        existing = hash[key]
+        hash[key] = if existing
+          existing.is_a?(Array) ? existing << value : [existing, value]
+        elsif value.is_a?(Array)
+          [value]
+        else
+          value
+        end
+        hash
       end
 
-      # Determines if a document element has text content
+      # Check if element contains only whitespace text
       #
-      # element::
-      #   XML element to be checked.
-      def empty_content?(element)
+      # @api private
+      # @param element [REXML::Element] Element to check
+      # @return [Boolean] true if whitespace only
+      def whitespace_only?(element)
         element.texts.join.strip.empty?
       end
     end

data/lib/multi_xml/parsers/sax_handler.rb

@@ -0,0 +1,117 @@
+require "cgi/escape"
+
+module MultiXml
+  module Parsers
+    # Shared SAX handler logic for building hash trees from XML events
+    #
+    # This module provides the core stack-based parsing logic used by both
+    # NokogiriSax and LibxmlSax parsers. Including classes must implement
+    # the callback methods that their respective SAX libraries expect.
+    #
+    # @api private
+    module SaxHandler
+      # Initialize the handler state
+      #
+      # @api private
+      # @return [void]
+      def initialize_handler
+        @result = {}
+        @stack = [@result]
+        @pending_attrs = []
+      end
+
+      # Get the parsed result
+      #
+      # @api private
+      # @return [Hash] the parsed hash
+      attr_reader :result
+
+      private
+
+      # Get the current element hash
+      #
+      # @api private
+      # @return [Hash] current hash being built
+      def current = @stack.last
+
+      # Handle start of an element by pushing onto the stack
+      #
+      # @api private
+      # @param name [String] Element name
+      # @param attrs [Hash, Array] Element attributes
+      # @return [void]
+      def handle_start_element(name, attrs)
+        child = {TEXT_CONTENT_KEY => +""}
+        add_child_to_current(name, child)
+        @stack << child
+        @pending_attrs << normalize_attrs(attrs)
+      end
+
+      # Handle end of an element by applying attributes and popping the stack
+      #
+      # @api private
+      # @return [void]
+      def handle_end_element
+        apply_attributes(@pending_attrs.pop)
+        strip_whitespace_content
+        @stack.pop
+      end
+
+      # Append text to the current element's content
+      #
+      # @api private
+      # @param text [String] Text to append
+      # @return [void]
+      def append_text(text)
+        current[TEXT_CONTENT_KEY] << text
+      end
+
+      # Add a child hash to the current element
+      #
+      # @api private
+      # @param name [String] Child element name
+      # @param child [Hash] Child hash to add
+      # @return [void]
+      def add_child_to_current(name, child)
+        existing = current[name]
+        current[name] = case existing
+        when Array then existing << child
+        when Hash then [existing, child]
+        else child
+        end
+      end
+
+      # Normalize attributes to a hash
+      #
+      # @api private
+      # @param attrs [Hash, Array] Attributes as hash or array of pairs
+      # @return [Hash] Normalized attributes hash
+      def normalize_attrs(attrs)
+        attrs.is_a?(Hash) ? attrs : attrs.to_h
+      end
+
+      # Apply pending attributes to the current element
+      #
+      # @api private
+      # @param attrs [Hash] Attributes to apply
+      # @return [void]
+      def apply_attributes(attrs)
+        attrs.each do |name, value|
+          unescaped = CGI.unescapeHTML(value)
+          existing = current[name]
+          current[name] = existing ? [unescaped, existing] : unescaped
+        end
+      end
+
+      # Remove empty or whitespace-only text content
+      #
+      # @api private
+      # @return [void]
+      def strip_whitespace_content
+        content = current[TEXT_CONTENT_KEY]
+        should_remove = content.empty? || (current.size > 1 && content.strip.empty?)
+        current.delete(TEXT_CONTENT_KEY) if should_remove
+      end
+    end
+  end
+end

data/lib/multi_xml/version.rb

@@ -1,3 +1,7 @@
 module MultiXml
-  VERSION = Gem::Version.create("0.7.2")
+  # The current version of MultiXml
+  #
+  # @api public
+  # @return [Gem::Version] the gem version
+  VERSION = Gem::Version.create("0.8.0")
 end