taurus 0.1.0

data/docs/xpath-performance.adoc

@@ -0,0 +1,379 @@
+= XPath Performance Benchmarks
+:toc:
+:toclevels: 3
+
+== Overview
+
+This document provides comprehensive performance benchmarks, generated from actual benchmark runs using `benchmark-ips`.
+
+**IMPORTANT**: This file is auto-generated from benchmark data. Do not edit manually.
+To update, run the appropriate rake task (see footer).
+
+== Test Environment
+
+* **Ruby Version**: 3.1.1
+* **Platform**: arm64-darwin21
+* **Taurus Version**: 0.1.0
+* **Libraries Available**: 
+* **Nokogiri**: Available
+* **Timestamp**: 2025-11-27T18:27:43+0800
+* **Method**: benchmark-ips
+
+== Performance Summary
+
+**Overall Results** (50 tests, vs Nokogiri):
+
+* **Average**: 2.34× slower
+* **Best case**: 3.13× faster
+* **Worst case**: 10.38× slower
+* **Tests faster**: 2/50 (4.0%)
+* **Tests slower**: 48/50 (96.0%)
+
+**Verdict**: ❌ **Needs Optimization** - Significantly slower than Nokogiri
+
+== axes
+
+[cols="["3", "2", "2", "2"]",options="header"]
+|===
+|Test |Taurus |Nokogiri |vs Nokogiri
+
+|Child
+|1.39µs
+|4.3µs
+|**3.09× faster** ✅
+
+|Descendant
+|59.56µs
+|5.74µs
+|**10.38× slower** ❌
+
+|Descendant Or Self
+|17.69µs
+|6.49µs
+|**2.73× slower** ❌
+
+|Parent
+|11.5µs
+|4.27µs
+|**2.69× slower** ❌
+
+|Ancestor
+|12.5µs
+|4.3µs
+|**2.91× slower** ❌
+
+|Ancestor Or Self
+|12.72µs
+|4.36µs
+|**2.92× slower** ❌
+
+|Self
+|11.5µs
+|7.53µs
+|**1.53× slower** ❌
+
+|Following Sibling
+|11.83µs
+|6.89µs
+|**1.72× slower** ❌
+
+|Preceding Sibling
+|11.37µs
+|5.52µs
+|**2.06× slower** ❌
+
+|Following
+|17.99µs
+|12.94µs
+|**1.39× slower** ❌
+
+|Preceding
+|12.91µs
+|5.3µs
+|**2.44× slower** ❌
+
+|Attribute
+|11.29µs
+|5.08µs
+|**2.22× slower** ❌
+
+|Namespace
+|14.79µs
+|7.71µs
+|**1.92× slower** ❌
+
+|===
+
+== simple_paths
+
+[cols="["3", "2", "2", "2"]",options="header"]
+|===
+|Test |Taurus |Nokogiri |vs Nokogiri
+
+|Absolute Path
+|6.01µs
+|4.99µs
+|**1.2× slower** ❌
+
+|Relative Path
+|1.65µs
+|4.66µs
+|**2.82× faster** ✅
+
+|Descendant Path
+|12.73µs
+|4.48µs
+|**2.84× slower** ❌
+
+|Wildcard
+|10.55µs
+|4.51µs
+|**2.34× slower** ❌
+
+|Attribute Access
+|25.37µs
+|4.76µs
+|**5.33× slower** ❌
+
+|Text Nodes
+|12.85µs
+|4.67µs
+|**2.75× slower** ❌
+
+|===
+
+== position_predicates
+
+[cols="["3", "2", "2", "2"]",options="header"]
+|===
+|Test |Taurus |Nokogiri |vs Nokogiri
+
+|First
+|38.24µs
+|5.95µs
+|**6.43× slower** ❌
+
+|Last
+|14.06µs
+|5.86µs
+|**2.4× slower** ❌
+
+|Position Eq
+|11.34µs
+|5.6µs
+|**2.03× slower** ❌
+
+|Position Range
+|11.83µs
+|5.56µs
+|**2.13× slower** ❌
+
+|===
+
+== boolean_predicates
+
+[cols="["3", "2", "2", "2"]",options="header"]
+|===
+|Test |Taurus |Nokogiri |vs Nokogiri
+
+|Attribute Exists
+|11.91µs
+|5.77µs
+|**2.06× slower** ❌
+
+|Attribute Value
+|12.15µs
+|7.24µs
+|**1.68× slower** ❌
+
+|Element Exists
+|13.13µs
+|7.57µs
+|**1.73× slower** ❌
+
+|Negation
+|11.87µs
+|6.21µs
+|**1.91× slower** ❌
+
+|===
+
+== multiple_predicates
+
+[cols="["3", "2", "2", "2"]",options="header"]
+|===
+|Test |Taurus |Nokogiri |vs Nokogiri
+
+|Two Predicates
+|16.65µs
+|6.86µs
+|**2.43× slower** ❌
+
+|Position And Boolean
+|11.52µs
+|11.17µs
+|**1.03× slower** ❌
+
+|Three Predicates
+|16.73µs
+|11.11µs
+|**1.51× slower** ❌
+
+|===
+
+== nodeset_functions
+
+[cols="["3", "2", "2", "2"]",options="header"]
+|===
+|Test |Taurus |Nokogiri |vs Nokogiri
+
+|Count
+|10.64µs
+|3.69µs
+|**2.88× slower** ❌
+
+|Last Func
+|17.68µs
+|5.06µs
+|**3.49× slower** ❌
+
+|Position Func
+|12.61µs
+|8.05µs
+|**1.57× slower** ❌
+
+|Local Name
+|19.11µs
+|13.09µs
+|**1.46× slower** ❌
+
+|Name
+|15.31µs
+|13.7µs
+|**1.12× slower** ❌
+
+|===
+
+== string_functions
+
+[cols="["3", "2", "2", "2"]",options="header"]
+|===
+|Test |Taurus |Nokogiri |vs Nokogiri
+
+|String
+|13.64µs
+|11.58µs
+|**1.18× slower** ❌
+
+|Concat
+|43.93µs
+|12.81µs
+|**3.43× slower** ❌
+
+|Starts With
+|20.35µs
+|7.64µs
+|**2.66× slower** ❌
+
+|Contains
+|14.53µs
+|9.3µs
+|**1.56× slower** ❌
+
+|String Length
+|15.21µs
+|8.94µs
+|**1.7× slower** ❌
+
+|===
+
+== boolean_functions
+
+[cols="["3", "2", "2", "2"]",options="header"]
+|===
+|Test |Taurus |Nokogiri |vs Nokogiri
+
+|Boolean
+|10.76µs
+|4.56µs
+|**2.36× slower** ❌
+
+|Not
+|12.34µs
+|6.8µs
+|**1.81× slower** ❌
+
+|True
+|11.11µs
+|5.15µs
+|**2.16× slower** ❌
+
+|===
+
+== number_functions
+
+[cols="["3", "2", "2", "2"]",options="header"]
+|===
+|Test |Taurus |Nokogiri |vs Nokogiri
+
+|Number
+|12.6µs
+|7.06µs
+|**1.78× slower** ❌
+
+|Sum
+|14.71µs
+|4.51µs
+|**3.26× slower** ❌
+
+|Floor
+|18.48µs
+|11.28µs
+|**1.64× slower** ❌
+
+|Ceiling
+|22.09µs
+|10.11µs
+|**2.18× slower** ❌
+
+|===
+
+== complex_queries
+
+[cols="["3", "2", "2", "2"]",options="header"]
+|===
+|Test |Taurus |Nokogiri |vs Nokogiri
+
+|Multi Axis
+|12.58µs
+|6.44µs
+|**1.95× slower** ❌
+
+|Union
+|24.42µs
+|13.61µs
+|**1.79× slower** ❌
+
+|Nested
+|18.96µs
+|12.73µs
+|**1.49× slower** ❌
+
+|===
+
+== Conclusion
+
+Based on 50 comprehensive tests (vs Nokogiri):
+
+* **Average Performance**: 2.34× slower
+* **Tests faster**: 2/50 (4.0%)
+* **Tests slower**: 48/50 (96.0%)
+* **Best result**: 0.32×
+* **Worst result**: 10.38×
+
+❌ **Taurus performance needs optimization** - Significantly slower than Nokogiri (2.34× average).
+
+---
+
+**Generated**: 2025-11-27T18:27:43+0800  
+**Baseline**: Nokogiri

