moxml 0.1.7 → 0.1.9

data/lib/moxml/document_builder.rb

@@ -11,6 +11,24 @@ module Moxml
 
     def build(native_doc)
       @current_doc = context.create_document(native_doc)
+
+      # Transfer has_declaration flag if present
+      if native_doc.respond_to?(:instance_variable_get) &&
+          native_doc.instance_variable_defined?(:@moxml_has_declaration)
+        has_declaration = native_doc.instance_variable_get(:@moxml_has_declaration)
+        @current_doc.has_xml_declaration = has_declaration
+      end
+
+      # 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 +51,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 +65,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

data/lib/moxml/node.rb

@@ -31,7 +31,7 @@ module Moxml
     def children
       NodeSet.new(
         adapter.children(@native).map { adapter.patch_node(_1, @native) },
-        context
+        context,
       )
     end
 
@@ -73,7 +73,13 @@ module Moxml
     end
 
     def to_xml(options = {})
-      adapter.serialize(@native, default_options.merge(options))
+      # Determine if we should include XML declaration
+      # For Document nodes: check native then wrapper, unless explicitly overridden
+      # For other nodes: default to no declaration unless explicitly set
+      serialize_options = default_options.merge(options)
+      serialize_options[:no_declaration] = !should_include_declaration?(options)
+
+      adapter.serialize(@native, serialize_options)
     end
 
     def xpath(expression, namespaces = {})
@@ -84,6 +90,92 @@ module Moxml
       Node.wrap(adapter.at_xpath(@native, expression, namespaces), context)
     end
 
+    # Convenience find methods (aliases for xpath methods)
+    def find(xpath_expression, namespaces = {})
+      at_xpath(xpath_expression, namespaces)
+    end
+
+    def find_all(xpath_expression, namespaces = {})
+      xpath(xpath_expression, namespaces).to_a
+    end
+
+    # Check if node has any children
+    def has_children?
+      !children.empty?
+    end
+
+    # Get first/last child
+    def first_child
+      children.first
+    end
+
+    def last_child
+      children.last
+    end
+
+    # Returns the text content of this node
+    # For elements, returns concatenated text of all text children
+    # For text nodes, returns the content if available
+    def text
+      if respond_to?(:content)
+        content
+      elsif respond_to?(:children)
+        children.select { |c| c.is_a?(Text) }.map(&:content).join
+      else
+        ""
+      end
+    end
+
+    # Returns the text content of this node
+    # Subclasses should override this method
+    # Element and Text have their own implementations
+    def text
+      ""
+    end
+
+    # Attribute accessor - only works on Element nodes
+    # Returns nil for non-element nodes
+    def [](name)
+      return nil unless respond_to?(:attribute)
+
+      attr = attribute(name)
+      attr&.value if attr.respond_to?(:value)
+    end
+
+    # Returns the namespace of this node
+    # Only applicable to Element nodes, returns nil for others
+    def namespace
+      return nil unless element?
+
+      ns = adapter.namespace(@native)
+      ns && Namespace.new(ns, context)
+    end
+
+    # Returns all namespace definitions on this node
+    # Only applicable to Element nodes, returns empty array for others
+    def namespaces
+      return [] unless element?
+
+      adapter.namespace_definitions(@native).map do |ns|
+        Namespace.new(ns, context)
+      end
+    end
+
+    # Recursively yield all descendant nodes
+    # Used by XPath descendant-or-self and descendant axes
+    def each_node(&block)
+      children.each do |child|
+        yield child
+        child.each_node(&block) if child.respond_to?(:each_node)
+      end
+    end
+
+    # Clone the node (deep copy)
+    def clone
+      Node.wrap(adapter.dup(@native), context)
+    end
+    alias dup clone
+
     def ==(other)
       self.class == other.class && @native == other.native
     end
@@ -106,6 +198,7 @@ module Moxml
               when :document then Document
               when :declaration then Declaration
               when :doctype then Doctype
+              when :attribute then Attribute
               else self
               end
 
@@ -129,7 +222,11 @@ module Moxml
       when String then Text.new(adapter.create_text(node), context)
       when Node then node
       else
