moxml 0.1.7 → 0.1.8

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
 
@@ -84,6 +84,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 +192,7 @@ module Moxml
               when :document then Document
               when :declaration then Declaration
               when :doctype then Doctype
+              when :attribute then Attribute
               else self
               end
 
@@ -129,7 +216,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,7 +232,7 @@ 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
   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

data/lib/moxml/sax/block_handler.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+require_relative "handler"
+
+module Moxml
+  module SAX
+    # Block-based SAX handler with DSL
+    #
+    # Provides a convenient block-based API for simple SAX parsing cases
+    # without requiring a full class definition.
+    #
+    # @example Block-based parsing
+    #   context.sax_parse(xml) do
+    #     start_element { |name, attrs| puts "Element: #{name}" }
+    #     characters { |text| puts "Text: #{text}" }
+    #     end_element { |name| puts "End: #{name}" }
+    #   end
+    #
+    # @example With instance variables
+    #   books = []
+    #   context.sax_parse(xml) do
+    #     start_element do |name, attrs|
+    #       books << { id: attrs["id"] } if name == "book"
+    #     end
+    #   end
+    #
+    class BlockHandler < Handler
+      # Create a new block handler
+      #
+      # @param block [Proc] Block containing DSL calls
+      # @yield DSL context for defining handlers
+      def initialize(&block)
+        super()
+        @handlers = {}
+        instance_eval(&block) if block
+      end
+
+      # Define handler for document start event
+      #
+      # @yield Block to execute when document parsing begins
+      # @yieldreturn [void]
+      # @return [void]
+      def start_document(&block)
+        @handlers[:start_document] = block
+      end
+
+      # Define handler for document end event
+      #
+      # @yield Block to execute when document parsing completes
+      # @yieldreturn [void]
+      # @return [void]
+      def end_document(&block)
+        @handlers[:end_document] = block
+      end
+
+      # Define handler for element start event
+      #
+      # @yield Block to execute when opening tag is encountered
+      # @yieldparam name [String] Element name
+      # @yieldparam attributes [Hash<String, String>] Element attributes
+      # @yieldparam namespaces [Hash<String, String>] Namespace declarations
+      # @yieldreturn [void]
+      # @return [void]
+      def start_element(&block)
+        @handlers[:start_element] = block
+      end
+
+      # Define handler for element end event
+      #
+      # @yield Block to execute when closing tag is encountered
+      # @yieldparam name [String] Element name
+      # @yieldreturn [void]
+      # @return [void]
+      def end_element(&block)
+        @handlers[:end_element] = block
+      end
+
+      # Define handler for character data event
+      #
+      # @yield Block to execute when character data is encountered
+      # @yieldparam text [String] Character data
+      # @yieldreturn [void]
+      # @return [void]
+      def characters(&block)
+        @handlers[:characters] = block
+      end
+
+      # Define handler for CDATA section event
+      #
+      # @yield Block to execute when CDATA section is encountered
+      # @yieldparam text [String] CDATA content
+      # @yieldreturn [void]
+      # @return [void]
+      def cdata(&block)
+        @handlers[:cdata] = block
+      end
+
+      # Define handler for comment event
+      #
+      # @yield Block to execute when comment is encountered
+      # @yieldparam text [String] Comment content
+      # @yieldreturn [void]
+      # @return [void]
+      def comment(&block)
+        @handlers[:comment] = block
+      end
+
+      # Define handler for processing instruction event
+      #
+      # @yield Block to execute when PI is encountered
+      # @yieldparam target [String] PI target
+      # @yieldparam data [String] PI data
+      # @yieldreturn [void]
+      # @return [void]
+      def processing_instruction(&block)
+        @handlers[:processing_instruction] = block
+      end
+
+      # Define handler for error event
+      #
+      # @yield Block to execute when error occurs
+      # @yieldparam error [Moxml::ParseError] The error
+      # @yieldreturn [void]
+      # @return [void]
+      def error(&block)
+        @handlers[:error] = block
+      end
+
+      # Define handler for warning event
+      #
+      # @yield Block to execute when warning occurs
+      # @yieldparam message [String] Warning message
+      # @yieldreturn [void]
+      # @return [void]
+      def warning(&block)
+        @handlers[:warning] = block
+      end
+
+      # @private
+      def on_start_document
+        @handlers[:start_document]&.call
+      end
+
+      # @private
+      def on_end_document
+        @handlers[:end_document]&.call
+      end
+
+      # @private
+      def on_start_element(name, attributes = {}, namespaces = {})
+        @handlers[:start_element]&.call(name, attributes, namespaces)
+      end
+
+      # @private
+      def on_end_element(name)
+        @handlers[:end_element]&.call(name)
+      end
+
+      # @private
+      def on_characters(text)
+        @handlers[:characters]&.call(text)
+      end
+
+      # @private
+      def on_cdata(text)
+        @handlers[:cdata]&.call(text)
+      end
+
+      # @private
+      def on_comment(text)
+        @handlers[:comment]&.call(text)
+      end
+
+      # @private
+      def on_processing_instruction(target, data)
+        @handlers[:processing_instruction]&.call(target, data)
+      end
+
+      # @private
+      def on_error(error)
+        if @handlers[:error]
+          @handlers[:error].call(error)
+        else
+          super
+        end
+      end
+
+      # @private
+      def on_warning(message)
+        @handlers[:warning]&.call(message)
+      end
+    end
+  end
+end

