moxml 0.1.7 → 0.1.8

data/lib/moxml/xpath/ruby/generator.rb

@@ -0,0 +1,269 @@
+# frozen_string_literal: true
+
+module Moxml
+  module XPath
+    module Ruby
+      # Class for converting a Ruby AST to a String.
+      #
+      # This class takes a {Moxml::XPath::Ruby::Node} instance and converts it
+      # (and its child nodes) to a String that can be passed to `eval`.
+      #
+      # @private
+      class Generator
+        # @param [Moxml::XPath::Ruby::Node] ast
+        # @return [String]
+        def process(ast)
+          handler = :"on_#{ast.type}"
+          unless respond_to?(handler, true)
+            raise NotImplementedError,
+                  "Generator missing handler for node type :#{ast.type}. Node: #{ast.inspect}"
+          end
+
+          send(handler, ast)
+        end
+
+        # @param [Moxml::XPath::Ruby::Node] ast
+        # @return [String]
+        def on_followed_by(ast)
+          ast.to_a.map { |child| process(child) }.join("\n\n")
+        end
+
+        # Processes an assignment node.
+        #
+        # @param [Moxml::XPath::Ruby::Node] ast
+        # @return [String]
+        def on_assign(ast)
+          var, val = *ast
+
+          var_str = process(var)
+          val_str = process(val)
+
+          "#{var_str} = #{val_str}"
+        end
+
+        # Processes a mass assignment node.
+        #
+        # @param [Moxml::XPath::Ruby::Node] ast
+        # @return [String]
+        def on_massign(ast)
+          vars, val = *ast
+
+          var_names = vars.map { |var| process(var) }
+          val_str = process(val)
+
+          "#{var_names.join(', ')} = #{val_str}"
+        end
+
+        # Processes a `begin` node.
+        #
+        # @param [Moxml::XPath::Ruby::Node] ast
+        # @return [String]
+        def on_begin(ast)
+          body = process(ast.to_a[0])
+
+          <<~RUBY
+            begin
+              #{body}
+            end
+          RUBY
+        end
+
+        # Processes an equality node.
+        #
+        # @param [Moxml::XPath::Ruby::Node] ast
+        # @return [String]
+        def on_eq(ast)
+          left, right = *ast
+
+          left_str = process(left)
+          right_str = process(right)
+
+          "#{left_str} == #{right_str}"
+        end
+
+        # Processes a boolean "and" node.
+        #
+        # @param [Moxml::XPath::Ruby::Node] ast
+        # @return [String]
+        def on_and(ast)
+          left, right = *ast
+
+          left_str = process(left)
+          right_str = process(right)
+
+          "#{left_str} && #{right_str}"
+        end
+
+        # Processes a boolean "or" node.
+        #
+        # @param [Moxml::XPath::Ruby::Node] ast
+        # @return [String]
+        def on_or(ast)
+          left, right = *ast
+
+          left_str = process(left)
+          right_str = process(right)
+
+          "(#{left_str} || #{right_str})"
+        end
+
+        # Processes an if statement node.
+        #
+        # @param [Moxml::XPath::Ruby::Node] ast
+        # @return [String]
+        def on_if(ast)
+          cond, body, else_body = *ast
+
+          cond_str = process(cond)
+          body_str = process(body)
+
+          if else_body
+            else_str = process(else_body)
+
+            <<~RUBY
+              if #{cond_str}
+                #{body_str}
+              else
+                #{else_str}
+              end
+            RUBY
+          else
+            <<~RUBY
+              if #{cond_str}
+                #{body_str}
+              end
+            RUBY
+          end
+        end
+
+        # Processes a while statement node.
+        #
+        # @param [Moxml::XPath::Ruby::Node] ast
+        # @return [String]
+        def on_while(ast)
+          cond, body = *ast
+
+          cond_str = process(cond)
+          body_str = process(body)
+
+          <<~RUBY
+            while #{cond_str}
+              #{body_str}
+            end
+          RUBY
+        end
+
+        # Processes a method call node.
+        #
+        # @param [Moxml::XPath::Ruby::Node] ast
+        # @return [String]
+        def on_send(ast)
+          children = ast.to_a
+          receiver = children[0]
+          name = children[1]
+          args = children[2..] || []
+
+          call = name
+          brackets = name == "[]"
+
+          unless args.empty?
+            arg_strs = []
+            args.each do |arg|
+              result = process(arg)
+              # Keep processing if we got a Node back (happens with nested send nodes)
+              while result.respond_to?(:type)
+                result = process(result)
+              end
+              arg_strs << result
+            end
+            arg_str = arg_strs.join(", ")
+            call = brackets ? "[#{arg_str}]" : "#{call}(#{arg_str})"
+          end
+
+          if receiver
+            rec_str = process(receiver)
+            # Keep processing if we got a Node back
+            while rec_str.respond_to?(:type)
+              rec_str = process(rec_str)
+            end
+            call = brackets ? "#{rec_str}#{call}" : "#{rec_str}.#{call}"
+          end
+
+          call
+        end
+
+        # Processes a block node.
+        #
+        # @param [Moxml::XPath::Ruby::Node] ast
+        # @return [String]
+        def on_block(ast)
+          receiver, args, body = *ast
+
+          receiver_str = process(receiver)
+          body_str = body ? process(body) : nil
+          arg_strs = args.map { |arg| process(arg) }
+
+          <<~RUBY
+            #{receiver_str} do |#{arg_strs.join(', ')}|
+              #{body_str}
+            end
+          RUBY
+        end
+
+        # Processes a Range node.
+        #
+        # @param [Moxml::XPath::Ruby::Node] ast
+        # @return [String]
+        def on_range(ast)
+          start, stop = *ast
+
+          start_str = process(start)
+          stop_str = process(stop)
+
+          "(#{start_str}..#{stop_str})"
+        end
+
+        # Processes a string node.
+        #
+        # @param [Moxml::XPath::Ruby::Node] ast
+        # @return [String]
+        def on_string(ast)
+          ast.to_a[0].inspect
+        end
+
+        # Processes a Symbol node.
+        #
+        # @param [Moxml::XPath::Ruby::Node] ast
+        # @return [String]
+        def on_symbol(ast)
+          ast.to_a[0].to_sym.inspect
+        end
+
+        # Processes a literal node.
+        #
+        # @param [Moxml::XPath::Ruby::Node] ast
+        # @return [String]
+        def on_lit(ast)
+          ast.to_a[0]
+        end
+
+        # Processes a constant reference node (e.g., Moxml::Document).
+        #
+        # @param [Moxml::XPath::Ruby::Node] ast
+        # @return [String]
+        def on_const(ast)
+          ast.to_a.join("::")
+        end
+
+        # Processes an array literal node.
+        #
+        # @param [Moxml::XPath::Ruby::Node] ast
+        # @return [String]
+        def on_array(ast)
+          elements = ast.to_a.map { |elem| process(elem) }
+          "[#{elements.join(', ')}]"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+module Moxml
+  module XPath
+    module Ruby
+      # Class representing a single node in a Ruby AST.
+      #
+      # This class provides a fluent DSL for building Ruby code dynamically.
+      # It's modeled after the "ast" gem but simplified to avoid method conflicts.
+      #
+      # @example Building an if statement
+      #   number1 = Node.new(:lit, ['10'])
+      #   number2 = Node.new(:lit, ['20'])
+      #
+      #   (number2 > number1).if_true do
+      #     Node.new(:lit, ['30'])
+      #   end
+      #
+      # @private
+      class Node < BasicObject
+        undef_method :!, :!=
+
+        # @return [Symbol]
+        attr_reader :type
+
+        # @param [Symbol] type The type of AST node
+        # @param [Array] children Child nodes or values
+        def initialize(type, children = [])
+          @type = type.to_sym
+          @children = children
+        end
+
+        # @return [Array]
+        def to_a
+          @children
+        end
+        alias to_ary to_a
+
+        # Returns a "to_a" call node.
+        #
+        # @return [Moxml::XPath::Ruby::Node]
+        def to_array
+          Node.new(:send, [self, :to_a])
+        end
+
+        # Returns an assignment node.
+        #
+        # Wraps assigned values in a begin/end block to ensure that
+        # multiple lines of code result in the proper value being assigned.
+        #
+        # @param [Moxml::XPath::Ruby::Node] other
+        # @return [Moxml::XPath::Ruby::Node]
+        def assign(other)
+          other = other.wrap if other.type == :followed_by
+
+          Node.new(:assign, [self, other])
+        end
+
+        # Returns an equality expression node.
+        #
+        # @param [Moxml::XPath::Ruby::Node] other
+        # @return [Moxml::XPath::Ruby::Node]
+        def eq(other)
+          Node.new(:eq, [self, other])
+        end
+
+        # Returns a boolean "and" node.
+        #
+        # @param [Moxml::XPath::Ruby::Node] other
+        # @return [Moxml::XPath::Ruby::Node]
+        def and(other)
+          Node.new(:and, [self, other])
+        end
+
+        # Returns a boolean "or" node.
+        #
+        # @param [Moxml::XPath::Ruby::Node] other
+        # @return [Moxml::XPath::Ruby::Node]
+        def or(other)
+          Node.new(:or, [self, other])
+        end
+
+        # Returns a node that evaluates to its inverse.
+        #
+        # @example
+        #   foo.not # => !foo
+        #
+        # @return [Moxml::XPath::Ruby::Node]
+        def not
+          !self
+        end
+
+        # Returns a node for Ruby's "is_a?" method.
+        #
+        # @param [Class] klass
+        # @return [Moxml::XPath::Ruby::Node]
+        def is_a?(klass)
+          # If klass is already a Node (e.g., a const node), use it directly
+          # Otherwise wrap it in a lit node
+          klass_node = if klass.respond_to?(:type)
+                         klass
+                       else
+                         Node.new(:lit, [klass.to_s])
+                       end
+
+          Node.new(:send, [self, "is_a?", klass_node])
+        end
+
+        # Wraps the current node in a block.
+        #
+        # @param [Array] args Arguments (as Node instances) to pass to the block
+        # @return [Moxml::XPath::Ruby::Node]
+        def add_block(*args)
+          Node.new(:block, [self, args, yield])
+        end
+
+        # Wraps the current node in a `begin` node.
+        #
+        # @return [Moxml::XPath::Ruby::Node]
+        def wrap
+          Node.new(:begin, [self])
+        end
+
+        # Wraps the current node in an if statement node.
+        #
+        # The body of this statement is set to the return value of the supplied
+        # block.
+        #
+        # @return [Moxml::XPath::Ruby::Node]
+        def if_true
+          Node.new(:if, [self, yield])
+        end
+
+        # Wraps the current node in an `if !...` statement.
+        #
+        # @see [#if_true]
+        def if_false(&block)
+          self.not.if_true(&block)
+        end
+
+        # Wraps the current node in a `while` statement.
+        #
+        # The body of this statement is set to the return value of the supplied
+        # block.
+        #
+        # @return [Moxml::XPath::Ruby::Node]
+        def while_true
+          Node.new(:while, [self, yield])
+        end
+
+        # Adds an "else" statement to the current node.
+        #
+        # This method assumes it's being called only on "if" nodes.
+        #
+        # @return [Moxml::XPath::Ruby::Node]
+        def else
+          Node.new(:if, @children + [yield])
+        end
+
+        # Chains two nodes together.
+        #
+        # @param [Moxml::XPath::Ruby::Node] other
+        # @return [Moxml::XPath::Ruby::Node]
+        def followed_by(other = nil)
+          other = yield if ::Kernel.block_given?
+
+          Node.new(:followed_by, [self, other])
+        end
+
+        # Returns a node for a method call.
+        #
+        # @param [Symbol] name The name of the method to call
+        # @param [Array] args Any arguments (as Node instances) to pass
+        # @return [Moxml::XPath::Ruby::Node]
+        def method_missing(name, *args)
+          Node.new(:send, [self, name.to_s, *args])
+        end
+
+        # Prevent implicit string conversion - Nodes must be explicitly processed
+        def to_str
+          ::Kernel.raise ::TypeError, "Cannot implicitly
+
+ convert #{self.class} to String. Use Generator#process instead."
+        end
+
+        # @return [String]
+        def inspect
+          "(#{type} #{@children.map(&:inspect).join(' ')})"
+        end
+      end
+    end
+  end
+end

