moxml 0.1.7 → 0.1.8

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

@@ -16,13 +16,51 @@ module Moxml
       config.adapter.parse(xml, default_options.merge(options))
     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
 
     def default_options
       {
         encoding: config.default_encoding,
         strict: config.strict_parsing,
-        indent: config.default_indent
+        indent: config.default_indent,
       }
     end
   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

@@ -40,18 +40,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
@@ -63,7 +64,8 @@ module Moxml
         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 +76,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 +98,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

data/lib/moxml/document_builder.rb

@@ -11,6 +11,17 @@ module Moxml
 
     def build(native_doc)
       @current_doc = context.create_document(native_doc)
+
+      # Transfer DOCTYPE from parsed document if it exists
+      if native_doc.respond_to?(:instance_variable_get) &&
+          native_doc.instance_variable_defined?(:@moxml_doctype)
+        doctype = native_doc.instance_variable_get(:@moxml_doctype)
+        if doctype
+          @current_doc.native.instance_variable_set(:@moxml_doctype,
+                                                    doctype)
+        end
+      end
+
       visit_node(native_doc)
       @current_doc
     end
@@ -33,6 +44,11 @@ module Moxml
     def visit_element(node)
       childless_node = adapter.duplicate_node(node)
       adapter.replace_children(childless_node, [])
+      # Prepare node for new document (LibXML needs this)
+      childless_node = adapter.prepare_for_new_document(
+        childless_node,
+        @current_doc.native,
+      )
       element = Element.new(childless_node, context)
       @node_stack.last.add_child(element)
 
@@ -42,23 +58,29 @@ module Moxml
     end
 
     def visit_text(node)
-      @node_stack.last&.add_child(Text.new(node, context))
+      # Prepare node for new document before wrapping
+      prepared = adapter.prepare_for_new_document(node, @current_doc.native)
+      @node_stack.last&.add_child(Text.new(prepared, context))
     end
 
     def visit_cdata(node)
-      @node_stack.last&.add_child(Cdata.new(node, context))
+      prepared = adapter.prepare_for_new_document(node, @current_doc.native)
+      @node_stack.last&.add_child(Cdata.new(prepared, context))
     end
 
     def visit_comment(node)
-      @node_stack.last&.add_child(Comment.new(node, context))
+      prepared = adapter.prepare_for_new_document(node, @current_doc.native)
+      @node_stack.last&.add_child(Comment.new(prepared, context))
     end
 
     def visit_processing_instruction(node)
-      @node_stack.last&.add_child(ProcessingInstruction.new(node, context))
+      prepared = adapter.prepare_for_new_document(node, @current_doc.native)
+      @node_stack.last&.add_child(ProcessingInstruction.new(prepared, context))
     end
 
     def visit_doctype(node)
-      @node_stack.last&.add_child(Doctype.new(node, context))
+      prepared = adapter.prepare_for_new_document(node, @current_doc.native)
+      @node_stack.last&.add_child(Doctype.new(prepared, context))
     end
 
     def visit_children(node)

data/lib/moxml/element.rb

@@ -13,6 +13,27 @@ module Moxml
       adapter.set_node_name(@native, value)
     end
 
+    # Returns the expanded name including namespace prefix
+    def expanded_name
+      if namespace_prefix && !namespace_prefix.empty?
+        "#{namespace_prefix}:#{name}"
+      else
+        name
+      end
+    end
+
+    # Returns the namespace prefix of this element
+    def namespace_prefix
+      ns = namespace
+      ns&.prefix
+    end
+
+    # Returns the namespace URI of this element
+    def namespace_uri
+      ns = namespace
+      ns&.uri
+    end
+
     def []=(name, value)
       adapter.set_attribute(@native, name, normalize_xml_value(value))
     end
@@ -26,6 +47,16 @@ module Moxml
       native_attr && Attribute.new(native_attr, context)
     end
 
