multi_xml 0.6.0 → 0.9.1

data/lib/multi_xml/parsers/ox.rb

@@ -1,91 +1,216 @@
-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.
-#
-
-module MultiXml
+require "ox"
+
+module MultiXML
   module Parsers
-    module Ox #:nodoc:
-      extend self
+    # XML parser using the Ox library (fastest pure-Ruby parser)
+    #
+    # @api private
+    module Ox
+      extend MultiXML::Parser
 
-      def parse_error
-        Exception
-      end
+      module_function
 
-      def parse(io)
-        handler = Handler.new
-        ::Ox.sax_parse(handler, io, :convert_special => true)
-        handler.doc
+      # Exception class raised on Ox parse failure
+      # @api private
+      ParseError = ::Ox::ParseError
+
+      # Parse XML from an IO object
+      #
+      # @api private
+      # @param io [IO] IO-like object containing XML
+      # @param namespaces [Symbol] Namespace handling mode
+      # @return [Hash] Parsed XML as a hash
+      def parse(io, namespaces: :strip)
+        handler = Handler.new(namespaces)
+        ::Ox.sax_parse(handler, io, convert_special: true, skip: :skip_return)
+        handler.result
       end
 
+      # SAX event handler that builds a hash tree while parsing.
+      #
+      # Ox's SAX callbacks expose element and attribute names in prefixed
+      # form (e.g. "atom:feed"). Under :preserve we keep the source form
+      # verbatim; under :strip we drop the prefix and filter xmlns
+      # declarations out of the attribute stream.
+      #
+      # @api private
       class Handler
-        attr_accessor :stack
-
-        def initialize
-          @stack = []
+        # Create a new SAX handler
+        #
+        # @api private
+        # @param mode [Symbol] Namespace handling mode
+        # @return [Handler] new handler instance
+        def initialize(mode)
+          @mode = mode
+          @stack = [{}]
         end
 
-        def doc
-          @stack[0]
+        # Get the parsed result
+        #
+        # @api private
+        # @return [Hash] the parsed hash
+        def result = @stack.first
+
+        # Handle start of an element
+        #
+        # @api private
+        # @param name [Symbol, String] Element name
+        # @return [void]
+        def start_element(name)
+          child = {}
+          add_value(current, format_name(name.to_s), child)
+          @stack << child
         end
 
+        # Handle an attribute
+        #
+        # Ignored outside an element (e.g. attributes on the XML declaration
+        # such as `<?xml version="1.0"?>`, which fire before any `start_element`).
+        #
+        # @api private
+        # @param name [Symbol, String] Attribute name
+        # @param value [String] Attribute value
+        # @return [void]
         def attr(name, value)
-          append(name, value) unless @stack.empty?
+          return if @stack.size < 2
+
+          name = name.to_s
+          return if xmlns_decl?(name) && @mode != :preserve
+
+          add_attribute_value(current, format_name(name), value)
         end
 
-        def text(value)
-          append(MultiXml::CONTENT_ROOT, value)
+        # Handle text content (also aliased as `cdata`)
+        #
+        # @api private
+        # @param value [String] Text content
+        # @return [void]
+        def text(value) = append_text(current, value)
+        alias_method :cdata, :text
+
+        # Handle end of an element
+        #
+        # @api private
+        # @param _name [Symbol, String] 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 parse errors
+        #
+        # @api private
+        # @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 start_element(name)
-          @stack.push({}) if @stack.empty?
-          h = {}
-          append(name, h)
-          @stack.push(h)
+        private
+
+        # Current element hash on top of the stack
+        #
+        # @api private
+        # @return [Hash] current hash being built
+        def current = @stack.last
+
+        # Format a prefixed-or-local name according to the namespace mode
+        #
+        # @api private
+        # @param name [String] Prefixed or local name
+        # @return [String] formatted name
+        def format_name(name)
+          (@mode == :preserve) ? name : name.split(":", 2).last
         end
 
-        def end_element(_)
-          @stack.pop
+        # Check whether an attribute name is an xmlns declaration
+        #
+        # @api private
+        # @param name [String] Attribute name
+        # @return [Boolean] true if xmlns or xmlns:*
+        def xmlns_decl?(name)
+          name == "xmlns" || name.start_with?("xmlns:")
         end
 
