moxml 0.1.7 → 0.1.9

data/lib/moxml/adapter/rexml.rb

@@ -14,13 +14,42 @@ module Moxml
           native_doc = begin
             ::REXML::Document.new(xml)
           rescue ::REXML::ParseException => e
-            raise Moxml::ParseError.new(e.message, line: e.line) if options[:strict]
-
+            if options[:strict]
+              raise Moxml::ParseError.new(
+                e.message,
+                line: e.line,
+                source: xml.is_a?(String) ? xml[0..100] : nil,
+              )
+            end
             create_document
           end
+
           DocumentBuilder.new(Context.new(:rexml)).build(native_doc)
         end
 
+        # SAX parsing implementation for REXML
+        #
+        # @param xml [String, IO] XML to parse
+        # @param handler [Moxml::SAX::Handler] Moxml SAX handler
+        # @return [void]
+        def sax_parse(xml, handler)
+          require "rexml/parsers/sax2parser"
+          require "rexml/source"
+          require "stringio"
+
+          bridge = REXMLSAX2Bridge.new(handler)
+
+          xml_string = xml.respond_to?(:read) ? xml.read : xml.to_s
+          source = ::REXML::IOSource.new(StringIO.new(xml_string))
+
+          parser = ::REXML::Parsers::SAX2Parser.new(source)
+          parser.listen(bridge)
+          parser.parse
+        rescue ::REXML::ParseException => e
+          error = Moxml::ParseError.new(e.message, line: e.line)
+          handler.on_error(error)
+        end
+
         def create_document(_native_doc = nil)
           ::REXML::Document.new
         end
@@ -55,10 +84,10 @@ module Moxml
 
           parts = [name]
           if external_id
-            parts.concat(["PUBLIC", %("#{external_id}")])
+            parts.push("PUBLIC", %("#{external_id}"))
             parts << %("#{system_id}") if system_id
           elsif system_id
-            parts.concat(["SYSTEM", %("#{system_id}")])
+            parts.push("SYSTEM", %("#{system_id}"))
           end
 
           ::REXML::DocType.new(parts.join(" "))
@@ -189,7 +218,7 @@ module Moxml
 
           # Only return non-namespace attributes
           element.attributes.values
-                 .reject { |attr| attr.prefix.to_s.start_with?("xmlns") }
+            .reject { |attr| attr.prefix.to_s.start_with?("xmlns") }
         end
 
         def attribute_element(attribute)
@@ -197,8 +226,8 @@ module Moxml
         end
 
         def set_attribute(element, name, value)
-          element.attributes[name&.to_s] = value
-          ::REXML::Attribute.new(name&.to_s, value.to_s, element)
+          element.attributes[name&.to_s] = value&.to_s
+          element.attributes.get_attribute(name&.to_s)
         end
 
         def set_attribute_name(attribute, name)
@@ -227,6 +256,12 @@ module Moxml
         end
 
         def add_child(element, child)
+          # Special handling for declarations on REXML documents
+          if element.is_a?(::REXML::Document) && child.is_a?(::REXML::XMLDecl)
+            # Set document's xml_decl directly
+            element.instance_variable_set(:@xml_declaration, child)
+          end
+
           case child
           when String
             element.add_text(child)
@@ -251,6 +286,12 @@ module Moxml
         end
 
         def remove(node)
+          # Special handling for declarations on REXML documents
+          if node.is_a?(::REXML::XMLDecl) && node.parent.is_a?(::REXML::Document)
+            # Clear document's xml_declaration when removing declaration
+            node.parent.instance_variable_set(:@xml_declaration, nil)
+          end
+
           node.remove
         end
 
@@ -327,8 +368,8 @@ module Moxml
         def inner_text(node)
           # Get direct text children only, filter duplicates
           text_children = node.children
-                              .select { _1.is_a?(::REXML::Text) }
-                              .uniq(&:object_id)
+            .select { _1.is_a?(::REXML::Text) }
+            .uniq(&:object_id)
           text_children.map(&:value).join
         end
 
@@ -353,7 +394,10 @@ module Moxml
         # add a namespace prefix to the element name AND a namespace definition
         def set_namespace(element, ns)
           prefix = ns.name.to_s.empty? ? "xmlns" : ns.name.to_s