-        raise ArgumentError, "Invalid node type: #{node.class}"
+        raise Moxml::DocumentStructureError.new(
+          "Invalid node type: #{node.class}. Expected String or Moxml::Node",
+          operation: "prepare_node",
+          state: "node_type: #{node.class}",
+        )
       end
     end
 
@@ -141,8 +238,62 @@ module Moxml
         # Oga: <empty /> (with a space)
         # Nokogiri: <empty/> (without a space)
         # The expanded format is enforced to avoid this conflict
-        expand_empty: true
+        expand_empty: true,
       }
     end
+
+    def should_include_declaration?(options)
+      return options[:declaration] if options.key?(:declaration)
+      return options.fetch(:declaration, false) unless is_a?(Document)
+
+      # For Document nodes, check both wrapper flag and native state
+      # Wrapper flag is set by Context.parse for parsed documents
+      # Native state reflects programmatic changes (e.g., add/remove)
+
+      adapter_name = adapter.to_s.split("::").last
+
+      case adapter_name
+      when "Nokogiri"
+        # Nokogiri: if @xml_decl is explicitly set, use that state
+        # Otherwise, trust wrapper flag (for parsed documents)
+        if native.respond_to?(:instance_variable_defined?) &&
+            native.instance_variable_defined?(:@xml_decl)
+          # Explicitly set (programmatically added) - check if nil
+          !native.instance_variable_get(:@xml_decl).nil?
+        else
+          # Not set (parsed document) - trust wrapper flag
+          has_xml_declaration
+        end
+      when "Rexml"
+        # REXML: check @xml_declaration instance variable
+        # If not defined (parsed doc), trust wrapper flag
+        if native.respond_to?(:instance_variable_defined?) &&
+            native.instance_variable_defined?(:@xml_declaration)
+          # Explicitly set - check if nil
+          !native.instance_variable_get(:@xml_declaration).nil?
+        else
+          # Not set (parsed document) - trust wrapper flag
+          has_xml_declaration
+        end
+      when "Oga"
+        native.respond_to?(:xml_declaration) && !native.xml_declaration.nil?
+      when "Ox", "HeadedOx"
+        # Ox stores declaration in document attributes
+        native[:version] || native[:encoding] || native[:standalone]
+      when "Libxml"
+        # LibXML stores declaration wrapper as instance variable
+        if native.respond_to?(:instance_variable_defined?) &&
+            native.instance_variable_defined?(:@moxml_declaration)
+          # Explicitly set - check if nil
+          !native.instance_variable_get(:@moxml_declaration).nil?
+        else
+          # Not set - trust wrapper flag
+          has_xml_declaration
+        end
+      else
+        # Fallback - trust wrapper flag
+        has_xml_declaration
+      end
+    end
   end
 end

data/lib/moxml/node_set.rb

@@ -52,6 +52,31 @@ module Moxml
       self.class.new(nodes + other.nodes, context)
     end
 
+    def <<(node)
+      # If it's a wrapped Moxml node, unwrap to native before storing
+      native_node = node.respond_to?(:native) ? node.native : node
+      @nodes << native_node
+      self
+    end
+    alias push <<
+
+    # Deduplicate nodes based on native object identity
+    # This is crucial for XPath operations like descendant-or-self
+    # which may yield the same native node multiple times
+    def uniq_by_native
+      seen = {}
+      unique_natives = @nodes.select do |native|
+        id = native.object_id
+        if seen[id]
+          false
+        else
+          seen[id] = true
+          true
+        end
+      end
+      self.class.new(unique_natives, context)
+    end
+
     def ==(other)
       self.class == other.class &&
         length == other.length &&
@@ -68,5 +93,14 @@ module Moxml
       each(&:remove)
       self
     end
+
+    # Delete a node from the set
+    # Accepts both wrapped Moxml nodes and native nodes
+    def delete(node)
+      # If it's a wrapped Moxml node, unwrap to native
+      native_node = node.respond_to?(:native) ? node.native : node
+      @nodes.delete(native_node)
+      self
+    end
   end
 end