data/lib/taurus/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Taurus
+  VERSION = "0.1.0"
+end

data/lib/taurus/xml/attr.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# Lightweight attribute wrapper. libtaurus v0.4.4 doesn't expose per-attribute
+# pointers (no TaurusAttribute accessors in the public API), so an Attr is a
+# (name, value, parent_element) triple. Mutation goes through the parent
+# element via #[]. Once upstream adds attribute-level accessors, this can
+# become a pointer-backed wrapper.
+
+class Taurus::XML::Attr
+  attr_reader :name, :value, :element
+
+  def initialize(name, value, element)
+    @name = name
+    @value = value
+    @element = element
+  end
+
+  def value=(new_value)
+    @element[@name] = new_value
+    @value = new_value
+  end
+
+  def namespace
+    nil  # upstream gap: per-attribute namespace not exposed
+  end
+
+  def remove
+    @element.remove_attribute(@name)
+  end
+
+  def to_s; @value; end
+  def to_str; @value; end
+
+  def ==(other)
+    other.is_a?(Taurus::XML::Attr) &&
+      @name == other.name && @value == other.value &&
+      @element == other.element
+  end
+
+  def inspect
+    "#<#{self.class.name} name=#{@name.inspect} value=#{@value.inspect}>"
+  end
+end

data/lib/taurus/xml/c14n.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Taurus
+  module XML
+    # @api private
+    #
+    # Builds a NULL-terminated `const char**` from a Ruby array of strings,
+    # suitable for passing to taurus_c14n_canonicalize_ex's
+    # `inclusive_ns_prefixes` argument. Returns [pointer, anchor] where
+    # anchor is the underlying MemoryPointer that the caller must keep
+    # alive (e.g. via local variable) for the duration of the FFI call.
+    def self.c14n_build_ns_pointer(inclusive_namespaces)
+      return [nil, nil] if inclusive_namespaces.nil? || inclusive_namespaces.empty?
+      strs = Array(inclusive_namespaces).map(&:to_s)
+      ptr_size = ::FFI.type_size(:pointer)
+      buffer = ::FFI::MemoryPointer.new(:pointer, strs.size + 1)
+      anchors = strs.map { |s| ::FFI::MemoryPointer.from_string(s) }
+      anchors.each_with_index { |p, i| buffer.put_pointer(i * ptr_size, p) }
+      buffer.put_pointer(strs.size * ptr_size, nil)
+      [buffer, anchors]
+    end
+  end
+end