-          element.add_namespace(prefix, ns.value) if element.respond_to?(:add_namespace)
+          if element.respond_to?(:add_namespace)
+            element.add_namespace(prefix,
+                                  ns.value)
+          end
           element.name = "#{prefix}:#{element.name}"
           owner = element.is_a?(::REXML::Attribute) ? element.element : element
           ::REXML::Attribute.new(prefix, ns.value, owner)
@@ -405,7 +449,12 @@ module Moxml
         def xpath(node, expression, _namespaces = {})
           node.get_elements(expression).to_a
         rescue ::REXML::ParseException => e
-          raise Moxml::XPathError, e.message
+          raise Moxml::XPathError.new(
+            e.message,
+            expression: expression,
+            adapter: "REXML",
+            node: node,
+          )
         end
 
         def at_xpath(node, expression, namespaces = {})
@@ -414,33 +463,45 @@ module Moxml
         end
 
         def serialize(node, options = {})
-          output = String.new
+          output = +""
 
           if node.is_a?(::REXML::Document)
-            # Always include XML declaration
-            decl = node.xml_decl || ::REXML::XMLDecl.new("1.0", options[:encoding] || "UTF-8")
-            decl.encoding = options[:encoding] if options[:encoding]
-            output << "<?xml"
-            output << %( version="#{decl.version}") if decl.version
-            output << %( encoding="#{decl.encoding}") if decl.encoding
-            output << %( standalone="#{decl.standalone}") if decl.standalone
-            output << "?>"
-            # output << "\n"
-
-            if node.doctype
-              node.doctype.write(output)
-              # output << "\n"
+            # Check if we should include declaration
+            # Priority: explicit option > check if document has xml_decl
+            should_include_decl = if options.key?(:no_declaration)
+                                    !options[:no_declaration]
+                                  else
+                                    # Include declaration only if document has xml_decl
+                                    !node.xml_decl.nil?
+                                  end
+
+            # Include XML declaration only if should_include_decl and xml_decl exists
+            if should_include_decl && node.xml_decl
+              decl = node.xml_decl
+              decl.encoding = options[:encoding] if options[:encoding]
+              output << "<?xml"
+              output << %( version="#{decl.version}") if decl.version
+              output << %( encoding="#{decl.encoding}") if decl.encoding
+              output << %( standalone="#{decl.standalone}") if decl.standalone
+              output << "?>"
             end
 
+            # output << "\n"
+            node.doctype&.write(output)
+
             # Write processing instructions
             node.children.each do |child|
-              next unless [::REXML::Instruction, ::REXML::CData, ::REXML::Comment, ::REXML::Text].include?(child.class)
+              next unless [::REXML::Instruction, ::REXML::CData,
+                           ::REXML::Comment, ::REXML::Text].include?(child.class)
 
               write_with_formatter(child, output, options[:indent] || 2)
               # output << "\n"
             end
 
-            write_with_formatter(node.root, output, options[:indent] || 2) if node.root
+            if node.root
+              write_with_formatter(node.root, output,
+                                   options[:indent] || 2)
+            end
           else
             write_with_formatter(node, output, options[:indent] || 2)
           end
@@ -452,11 +513,79 @@ module Moxml
 
         def write_with_formatter(node, output, indent = 2)
           formatter = ::Moxml::Adapter::CustomizedRexml::Formatter.new(
-            indentation: indent, self_close_empty: false
+            indentation: indent, self_close_empty: false,
           )
           formatter.write(node, output)
         end
       end
     end