data/lib/moxml/xpath.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Moxml
+  # XPath 1.0 implementation for Moxml
+  #
+  # This module provides a complete XPath 1.0 engine for querying XML
+  # documents, particularly for the Ox adapter which has limited native
+  # XPath support.
+  #
+  # @example Basic usage
+  #   engine = Moxml::XPath::Engine.new(document)
+  #   results = engine.evaluate("//book[@id='123']")
+  #
+  module XPath
+    autoload :Engine, "moxml/xpath/engine"
+    autoload :Context, "moxml/xpath/context"
+    autoload :Conversion, "moxml/xpath/conversion"
+    autoload :Cache, "moxml/xpath/cache"
+    autoload :Lexer, "moxml/xpath/lexer"
+    autoload :Parser, "moxml/xpath/parser"
+    autoload :Compiler, "moxml/xpath/compiler"
+
+    # Require errors directly so classes are immediately available
+    require_relative "xpath/errors"
+
+    # AST nodes for expression representation
+    module AST
+      autoload :Node, "moxml/xpath/ast/node"
+    end
+
+    # Ruby AST generation for compiling XPath
+    module Ruby
+      autoload :Node, "moxml/xpath/ruby/node"
+      autoload :Generator, "moxml/xpath/ruby/generator"
+    end
+  end
+end