+    # Alias for attribute access
+    def get(attr_name)
+      attribute(attr_name)
+    end
+
+    # Alias for getting attribute value (used by XPath engine)
+    def get(attr_name)
+      self[attr_name]
+    end
+
     def attributes
       adapter.attributes(@native).map do |attr|
         Attribute.new(attr, context)
@@ -42,7 +73,14 @@ module Moxml
       adapter.create_native_namespace(@native, prefix, uri)
       self
     rescue ValidationError => e
-      raise Moxml::NamespaceError, e.message
+      # Re-raise as NamespaceError, provide attributes for error context
+      # but the to_s will only add details if provided
+      raise Moxml::NamespaceError.new(
+        e.message,
+        prefix: prefix,
+        uri: uri,
+        element: self,
+      )
     end
     alias add_namespace_definition add_namespace
 
@@ -58,7 +96,7 @@ module Moxml
       if ns_or_hash.is_a?(Hash)
         adapter.set_namespace(
           @native,
-          adapter.create_namespace(@native, *ns_or_hash.to_a.first)
+          adapter.create_namespace(@native, *ns_or_hash.to_a.first),
         )
       else
         adapter.set_namespace(@native, ns_or_hash&.native)
@@ -72,6 +110,11 @@ module Moxml
     end
     alias namespace_definitions namespaces
 
+    # Returns the namespace URI of this element (alias for namespace_uri)
+    def namespace_name
+      namespace_uri
+    end
+
     def text
       adapter.text_content(@native)
     end
@@ -108,5 +151,31 @@ module Moxml
       self.text = content
       self
     end
+
+    # Bulk attribute setting
+    def set_attributes(attributes_hash)
+      attributes_hash.each { |name, value| self[name] = value }
+      self
+    end
+
+    # Chainable child addition
+    def with_child(child)
+      add_child(child)
+      self
+    end
+
+    # Convenience find methods
+    def find_element(xpath)
+      at_xpath(xpath)
+    end
+
+    def find_all(xpath)
+      xpath(xpath).to_a
+    end
+
+    # Alias for children (used by XPath engine)
+    def nodes
+      children
+    end
   end
 end

data/lib/moxml/error.rb

@@ -1,20 +1,189 @@
 # frozen_string_literal: true
 
 module Moxml
+  # Base error class for all Moxml errors
   class Error < StandardError; end
 
+  # Error raised when parsing XML fails
   class ParseError < Error
-    attr_reader :line, :column
+    attr_reader :line, :column, :source
 
-    def initialize(message, line: nil, column: nil)
+    def initialize(message, line: nil, column: nil, source: nil)
       @line = line
       @column = column
+      @source = source
       super(message)
     end
+
+    def to_s
+      msg = super
+      msg += "\n  Line: #{@line}" if @line
+      msg += "\n  Column: #{@column}" if @column
+      msg += "\n  Source: #{@source.inspect}" if @source
+      msg += "\n  Hint: Check XML syntax and ensure all tags are properly closed"
+      msg
+    end
+  end
+
+  # Error raised when XPath expression evaluation fails
+  class XPathError < Error
+    attr_reader :expression, :adapter, :node
+
+    def initialize(message, expression: nil, adapter: nil, node: nil)
+      @expression = expression
+      @adapter = adapter
+      @node = node
+      super(message)
+    end
+
+    def to_s
+      msg = super
+      msg += "\n  Expression: #{@expression}" if @expression
+      msg += "\n  Adapter: #{@adapter}" if @adapter
+      msg += "\n  Node: <#{@node.name}>" if @node.respond_to?(:name)
+      msg += "\n  Hint: Verify XPath syntax and ensure the adapter supports the expression"
+      msg
+    end
+  end
+
+  # Error raised when XML validation fails
+  class ValidationError < Error
+    attr_reader :node, :constraint, :value
+
+    def initialize(message, node: nil, constraint: nil, value: nil)
+      @node = node
+      @constraint = constraint
+      @value = value
+      super(message)
+    end
+
+    def to_s
+      msg = super
+      # Only add extra details if any were provided
+      has_details = @node.respond_to?(:name) || @constraint || @value
+      if has_details
+        msg += "\n  Node: <#{@node.name}>" if @node.respond_to?(:name)
+        msg += "\n  Constraint: #{@constraint}" if @constraint
+        msg += "\n  Value: #{@value.inspect}" if @value
+        msg += "\n  Hint: Ensure the value meets XML specification requirements"
+      end
+      msg
+    end
+  end
+
+  # Error raised when namespace operations fail
+  class NamespaceError < Error
+    attr_reader :prefix, :uri, :element
+
+    def initialize(message, prefix: nil, uri: nil, element: nil)
+      @prefix = prefix
+      @uri = uri
+      @element = element
+      super(message)
+    end
+  end
+
+  # Error raised when adapter operations fail
+  class AdapterError < Error
+    attr_reader :adapter_name, :operation, :native_error
+
+    def initialize(message, adapter: nil, operation: nil, native_error: nil)
+      @adapter_name = adapter
+      @operation = operation
+      @native_error = native_error
+      super(message)
+    end
+
+    def to_s
+      msg = super
+      msg += "\n  Adapter: #{@adapter_name}" if @adapter_name
+      msg += "\n  Operation: #{@operation}" if @operation
+      if @native_error
+        msg += "\n  Native Error: #{@native_error.class.name}: #{@native_error.message}"
+      end
+      msg += "\n  Hint: Ensure the adapter gem is properly installed and compatible"
+      msg
+    end
   end
 