+
+    # Bridge between REXML SAX2 and Moxml SAX
+    #
+    # Translates REXML::SAX2Parser events to Moxml::SAX::Handler events
+    #
+    # @private
+    class REXMLSAX2Bridge
+      def initialize(handler)
+        @handler = handler
+      end
+
+      # REXML splits element name into uri/localname/qname
+      def start_element(_uri, _localname, qname, attributes)
+        # Convert REXML attributes to hash
+        attr_hash = {}
+        ns_hash = {}
+
+        attributes.each do |name, value|
+          if name.to_s.start_with?("xmlns")
+            # Namespace declaration
+            prefix = name.to_s == "xmlns" ? nil : name.to_s.sub("xmlns:", "")
+            ns_hash[prefix] = value
+          else
+            attr_hash[name.to_s] = value
+          end
+        end
+
+        # Use qname (qualified name) for element name
+        @handler.on_start_element(qname, attr_hash, ns_hash)
+      end
+
+      def end_element(_uri, _localname, qname)
+        @handler.on_end_element(qname)
+      end
+
+      def characters(text)
+        @handler.on_characters(text)
+      end
+
+      def cdata(content)
+        @handler.on_cdata(content)
+      end
+
+      def comment(text)
+        @handler.on_comment(text)
+      end
+
+      def processing_instruction(target, data)
+        @handler.on_processing_instruction(target, data || "")
+      end
+
+      def start_document
+        @handler.on_start_document
+      end
+
+      def end_document
+        @handler.on_end_document
+      end
+
+      # REXML calls these but we don't need to handle them
+      def xmldecl(version, encoding, standalone)
+        # XML declaration - we don't need to do anything
+      end
+
+      def progress(position)
+        # Progress callback - we don't need to do anything
+      end
+    end
   end
 end

data/lib/moxml/adapter.rb

@@ -4,14 +4,26 @@ require_relative "adapter/base"
 
 module Moxml
   module Adapter
-    AVALIABLE_ADAPTERS = %i[nokogiri oga rexml ox].freeze
+    AVALIABLE_ADAPTERS = %i[nokogiri oga rexml ox headed_ox libxml].freeze
 
     class << self
       def load(name)
         require_adapter(name)
-        const_get(name.to_s.capitalize)
+        # Handle special case for headed_ox -> HeadedOx
+        const_name = case name
+                     when :headed_ox
+                       "HeadedOx"
+                     else
+                       name.to_s.capitalize
+                     end
+        const_get(const_name)
       rescue LoadError => e
-        raise LoadError, "Could not load #{name} adapter. Please ensure the #{name} gem is available: #{e.message}"
+        raise Moxml::AdapterError.new(
+          "Could not load #{name} adapter. Please ensure the #{name} gem is installed",
+          adapter: name,
+          operation: "load",
+          native_error: e,
+        )
       end
 
       private
@@ -23,7 +35,12 @@ module Moxml
           require name.to_s
           require "#{__dir__}/adapter/#{name}"
         rescue LoadError => e
-          raise LoadError, "Failed to load #{name} adapter: #{e.message}"
+          raise Moxml::AdapterError.new(
+            "Failed to load #{name} adapter",
+            adapter: name,
+            operation: "require",
+            native_error: e,
+          )
         end
       end
     end

data/lib/moxml/attribute.rb

@@ -18,6 +18,12 @@ module Moxml
       adapter.set_attribute_value(@native, new_value)
     end
 
+    # XPath conversion compatibility - attributes need .text method
+    # that returns their value for XPath comparisons
+    def text
+      value
+    end
+
     def namespace
       ns = adapter.namespace(@native)
       ns && Namespace.new(ns, context)

data/lib/moxml/builder.rb

@@ -15,7 +15,7 @@ module Moxml
 
     def declaration(version: "1.0", encoding: "UTF-8", standalone: nil)
       @current.add_child(
-        @document.create_declaration(version, encoding, standalone)
+        @document.create_declaration(version, encoding, standalone),
       )
     end
 
@@ -23,12 +23,22 @@ module Moxml
       el = @document.create_element(name)
 
       attributes.each do |key, value|
-        el[key] = value
+        if key.to_s == "xmlns"
+          # Handle default namespace
+          el.add_namespace(nil, value.to_s)
+        elsif key.to_s.start_with?("xmlns:")
+          # Handle prefixed namespace
+          prefix = key.to_s.sub("xmlns:", "")
+          el.add_namespace(prefix, value.to_s)
+        else
+          # Regular attribute
+          el[key] = value
+        end
       end
 
       @current.add_child(el)
 
-      if block_given?
+      if block
         previous = @current
         @current = el
         instance_eval(&block)
@@ -52,7 +62,7 @@ module Moxml
 
     def processing_instruction(target, content)
       @current.add_child(
-        @document.create_processing_instruction(target, content)
+        @document.create_processing_instruction(target, content),
       )
     end
 
@@ -60,5 +70,31 @@ module Moxml
       @current.add_namespace(prefix, uri)
       @namespaces[prefix] = uri
     end