data/lib/moxml.rb

@@ -4,7 +4,7 @@ module Moxml
   class << self
     def new(adapter = nil, &block)
       context = Context.new(adapter)
-      context.config.instance_eval(&block) if block_given?
+      context.config.instance_eval(&block) if block
       context
     end
 
@@ -12,7 +12,8 @@ module Moxml
       yield Config.default if block_given?
     end
 
-    def with_config(adapter_name = nil, strict_parsing = nil, default_encoding = nil)
+    def with_config(adapter_name = nil, strict_parsing = nil,
+                    default_encoding = nil)
       original_config = Config.default.dup
 
       configure do |config|
@@ -42,3 +43,5 @@ require_relative "moxml/builder"
 require_relative "moxml/config"
 require_relative "moxml/context"
 require_relative "moxml/adapter"
+require_relative "moxml/xpath"
+require_relative "moxml/sax"

data/moxml.gemspec

@@ -10,7 +10,9 @@ Gem::Specification.new do |spec|
 
   spec.summary = "Unified XML manipulation library"
   spec.description = <<~DESCRIPTION
-    Moxml is a unified XML manipulation library that provides a common API.
+    Moxml is a unified XML manipulation library that provides a common API
+    for XML node navigation, manipulation, building and XPath querying
+    interface covering multiple parser implementations including Nokogiri, Oga, REXML, Ox, LibXML.
   DESCRIPTION
 
   spec.homepage = "https://github.com/lutaml/moxml"