-        def error(message, line, column)
-          raise(Exception.new("#{message} at #{line}:#{column}"))
+        # Add a value to a hash, folding into an array on collision
+        #
+        # @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] = existing ? merge_values(existing, value) : value
+        end
+
+        # Append a text fragment to the current node's content
+        #
+        # SAX parsers may deliver element text in multiple callbacks when
+        # inline elements split the text stream. MultiXML represents that
+        # as one concatenated ``__content__`` string, not an array.
+        #
+        # @api private
+        # @param hash [Hash] Target hash
+        # @param value [String] Text fragment
+        # @return [void]
+        def append_text(hash, value)
+          existing = hash[TEXT_CONTENT_KEY]
+          hash[TEXT_CONTENT_KEY] = existing ? "#{existing}#{value}" : value
+        end
+
+        # Merge a value with an existing value, creating an array if needed
+        #
+        # @api private
+        # @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
+        # Add an attribute value while keeping document order on collisions
+        #
+        # @api private
+        # @param hash [Hash] Target hash
+        # @param key [String] Attribute key
+        # @param value [String] Attribute value
+        # @return [void]
+        def add_attribute_value(hash, key, value)
+          existing = hash[key]
+          hash[key] = case existing
+          when nil then value
+          when Array then insert_attribute_before_children(existing, value)
+          when Hash then [value, existing]
+          else [existing, value]
           end
         end
-      end # Handler
-    end # Ox
-  end # Parsers
-end # MultiXml
+
+        # Insert a later attribute before any child-element entries
+        #
+        # @api private
+        # @param values [Array] Existing colliding values
+        # @param value [String] Attribute value to insert
+        # @return [Array] Updated value list
+        def insert_attribute_before_children(values, value)
+          child_index = values.index { |entry| entry.is_a?(Hash) } || values.length
+          values.dup.insert(child_index, value)
+        end
+
+        # Remove empty or whitespace-only text content from the current hash
+        #
+        # @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
+end

data/lib/multi_xml/parsers/rexml.rb

@@ -1,111 +1,205 @@
-require 'rexml/document' unless defined?(REXML::Document)
+require "rexml/document"
 
-module MultiXml
+module MultiXML
   module Parsers
-    module Rexml #:nodoc:
+    # XML parser using Ruby's built-in REXML library
+    #
+    # @api private
+    module Rexml
+      extend MultiXML::Parser
       extend self
 
-      def parse_error
-        ::REXML::ParseException
+      # Exception class raised on REXML parse failure
+      # @api private
+      ParseError = ::REXML::ParseException
+
+      # Parse XML from an IO object
+      #
+      # @api private
+      # @param io [IO] IO-like object containing XML
+      # @param namespaces [Symbol] Namespace handling mode
+      # @return [Hash] Parsed XML as a hash
+      # @raise [REXML::ParseException] if XML is malformed
+      def parse(io, namespaces: :strip)
+        doc = REXML::Document.new(io)
+        element_to_hash({}, doc.root, namespaces)
       end
 
-      # Parse an XML Document IO into a simple hash using REXML
+      private
+
+      # Convert an element to hash format
       #
-      # xml::
-      #   XML Document IO to parse
-      def parse(xml)
-        doc = REXML::Document.new(xml)
-        raise(REXML::ParseException.new("The document #{doc.to_s.inspect} does not have a valid root")) unless doc.root
-        merge_element!({}, doc.root)
+      # @api private
+      # @param hash [Hash] Accumulator hash
+      # @param element [REXML::Element] Element to convert
+      # @param mode [Symbol] Namespace handling mode
+      # @return [Hash] Updated hash
+      def element_to_hash(hash, element, mode)
+        add_to_hash(hash, format_element_name(element, mode), collapse_element(element, mode))
       end
 
-    private
+      # Format element name using prefix/local and namespace mode
+      #
+      # @api private
+      # @param element [REXML::Element] Element node
+      # @param mode [Symbol] Namespace handling mode
+      # @return [String] formatted element name
+      def format_element_name(element, mode)
+        format_name(element.prefix, element.name, mode)
+      end
 
-      # Convert an XML element and merge into the hash
+      # Format attribute name using prefix/local and namespace mode
       #
