moxml 0.1.7 → 0.1.9

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.9"
 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

data/lib/moxml/xpath/ast/node.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module Moxml
+  module XPath
+    module AST
+      # Abstract base class for all XPath AST nodes
+      #
+      # All AST nodes must implement the #evaluate method which takes
+      # a context and returns a result (NodeSet, String, Number, or Boolean).
+      #
+      # @abstract Subclass and override {#evaluate} to implement
+      class Node
+        attr_reader :type, :children, :value
+
+        # Initialize a new AST node
+        #
+        # @param type [Symbol] Node type
+        # @param children [Array] Child nodes
+        # @param value [Object] Optional value for leaf nodes
+        def initialize(type = :node, children = [], value = nil)
+          @type = type
+          @children = Array(children)
+          @value = value
+        end
+
+        # Evaluate this AST node in the given context
+        #
+        # @param context [Moxml::XPath::Context] Evaluation context
+        # @return [Moxml::NodeSet, String, Numeric, Boolean] Result of evaluation
+        # @raise [NotImplementedError] if not overridden by subclass
+        def evaluate(context)
+          raise ::NotImplementedError,
+                "#{self.class}#evaluate must be implemented by subclass"
+        end
+
+        # Check if this node is a constant value
+        #
+        # @return [Boolean] true if node represents a constant value
+        def constant?
+          false
+        end
+
+        # Get the result type of this node
+        #
+        # @return [Symbol] One of :node_set, :string, :number, :boolean
+        def result_type
+          :unknown
+        end
+
+        # String representation for debugging
+        #
+        # @return [String] Debug representation
+        def inspect
+          if @value
+            "#<#{self.class.name} @type=#{@type} @value=#{@value.inspect}>"
+          elsif @children.any?
+            "#<#{self.class.name} @type=#{@type} children=#{@children.size}>"
+          else
+            "#<#{self.class.name} @type=#{@type}>"
+          end
+        end
+
+        alias to_s inspect
+
+        # Factory methods for creating specific node types
+
+        # Create an absolute path node (starts with / or //)
+        def self.absolute_path(descendant_or_self, *steps)
+          new(:absolute_path, [descendant_or_self] + steps)
+        end
+
+        # Create a relative path node
+        def self.relative_path(*steps)
+          new(:relative_path, steps)
+        end
+
+        # Create a path node
+        def self.path(*steps)
+          new(:path, steps)
+        end
+
+        # Create an axis node
+        def self.axis(axis_name, node_test, *predicates)
+          new(:axis, [axis_name, node_test] + predicates)
+        end
+
+        # Create a node test
+        def self.test(namespace, name)
+          new(:test, [], { namespace: namespace, name: name })
+        end
+
+        # Create a wildcard test
+        def self.wildcard
+          new(:wildcard)
+        end
+
+        # Create a predicate node
+        def self.predicate(condition)
+          new(:predicate, [condition])
+        end
+
+        # Create a function call node
+        def self.function(name, *args)
+          new(:function, args, name)
+        end
+
+        # Create a variable reference node
+        def self.variable(name)
+          new(:variable, [], name)
+        end
+
+        # Create a literal string node
+        def self.string(value)
+          new(:string, [], value)
+        end
+
+        # Create a literal number node
+        def self.number(value)
+          new(:number, [], value.to_f)
+        end
+
+        # Create a binary operator node
+        def self.binary_op(operator, left, right)
+          new(:binary_op, [left, right], operator)
+        end
+
+        # Create a unary operator node
+        def self.unary_op(operator, operand)
+          new(:unary_op, [operand], operator)
+        end
+
+        # Create a union node (|)
+        def self.union(*expressions)
+          new(:union, expressions)
+        end
+
+        # Create an attribute node
+        def self.attribute(name)
+          new(:attribute, [], name)
+        end
+
+        # Create a current node (.)
+        def self.current
+          new(:current)
+        end
+
+        # Create a parent node (..)
+        def self.parent
+          new(:parent)
+        end
+
+        # Create a node type test (text(), comment(), etc.)
+        def self.node_type(type_name)
+          new(:node_type, [], type_name)
+        end
+      end
+    end
+  end
+end