-  class ValidationError < Error; end
-  class XPathError < Error; end
-  class NamespaceError < Error; end
-  class AdapterError < Error; end
+  # Error raised when serialization fails
+  class SerializationError < Error
+    attr_reader :node, :adapter, :format
+
+    def initialize(message, node: nil, adapter: nil, format: nil)
+      @node = node
+      @adapter = adapter
+      @format = format
+      super(message)
+    end
+
+    def to_s
+      msg = super
+      msg += "\n  Node: <#{@node.name}>" if @node.respond_to?(:name)
+      msg += "\n  Adapter: #{@adapter}" if @adapter
+      msg += "\n  Format: #{@format}" if @format
+      msg += "\n  Hint: Check that the node structure is valid for serialization"
+      msg
+    end
+  end
+
+  # Error raised when document structure is invalid
+  class DocumentStructureError < Error
+    attr_reader :attempted_operation, :current_state
+
+    def initialize(message, operation: nil, state: nil)
+      @attempted_operation = operation
+      @current_state = state
+      super(message)
+    end
+
+    def to_s
+      msg = super
+      msg += "\n  Operation: #{@attempted_operation}" if @attempted_operation
+      msg += "\n  Current State: #{@current_state}" if @current_state
+      msg += "\n  Hint: Ensure the document structure follows XML specifications"
+      msg
+    end
+  end
+
+  # Error raised when attribute operations fail
+  class AttributeError < Error
+    attr_reader :attribute_name, :element, :value
+
+    def initialize(message, name: nil, element: nil, value: nil)
+      @attribute_name = name
+      @element = element
+      @value = value
+      super(message)
+    end
+
+    def to_s
+      msg = super
+      msg += "\n  Attribute: #{@attribute_name}" if @attribute_name
+      msg += "\n  Element: <#{@element.name}>" if @element.respond_to?(:name)
+      msg += "\n  Value: #{@value.inspect}" if @value
+      msg += "\n  Hint: Verify attribute name follows XML naming rules"
+      msg
+    end
+  end
+
+  # Error raised when a feature is not implemented by an adapter
+  class NotImplementedError < Error
+    attr_reader :feature, :adapter
+
+    def initialize(message = nil, feature: nil, adapter: nil)
+      @feature = feature
+      @adapter = adapter
+      message ||= "Feature not implemented"
+      super(message)
+    end
+
+    def to_s
+      msg = super
+      msg += "\n  Feature: #{@feature}" if @feature
+      msg += "\n  Adapter: #{@adapter}" if @adapter
+      msg += "\n  Hint: This feature may not be supported by the current adapter"
+      msg
+    end
+  end
 end