data/old-specs/moxml/adapter/customized_libxml/.gitkeep

@@ -0,0 +1,6 @@
+# CustomizedLibxml wrapper classes are tested via:
+# spec/moxml/adapter/libxml_spec.rb
+#
+# Individual wrapper spec files removed to avoid redundant pending tests.
+# The wrapper classes (Element, Text, Cdata, Comment, etc.) are thoroughly
+# tested through the main LibXML adapter test suite.

data/spec/consistency/README.md

@@ -0,0 +1,77 @@
+# Consistency Tests
+
+## Purpose
+
+This directory contains cross-adapter consistency tests that verify all adapters produce equivalent results for the same operations. These tests act as a quality gate to ensure adapter parity.
+
+## What Should Be Placed Here
+
+- ✅ Tests verifying all adapters produce equivalent XML output
+- ✅ Tests ensuring API parity across adapters
+- ✅ Tests catching adapter-specific quirks
+- ✅ Tests for serialization consistency
+- ✅ Tests for parsing equivalence
+
+## What Should NOT Be Placed Here
+
+- ❌ Adapter-specific implementation tests (use adapter/ instead)
+- ❌ Unit tests (use unit/ instead)
+- ❌ Performance benchmarks (use performance/ instead)
+- ❌ Documentation examples (use examples/ instead)
+
+## How to Run
+
+```bash
+# Run all consistency tests
+bundle exec rake spec:consistency
+
+# Run specific consistency test
+bundle exec rspec spec/consistency/adapter_parity_spec.rb
+```
+
+## Directory Structure
+
+```
+consistency/
+└── adapter_parity_spec.rb    # Ensures all adapters produce equivalent results
+```
+
+## Writing Consistency Tests
+
+Consistency tests should compare output across all adapters:
+
+```ruby
+RSpec.describe "Adapter Parity" do
+  describe "Serialization consistency" do
+    it "produces equivalent XML across adapters" do
+      results = {}
+
+      Moxml::Adapter::AVALIABLE_ADAPTERS.each do |adapter|
+        Moxml.with_config(adapter) do
+          doc = Moxml.parse("<root><child>text</child></root>")
+          results[adapter] = doc.to_xml
+        end
+      end
+
+      # All results should be equivalent (allowing for formatting differences)
+      expect(results.values.uniq.length).to eq(1)
+    end
+  end
+end
+```
+
+## Purpose
+
+These tests ensure that:
+1. Users can switch adapters without changing behavior
+2. All adapters implement the same API surface
+3. No adapter-specific bugs leak into user code
+4. Documentation examples work with all adapters
+
+## CI Integration
+
+Consistency tests should run:
+- On every pull request
+- Before releases
+- As a quality gate
+- To catch regressions