-      # 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 attr [REXML::Attribute] Attribute node
+      # @param mode [Symbol] Namespace handling mode
+      # @return [String] formatted attribute name
+      def format_attr_name(attr, mode)
+        format_name(attr.prefix, attr.name, mode)
       end
 
-      # Actually converts an XML document element into a data structure.
+      # Produce a name string for a given [prefix, local] tuple
       #
-      # element::
-      #   The document element to be collapsed.
-      def collapse(element)
-        hash = get_attributes(element)
+      # @api private
+      # @param prefix [String, nil] Namespace prefix
+      # @param local [String] Local part of the name
+      # @param mode [Symbol] Namespace handling mode
+      # @return [String] formatted name
+      def format_name(prefix, local, mode)
+        (mode == :preserve && prefix && !prefix.empty?) ? "#{prefix}:#{local}" : local
+      end
+
+      # Collapse an element into a hash with attributes and content
+      #
+      # @api private
+      # @param element [REXML::Element] Element to collapse
+      # @param mode [Symbol] Namespace handling mode
+      # @return [Hash] Hash representation
+      def collapse_element(element, mode)
+        node_hash = collect_attributes(element, mode)
 
         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, mode)
+          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.each { |t| texts << t.value }
-          merge!(hash, MultiXml::CONTENT_ROOT, texts)
-        else
-          hash
+      # @api private
+      # @param element [REXML::Element] Element with attributes
+      # @param mode [Symbol] Namespace handling mode
+      # @return [Hash] Hash of attribute name-value pairs
+      def collect_attributes(element, mode)
+        element.attributes.each_attribute.with_object({}) do |attr, hash|
+          if xmlns_decl?(attr)
+            add_attribute_value(hash, xmlns_decl_key(attr), attr.value) if mode == :preserve
+          else
+            add_attribute_value(hash, format_attr_name(attr, mode), attr.value)
+          end
         end
       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.
+      # Check whether an attribute represents an xmlns declaration
       #
-      # 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]
+      # @api private
+      # @param attr [REXML::Attribute] Attribute to inspect
+      # @return [Boolean] true if xmlns declaration
+      def xmlns_decl?(attr)
+        attr.prefix == "xmlns" || ((attr.prefix.nil? || attr.prefix.empty?) && attr.name == "xmlns")
+      end
+
+      # Build the key for an xmlns declaration under :preserve
+      #
+      # @api private
+      # @param attr [REXML::Attribute] Declaration attribute
+      # @return [String] key such as "xmlns" or "xmlns:atom"
+      def xmlns_decl_key(attr)
+        (attr.prefix == "xmlns") ? "xmlns:#{attr.name}" : "xmlns"
+      end
+
+      # Collect all child elements into a hash
+      #
+      # @api private
+      # @param element [REXML::Element] Parent element
+      # @param node_hash [Hash] Hash to populate
+      # @param mode [Symbol] Namespace handling mode
+      # @return [void]
+      def collect_child_elements(element, node_hash, mode)
+        element.each_element { |child| element_to_hash(node_hash, child, mode) }
+      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
+
+      # Add a value to a hash, handling duplicates as arrays
+      #
+      # @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
-          hash[key] = value
+          value
+        end
+        hash
+      end
+
+      # Add an attribute value while keeping document order on collisions
+      #
+      # @api private
+      # @param hash [Hash] Target hash
+      # @param key [String] Attribute key
+      # @param value [String] Attribute value
+      # @return [Hash] Updated hash
+      def add_attribute_value(hash, key, value)
+        existing = hash[key]
+        hash[key] = case existing
+        when nil then value
+        when Array then insert_attribute_before_children(existing, value)
+        when Hash then [value, existing]
+        else [existing, value]
         end
         hash
       end
 
-      # Converts the attributes array of an XML element into a hash.
-      # Returns an empty Hash if node has no attributes.
+      # Insert a later attribute before any child-element entries
       #
-      # element::
-      #   XML element to extract attributes from.
-      def get_attributes(element)
-        attributes = {}
-        element.attributes.each { |n, v| attributes[n] = v }
-        attributes
+      # @api private
+      # @param values [Array] Existing colliding values
+      # @param value [String] Attribute value to insert
+      # @return [Array] Updated value list
+      def insert_attribute_before_children(values, value)
+        child_index = values.index { |entry| entry.is_a?(Hash) } || values.length
+        values.dup.insert(child_index, value)
       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