data/lib/taurus/xml/cdata.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+class Taurus::XML::CDATA < Taurus::XML::Text
+  def name; "#cdata-section"; end
+
+  def content
+    Taurus::XML::FFI.taurus_cdata_node_get_content(@c_ptr)
+  end
+
+  def content=(new_content)
+    status = Taurus::XML::FFI.taurus_cdata_node_set_content(@c_ptr, new_content.to_s)
+    raise Taurus::XML::Error,
+      Taurus::XML::FFI.taurus_status_string(status) unless status == Taurus::XML::FFI::TAURUS_OK
+    new_content
+  end
+end

data/lib/taurus/xml/comment.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+class Taurus::XML::Comment < Taurus::XML::Node
+  def name; "comment"; end
+
+  def content
+    Taurus::XML::FFI.taurus_comment_node_get_content(@c_ptr)
+  end
+
+  def content=(new_content)
+    status = Taurus::XML::FFI.taurus_comment_node_set_content(@c_ptr, new_content.to_s)
+    raise Taurus::XML::Error,
+      Taurus::XML::FFI.taurus_status_string(status) unless status == Taurus::XML::FFI::TAURUS_OK
+    new_content
+  end
+end

data/lib/taurus/xml/css_to_xpath.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module Taurus
+  module XML
+    # Minimal CSS-to-XPath translator covering the common Nokogiri subset:
+    #
+    #   tag                    → //tag
+    #   *                      → //*
+    #   .class                 → //*[contains(concat(' ',@class,' '),' class ')]
+    #   #id                    → //*[@id='id']
+    #   [attr]                 → //*[@attr]
+    #   [attr=val]             → //*[@attr='val']
+    #   tag[attr]              → //tag[@attr]
+    #   tag[attr=val]          → //tag[@attr='val']
+    #   parent > child         → //parent/child
+    #   ancestor descendant    → //ancestor//descendant
+    #   a, b                   → //a | //b
+    #   tag:first-child        → //tag[position()=1]
+    #   tag:last-child         → //tag[position()=last()]
+    #   tag:not(simple)        → //tag[not(self::simple)]
+    #
+    # For anything beyond this subset, raise ArgumentError. Callers can fall
+    # back to writing XPath directly via #xpath/#at_xpath.
+    module CssToXPath
+      COMMA_SPLIT = /\s*,\s*/.freeze
+      private_constant :COMMA_SPLIT
+
+      # Token types in a single simple selector.
+      # tag (optional), then zero or more of: .class, #id, [attr...], :pseudo
+      TAG_RE        = /\A(\*|[\w-]+)/.freeze
+      DOT_CLASS_RE  = /\A\.([\w-]+)/.freeze
+      HASH_ID_RE    = /\A#([\w-]+)/.freeze
+      BRACKET_RE    = /\A\[([^\]]+)\]/.freeze
+      PSEUDO_RE     = /\A:([\w-]+(?:\([^)]*\))?)/.freeze
+
+      module_function
+
+      def convert(rule)
+        rule.to_s.split(COMMA_SPLIT).map { |r| convert_one(r.strip) }.join(" | ")
+      end
+
+      def convert_one(rule)
+        return "//*" if rule == "*"
+
+        # Tokenize chain first (handles > and whitespace)
+        if rule =~ /\s/ || rule.include?(">")
+          return convert_chain(rule)
+        end
+
+        convert_simple(rule, prefix: "//")
+      end
+
+      # Parse a single simple selector into (tag, predicates) where
+      # predicates is an array of XPath fragments to be joined via [p1][p2]...
+      def parse_simple(part)
+        tag = "*"
+        preds = []
+
+        s = part.strip
+        if s =~ TAG_RE
+          tag = $1
+          s = $'
+        end
+
+        until s.empty?
+          case s
+          when DOT_CLASS_RE
+            preds << "contains(concat(' ',normalize-space(@class),' '),' #{$1} ')"
+            s = $'
+          when HASH_ID_RE
+            preds << "@id='#{$1}'"
+            s = $'
+          when BRACKET_RE
+            preds << convert_attrs($1)
+            s = $'
+          when PSEUDO_RE
+            preds << convert_pseudo($1)
+            s = $'
+          else
+            raise ArgumentError,
+              "unsupported CSS selector at #{s.inspect} (in #{part.inspect})"
+          end
+        end
+
+        [tag, preds]
+      end
+
+      def convert_simple(part, prefix:)
+        tag, preds = parse_simple(part)
+        "#{prefix}#{tag}#{preds.map { |p| "[#{p}]" }.join}"
+      end
+      private_class_method :convert_simple
+
+      def convert_attrs(clause)
+        case clause.strip
+        when /\A(\w+)\z/
+          "@#{$1}"
+        when /\A(\w+)=['"]?([^'"\]]+)['"]?\z/
+          "@#{$1}='#{$2}'"
+        when /\A(\w+)~=['"]?([^'"\]]+)['"]?\z/
+          "contains(concat(' ',normalize-space(@#{$1}),' '),' #{$2} ')"
+        when /\A(\w+)\^=['"]?([^'"\]]+)['"]?\z/
+          "starts-with(@#{$1}, '#{$2}')"
+        when /\A(\w+)\$=['"]?([^'"\]]+)['"]?\z/
+          "substring(@#{$1}, string-length(@#{$1}) - string-length('#{$2}') + 1) = '#{$2}'"
+        when /\A(\w+)\*=['"]?([^'"\]]+)['"]?\z/
+          "contains(@#{$1}, '#{$2}')"
+        else
+          raise ArgumentError, "unsupported attribute selector: [#{clause}]"
+        end
+      end
+      private_class_method :convert_attrs
+
+      def convert_pseudo(pseudo)
+        case pseudo
+        when "first-child"     then "not(preceding-sibling::*)"
+        when "last-child"      then "not(following-sibling::*)"
+        when "only-child"      then "not(preceding-sibling::* or following-sibling::*)"
+        when "empty"           then "not(node())"
+        when "root"            then "not(parent::*)"
+        when /\Anot\((.+)\)\z/
+          inner_tag, _ = parse_simple($1)
+          "not(self::#{inner_tag})"
+        else
+          raise ArgumentError, "unsupported pseudo-class: :#{pseudo}"
+        end
+      end
+      private_class_method :convert_pseudo
+
+      # Tokenize chain into [sel, op, sel, op, sel, ...] where op is :child or
+      # :descendant. Then build XPath.
+      def convert_chain(rule)
+        tokens = tokenize_chain(rule)
+        build_chain_xpath(tokens)
+      end
+      private_class_method :convert_chain
+
+      def tokenize_chain(rule)
+        tokens = []
+        s = rule.strip
+        until s.empty?
+          if s.sub!(/\A\s*>\s*/, "")
+            tokens << :child
+          elsif s.sub!(/\A\s+/, "")
+            # whitespace descendant only counts if previous token is a string
+            tokens << :descendant if tokens.last.is_a?(String)
+          else
+            # Read one simple selector — keep going until whitespace or > or end
+            m = s.match(/\A[^>\s]+/)
+            raise ArgumentError, "couldn't parse CSS chain at: #{s.inspect}" unless m
+            tokens << m[0]
+            s = m.post_match
+          end
+        end
+        tokens
+      end
+      private_class_method :tokenize_chain
+
+      def build_chain_xpath(tokens)
+        first = tokens.shift
+        raise ArgumentError, "empty CSS chain" unless first.is_a?(String)
+
+        xpath = convert_simple(first, prefix: "//")
+        until tokens.empty?
+          op = tokens.shift
+          sel = tokens.shift
+          raise ArgumentError, "malformed CSS chain" unless sel.is_a?(String)
+          inner_tag, preds = parse_simple(sel)
+          connector = op == :child ? "/" : "//"
+          xpath = "#{xpath}#{connector}#{inner_tag}#{preds.map { |p| "[#{p}]" }.join}"
+        end
+        xpath
+      end
+      private_class_method :build_chain_xpath
+    end
+  end
+end

data/lib/taurus/xml/doc_type.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+class Taurus::XML::DocType
+  attr_reader :c_ptr, :document
+
+  def initialize(c_ptr, document)
+    @c_ptr = c_ptr
+    @document = document
+  end
+
+  def name
+    Taurus::XML::FFI.taurus_doctype_get_name(@c_ptr)
+  end
+  alias_method :node_name, :name
+
+  def root_name
+    Taurus::XML::FFI.taurus_doctype_get_root_name(@c_ptr)
+  end
+
+  def public_id
+    Taurus::XML::FFI.taurus_doctype_get_public_id(@c_ptr)
+  end
+
+  def system_id
+    Taurus::XML::FFI.taurus_doctype_get_system_id(@c_ptr)
+  end
+
+  def internal_subset
+    Taurus::XML::FFI.taurus_doctype_get_internal_subset(@c_ptr)
+  end
+
+  def external_id
+    pub = public_id
+    sys = system_id
+    return nil if pub.nil? && sys.nil?
+    parts = []
+    parts << "PUBLIC \"#{pub}\"" if pub
+    parts << "SYSTEM \"#{sys}\"" if sys && pub.nil?
+    parts << "\"#{sys}\"" if pub && sys
+    parts.join(" ")
+  end
+
+  def to_s
+    inner = internal_subset
+    parts = ["<!DOCTYPE #{name}"]
+    parts << external_id if external_id
+    parts << "[#{inner}]" if inner && !inner.empty?
+    parts.join(" ") + ">"
+  end
+
+  def inspect
+    "#<#{self.class.name} name=#{name.inspect} public=#{public_id.inspect} system=#{system_id.inspect}>"
+  end
+end