data/spec/{moxml/examples/adapter_spec.rb → consistency/adapter_parity_spec.rb}

@@ -18,10 +18,10 @@ RSpec.describe "Adapter Examples" do
 
     def normalize_xml(xml)
       xml.gsub(/>\s+</, "><")
-         .gsub(/\s+/, " ")
-         .gsub(/ >/, ">")
-         .gsub(/\?></, "?>\n<")
-         .strip
+        .gsub(/\s+/, " ")
+        .gsub(" >", ">")
+        .gsub("?><", "?>\n<")
+        .strip
     end
   end
 end

data/spec/examples/README.md

@@ -0,0 +1,75 @@
+# Example Tests
+
+## Purpose
+
+This directory contains executable documentation examples. These tests verify that code examples from documentation and README work correctly and serve as living documentation.
+
+## What Should Be Placed Here
+
+- ✅ Tests for documentation examples
+- ✅ Tests for README code snippets
+- ✅ Examples that demonstrate API usage
+- ✅ Tutorial-style example tests
+- ✅ Tests that can be extracted for documentation
+
+## What Should NOT Be Placed Here
+
+- ❌ Comprehensive test coverage (use unit/ or integration/ instead)
+- ❌ Edge case testing (use integration/ instead)
+- ❌ Performance benchmarks (use performance/ instead)
+- ❌ Adapter-specific tests (use adapter/ instead)
+
+## How to Run
+
+```bash
+# Run all example tests
+bundle exec rake spec:examples
+
+# Run specific example test
+bundle exec rspec spec/examples/basic_usage_spec.rb
+
+# Examples can be skipped in CI
+bundle exec rspec --tag ~examples
+```
+
+## Directory Structure
+
+```
+examples/
+├── basic_usage_spec.rb        # README basic usage examples
+├── namespace_examples_spec.rb # Namespace handling examples
+├── xpath_examples_spec.rb     # XPath query examples
+└── attribute_examples_spec.rb # Attribute manipulation examples
+```
+
+## Writing Example Tests
+
+Example tests should:
+1. Be simple and easy to understand
+2. Demonstrate real-world usage patterns
+3. Run with all adapters to ensure portability
+4. Be suitable for extraction into documentation
+
+```ruby
+RSpec.describe "Basic Usage Examples" do
+  Moxml::Adapter::AVALIABLE_ADAPTERS.each do |adapter_name|
+    context "with #{adapter_name} adapter" do
+      let(:context) { Moxml.new(adapter_name) }
+
+      it "parses XML" do
+        doc = context.parse("<root>Text</root>")
+        expect(doc.root.text).to eq("Text")
+      end
+    end
+  end
+end
+```
+
+## Tagging
+
+Example tests are tagged with `:examples` and can be excluded:
+
+```ruby
+RSpec.describe "Example", :examples do
+  # ...
+end