data/lib/moxml/sax/element_handler.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require_relative "handler"
+
+module Moxml
+  module SAX
+    # Element-focused SAX handler with stack tracking
+    #
+    # Extends the base Handler with utilities for tracking element context:
+    # - Element stack (current hierarchy)
+    # - Current path (array of element names from root)
+    # - Helper methods for checking context
+    #
+    # @example Using element context
+    #   class MyHandler < Moxml::SAX::ElementHandler
+    #     def on_start_element(name, attributes = {}, namespaces = {})
+    #       super # Important: call super to update stack
+    #
+    #       if path_matches?(%r{/library/book/title$})
+    #         puts "Found title at: #{current_path.join('/')}"
+    #       end
+    #     end
+    #   end
+    #
+    class ElementHandler < Handler
+      # @return [Array<String>] Stack of currently open elements
+      attr_reader :element_stack
+
+      # @return [Array<String>] Current path from root to current element
+      attr_reader :current_path
+
+      def initialize
+        super
+        @element_stack = []
+        @current_path = []
+      end
+
+      # Tracks element on stack before calling super
+      #
+      # @param name [String] Element name
+      # @param attributes [Hash] Element attributes
+      # @param namespaces [Hash] Namespace declarations
+      # @return [void]
+      def on_start_element(name, attributes = {}, namespaces = {})
+        @element_stack.push(name)
+        @current_path.push(name)
+        super
+      end
+
+      # Removes element from stack before calling super
+      #
+      # @param name [String] Element name
+      # @return [void]
+      def on_end_element(name)
+        @element_stack.pop
+        @current_path.pop
+        super
+      end
+
+      # Check if currently inside an element with the given name
+      #
+      # @param name [String] Element name to check
+      # @return [Boolean] true if inside the element
+      # @example
+      #   in_element?("book") # true if inside any <book> element
+      def in_element?(name)
+        @element_stack.include?(name)
+      end
+
+      # Get the name of the current (innermost) element
+      #
+      # @return [String, nil] Current element name, or nil if at document level
+      # @example
+      #   current_element # => "title"
+      def current_element
+        @element_stack.last
+      end
+
+      # Get the name of the parent element
+      #
+      # @return [String, nil] Parent element name, or nil if no parent
+      # @example
+      #   parent_element # => "book"
+      def parent_element
+        @element_stack[-2]
+      end
+
+      # Get current depth in the document tree
+      #
+      # @return [Integer] Current nesting level (0 at document root)
+      # @example
+      #   depth # => 3 (e.g., /library/book/title)
+      def depth
+        @element_stack.length
+      end
+
+      # Check if current path matches a pattern
+      #
+      # @param pattern [String, Regexp] Pattern to match against path
+      # @return [Boolean] true if path matches
+      # @example
+      #   path_matches?(/book\/title$/) # true if at /*/book/title
+      #   path_matches?("/library/book/title") # exact path match
+      def path_matches?(pattern)
+        path_str = "/#{@current_path.join('/')}"
+        if pattern.is_a?(Regexp)
+          !path_str.match?(pattern).nil?
+        else
+          path_str == pattern.to_s
+        end
+      end
+
+      # Get the full path as a string
+      #
+      # @param separator [String] Path separator (default: "/")
+      # @return [String] Full path string
+      # @example
+      #   path_string # => "/library/book/title"
+      def path_string(separator = "/")
+        separator + @current_path.join(separator)
+      end
+    end
+  end
+end