+
+    # Convenience method for DOCTYPE
+    def doctype(name, external_id = nil, system_id = nil)
+      @current.add_child(
+        @document.create_doctype(name, external_id, system_id),
+      )
+    end
+
+    # Batch element creation
+    def elements(element_specs)
+      element_specs.each do |name, content_or_attrs|
+        if content_or_attrs.is_a?(Hash)
+          element(name, content_or_attrs)
+        else
+          element(name) { text(content_or_attrs) }
+        end
+      end
+    end
+
+    # Helper for creating namespaced elements
+    def ns_element(namespace_uri, name, attributes = {}, &block)
+      el = element(name, attributes, &block)
+      prefix = @namespaces.key(namespace_uri)
+      el.namespace = { prefix => namespace_uri } if prefix
+      el
+    end
   end
 end

data/lib/moxml/config.rb

@@ -2,7 +2,7 @@
 
 module Moxml
   class Config
-    VALID_ADAPTERS = %i[nokogiri oga rexml ox].freeze
+    VALID_ADAPTERS = %i[nokogiri oga rexml ox headed_ox libxml].freeze
     DEFAULT_ADAPTER = VALID_ADAPTERS.first
 
     class << self
@@ -23,7 +23,8 @@ module Moxml
                   :entity_encoding,
                   :default_indent
 
-    def initialize(adapter_name = nil, strict_parsing = nil, default_encoding = nil)
+    def initialize(adapter_name = nil, strict_parsing = nil,
+                   default_encoding = nil)
       self.adapter = adapter_name || Config.default.adapter_name
       @strict_parsing = strict_parsing || Config.default.strict_parsing
       @default_encoding = default_encoding || Config.default.default_encoding
@@ -37,7 +38,11 @@ module Moxml
       @adapter = nil
 
       unless VALID_ADAPTERS.include?(name)
-        raise ArgumentError, "Invalid adapter: #{name}. Valid adapters are: #{VALID_ADAPTERS.join(", ")}"
+        raise Moxml::AdapterError.new(
+          "Invalid adapter: #{name}",
+          adapter: name,
+          operation: "set_adapter",
+        )
       end
 
       @adapter_name = name

data/lib/moxml/context.rb

@@ -13,7 +13,62 @@ module Moxml
     end
 
     def parse(xml, options = {})
-      config.adapter.parse(xml, default_options.merge(options))
+      # Detect if input has XML declaration
+      xml_string = if xml.respond_to?(:read)
+                     xml.read.tap do
+                       xml.rewind if xml.respond_to?(:rewind)
+                     end
+                   else
+                     xml.to_s
+                   end
+      has_declaration = xml_string.strip.start_with?("<?xml")
+
+      # Parse with adapter (without declaration info - adapters don't need it)
+      parsed_options = default_options.merge(options)
+      doc = config.adapter.parse(xml_string, parsed_options)
+
+      # Set declaration flag on Document wrapper (proper OOP)
+      doc.has_xml_declaration = has_declaration if doc.is_a?(Document)
+
+      doc
+    end
+
+    # Parse XML using SAX (event-driven) parsing
+    #
+    # SAX parsing is memory-efficient and suitable for large XML files.
+    # Provide either a handler object or a block with DSL.
+    #
+    # @param xml [String, IO] XML string or IO object to parse
+    # @param handler [Moxml::SAX::Handler, nil] Handler object (optional if block given)
+    # @yield [block] DSL block for defining handlers (optional if handler given)
+    # @return [void]
+    # @raise [ArgumentError] if neither handler nor block is provided
+    #
+    # @example With handler object
+    #   handler = MyHandler.new
+    #   context.sax_parse(xml_string, handler)
+    #
+    # @example With block
+    #   context.sax_parse(xml_string) do
+    #     start_element { |name, attrs| puts name }
+    #     characters { |text| puts text }
+    #   end
+    #
+    def sax_parse(xml, handler = nil, &block)
+      # Load SAX module if not already loaded
+      require_relative "sax" unless defined?(Moxml::SAX)
+
+      # Create block handler if block given
+      handler ||= SAX::BlockHandler.new(&block) if block
+
+      # Validate handler
+      raise ArgumentError, "Handler or block required" unless handler
+      unless handler.is_a?(SAX::Handler)
+        raise ArgumentError, "Handler must inherit from Moxml::SAX::Handler"
+      end
+
+      # Delegate to adapter
+      config.adapter.sax_parse(xml, handler)
     end
 
     private