data/lib/moxml/sax/handler.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Moxml
+  module SAX
+    # Abstract base class for SAX event handlers
+    #
+    # This class defines the interface for handling SAX parsing events.
+    # Subclass this and override the event methods you need to handle.
+    #
+    # All event methods have default implementations that do nothing,
+    # so you only need to override the events you care about.
+    #
+    # @example Create a custom handler
+    #   class BookHandler < Moxml::SAX::Handler
+    #     def on_start_element(name, attributes = {}, namespaces = {})
+    #       puts "Found element: #{name}"
+    #     end
+    #   end
+    #
+    class Handler
+      # Called when parsing begins
+      #
+      # @return [void]
+      def on_start_document
+        # Override in subclass if needed
+      end
+
+      # Called when parsing completes successfully
+      #
+      # @return [void]
+      def on_end_document
+        # Override in subclass if needed
+      end
+
+      # Called when an opening tag is encountered
+      #
+      # @param name [String] Element name (with namespace prefix if present)
+      # @param attributes [Hash<String, String>] Element attributes
+      # @param namespaces [Hash<String, String>] Namespace declarations on this element
+      # @return [void]
+      def on_start_element(name, attributes = {}, namespaces = {})
+        # Override in subclass if needed
+      end
+
+      # Called when a closing tag is encountered
+      #
+      # @param name [String] Element name
+      # @return [void]
+      def on_end_element(name)
+        # Override in subclass if needed
+      end
+
+      # Called when character data is encountered
+      #
+      # Note: This may be called multiple times for a single text node
+      # if the parser breaks it into chunks. Concatenate if needed.
+      #
+      # @param text [String] Character data
+      # @return [void]
+      def on_characters(text)
+        # Override in subclass if needed
+      end
+
+      # Called when a CDATA section is encountered
+      #
+      # @param text [String] CDATA content
+      # @return [void]
+      def on_cdata(text)
+        # Override in subclass if needed
+      end
+
+      # Called when a comment is encountered
+      #
+      # @param text [String] Comment content
+      # @return [void]
+      def on_comment(text)
+        # Override in subclass if needed
+      end
+
+      # Called when a processing instruction is encountered
+      #
+      # @param target [String] PI target
+      # @param data [String] PI data/content
+      # @return [void]
+      def on_processing_instruction(target, data)
+        # Override in subclass if needed
+      end
+
+      # Called when a fatal parsing error occurs
+      #
+      # Default implementation raises the error.
+      # Override to handle errors differently.
+      #
+      # @param error [Moxml::ParseError] The parsing error
+      # @return [void]
+      # @raise [Moxml::ParseError] By default
+      def on_error(error)
+        raise error
+      end
+
+      # Called when a non-fatal warning occurs
+      #
+      # Default implementation ignores warnings.
+      # Override to handle warnings (e.g., log them).
+      #
+      # @param message [String] Warning message
+      # @return [void]
+      def on_warning(message)
+        # Override in subclass if needed
+      end
+    end
+  end
+end

data/lib/moxml/sax.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "sax/handler"
+require_relative "sax/element_handler"
+require_relative "sax/block_handler"
+
+module Moxml
+  # SAX (Simple API for XML) parsing interface
+  #
+  # Provides event-driven XML parsing across all Moxml adapters.
+  # SAX parsing is memory-efficient and suitable for processing large XML files.
+  #
+  # @example Class-based handler
+  #   class MyHandler < Moxml::SAX::Handler
+  #     def on_start_element(name, attributes = {}, namespaces = {})
+  #       puts "Started element: #{name}"
+  #     end
+  #   end
+  #
+  #   context = Moxml.new
+  #   context.sax_parse(xml_string, MyHandler.new)
+  #
+  # @example Block-based handler
+  #   context.sax_parse(xml_string) do
+  #     start_element { |name, attrs| puts "Element: #{name}" }
+  #     characters { |text| puts "Text: #{text}" }
+  #   end
+  #
+  module SAX
+  end
+end

data/lib/moxml/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Moxml
-  VERSION = "0.1.7"
+  VERSION = "0.1.8"
 end

data/lib/moxml/xml_utils/encoder.rb

@@ -10,19 +10,19 @@ module Moxml
         basic: {
           "<" => "&lt;",
           ">" => "&gt;",
-          "&" => "&amp;"
+          "&" => "&amp;",
         },
         quotes: {
           "'" => "&apos;",
-          '"' => "&quot;"
+          '"' => "&quot;",
         },
         full: {
           "<" => "&lt;",
           ">" => "&gt;",
           "'" => "&apos;",
           '"' => "&quot;",
-          "&" => "&amp;"
-        }
+          "&" => "&amp;",
+        },
       }.freeze
       MODES = MAPPINGS.keys.freeze
 

data/lib/moxml/xml_utils.rb

@@ -3,7 +3,7 @@
 require_relative "xml_utils/encoder"
 
 # Ruby 3.3+ requires the URI module to be explicitly required
-require "uri" unless defined?(::URI)
+require "uri" unless defined?(URI)
 
 module Moxml
   module XmlUtils
@@ -47,17 +47,20 @@ module Moxml
     def validate_element_name(name)
       return if name.is_a?(String) && name.match?(/^[a-zA-Z_][\w\-.:]*$/)
 
-      raise ValidationError, "Invalid XML name: #{name}"
+      raise ValidationError, "Invalid XML element name: #{name}"
     end
 
     def validate_pi_target(target)
       return if target.is_a?(String) && target.match?(/^[a-zA-Z_][\w\-.]*$/)
 
-      raise ValidationError, "Invalid XML target: #{target}"
+      raise ValidationError,
+            "Invalid XML processing instruction target: #{target}"
     end
 
     def validate_uri(uri)
-      return if uri.empty? || uri.match?(/\A#{::URI::DEFAULT_PARSER.make_regexp}\z/)
+      if uri.empty? || uri.match?(/\A#{::URI::DEFAULT_PARSER.make_regexp}\z/)
+        return
+      end
 
       raise ValidationError, "Invalid URI: #{uri}"
     end