@@ -22,7 +77,7 @@ module Moxml
       {
         encoding: config.default_encoding,
         strict: config.strict_parsing,
-        indent: config.default_indent
+        indent: config.default_indent,
       }
     end
   end

data/lib/moxml/declaration.rb

@@ -33,6 +33,15 @@ module Moxml
       adapter.set_declaration_attribute(@native, "standalone", new_standalone)
     end
 
+    def remove
+      # Mark document as having no declaration when declaration is removed
+      # Store on native document so all wrappers see it
+      native_doc = adapter.document(@native)
+      native_doc&.instance_variable_set(:@moxml_has_declaration, false)
+
+      super
+    end
+
     def declaration?
       true
     end

data/lib/moxml/doctype.rb

@@ -1,5 +1,17 @@
 # frozen_string_literal: true
 
 module Moxml
-  class Doctype < Node; end
+  class Doctype < Node
+    def name
+      adapter.doctype_name(@native)
+    end
+
+    def external_id
+      adapter.doctype_external_id(@native)
+    end
+
+    def system_id
+      adapter.doctype_system_id(@native)
+    end
+  end
 end

data/lib/moxml/document.rb

@@ -12,6 +12,17 @@ require_relative "doctype"
 
 module Moxml
   class Document < Node
+    attr_accessor :has_xml_declaration
+
+    def initialize(native, context)
+      super
+      @has_xml_declaration = false
+    end
+
+    def document
+      self
+    end
+
     def root=(element)
       adapter.set_root(@native, element.native)
     end
@@ -40,18 +51,19 @@ module Moxml
     def create_doctype(name, external_id, system_id)
       Doctype.new(
         adapter.create_doctype(name, external_id, system_id),
-        context
+        context,
       )
     end
 
     def create_processing_instruction(target, content)
       ProcessingInstruction.new(
         adapter.create_processing_instruction(target, content),
-        context
+        context,
       )
     end
 
-    def create_declaration(version = "1.0", encoding = "UTF-8", standalone = nil)
+    def create_declaration(version = "1.0", encoding = "UTF-8",
+                           standalone = nil)
       decl = adapter.create_declaration(version, encoding, standalone)
       Declaration.new(decl, context)
     end
@@ -60,10 +72,14 @@ module Moxml
       node = prepare_node(node)
 
       if node.is_a?(Declaration)
+        # Mark that document now has a declaration
+        @has_xml_declaration = true
+
         if children.empty?
           adapter.add_child(@native, node.native)
         else
-          adapter.add_previous_sibling(adapter.children(@native).first, node.native)
+          adapter.add_previous_sibling(adapter.children(@native).first,
+                                       node.native)
         end
       elsif root && !node.is_a?(ProcessingInstruction) && !node.is_a?(Comment)
         raise Error, "Document already has a root element"
@@ -74,8 +90,21 @@ module Moxml
     end
 
     def xpath(expression, namespaces = nil)
-      native_nodes = adapter.xpath(@native, expression, namespaces)
-      NodeSet.new(native_nodes, context)
+      result = adapter.xpath(@native, expression, namespaces)
+
+      # Handle different result types:
+      # - Scalar values (from functions): return directly
+      # - NodeSet: already wrapped, return directly
+      # - Array: wrap in NodeSet
+      case result
+      when NodeSet, Float, String, TrueClass, FalseClass, NilClass
+        result
+      when Array
+        NodeSet.new(result, context)
+      else
+        # For other types, try to wrap in NodeSet
+        NodeSet.new(result, context)
+      end
     end
 
     def at_xpath(expression, namespaces = nil)
@@ -83,5 +112,23 @@ module Moxml
         Node.wrap(native_node, context)
       end
     end
+
+    # Quick element creation and addition
+    def add_element(name, attributes = {}, &block)
+      elem = create_element(name)
+      attributes.each { |k, v| elem[k] = v }
+      add_child(elem)
+      block&.call(elem)
+      elem
+    end
+
+    # Convenience find methods
+    def find(xpath)
+      at_xpath(xpath)
+    end
+
+    def find_all(xpath)
+      xpath(xpath).to_a
+    end
   end
 end