leptris 1.1.2-aarch64-linux

data/lib/leptris/xml/node.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+class Leptris::XML::Node
+  attr_reader :c_ptr, :document
+
+  def initialize(c_ptr, document, parent: nil)
+    @c_ptr = c_ptr
+    @document = document
+    @parent = parent
+  end
+
+  def self.wrap(c_ptr, document, parent: nil)
+    # Per-document weak-ref cache. Returns the existing wrapper when the
+    # same c_ptr is wrapped twice (common in children/sibling walks,
+    # repeated xpath queries, traverse-then-access patterns). The cache
+    # dies with the document so no stale entries.
+    if document && (cached = document.wrapper_cache[c_ptr.address])
+      return cached
+    end
+
+    node =
+      case Leptris::XML::FFI.leptris_node_get_type(c_ptr)
+      when Leptris::XML::FFI::NODE_ELEMENT
+        Leptris::XML::Element.new(c_ptr, document, parent: parent)
+      when Leptris::XML::FFI::NODE_TEXT
+        Leptris::XML::Text.new(c_ptr, document, parent: parent)
+      when Leptris::XML::FFI::NODE_COMMENT
+        Leptris::XML::Comment.new(c_ptr, document, parent: parent)
+      when Leptris::XML::FFI::NODE_CDATA
+        Leptris::XML::CDATA.new(c_ptr, document, parent: parent)
+      when Leptris::XML::FFI::NODE_PI
+        Leptris::XML::ProcessingInstruction.new(c_ptr, document, parent: parent)
+      else
+        new(c_ptr, document, parent: parent)
+      end
+
+    document.wrapper_cache[c_ptr.address] = node if document
+    node
+  end
+
+  def name
+    raise NotImplementedError, "#{self.class}#name not implemented"
+  end
+
+  def content
+    raise NotImplementedError, "#{self.class}#content not implemented"
+  end
+  alias_method :text, :content
+  alias_method :inner_text, :content
+
+  def type
+    Leptris::XML::FFI.leptris_node_get_type(@c_ptr)
+  end
+  alias_method :node_type, :type
+
+  def element?;  type == Leptris::XML::FFI::NODE_ELEMENT;  end
+  def text?;     type == Leptris::XML::FFI::NODE_TEXT;     end
+  def comment?;  type == Leptris::XML::FFI::NODE_COMMENT;  end
+  def cdata?;    type == Leptris::XML::FFI::NODE_CDATA;    end
+  def processing_instruction?
+    type == Leptris::XML::FFI::NODE_PI
+  end
+  alias_method :pi?, :processing_instruction?
+
+  def parent
+    return @parent if @parent
+    ptr = Leptris::XML::FFI.leptris_node_parent(@c_ptr)
+    return nil if ptr.null?
+    Leptris::XML::Node.wrap(ptr, @document)
+  end
+
+  def line
+    Leptris::XML::FFI.leptris_node_line(@c_ptr)
+  end
+
+  def <=>(other)
+    return nil unless other.is_a?(Leptris::XML::Node)
+    return nil unless @document == other.document
+    Leptris::XML::FFI.leptris_node_compare(@c_ptr, other.c_ptr)
+  end
+
+  def child
+    ptr = Leptris::XML::FFI.leptris_node_first_child(@c_ptr)
+    return nil if ptr.null?
+    Leptris::XML::Node.wrap(ptr, @document, parent: as_element_or_self)
+  end
+
+  def children
+    nodes = []
+    ptr = Leptris::XML::FFI.leptris_node_first_child(@c_ptr)
+    until ptr.nil? || ptr.null?
+      nodes << Leptris::XML::Node.wrap(ptr, @document, parent: as_element_or_self)
+      ptr = Leptris::XML::FFI.leptris_node_next_sibling(ptr)
+    end
+    Leptris::XML::NodeSet.new(@document, nodes)
+  end
+
+  def next_sibling
+    ptr = Leptris::XML::FFI.leptris_node_next_sibling(@c_ptr)
+    return nil if ptr.null?
+    Leptris::XML::Node.wrap(ptr, @document, parent: @parent)
+  end
+  alias_method :next, :next_sibling
+
+  def previous_sibling
+    ptr = Leptris::XML::FFI.leptris_node_previous_sibling(@c_ptr)
+    return nil if ptr.null?
+    Leptris::XML::Node.wrap(ptr, @document, parent: @parent)
+  end
+  alias_method :previous, :previous_sibling
+
+  def first_element_child
+    ptr = Leptris::XML::FFI.leptris_node_first_child(@c_ptr)
+    until ptr.nil? || ptr.null?
+      node = Leptris::XML::Node.wrap(ptr, @document, parent: as_element_or_self)
+      return node if node.element?
+      ptr = Leptris::XML::FFI.leptris_node_next_sibling(ptr)
+    end
+    nil
+  end
+
+  def last_element_child
+    children.reverse_each.find(&:element?)
+  end
+
+  def element_children
+    children.select(&:element?)
+  end
+  alias_method :elements, :element_children
+
+  def next_element
+    sibling = next_sibling
+    sibling = sibling.next_sibling until sibling.nil? || sibling.element?
+    sibling
+  end
+
+  def previous_element
+    sibling = previous_sibling
+    sibling = sibling.previous_sibling until sibling.nil? || sibling.element?
+    sibling
+  end
+
+  def unlink
+    Leptris::XML::FFI.check_status(
+      Leptris::XML::FFI.leptris_node_unlink(@c_ptr))
+    @parent = nil
+    self
+  end
+  alias_method :remove, :unlink
+
+  # Walks the subtree in post-order DFS (matches Nokogiri's semantics).
+  #
+  # Specialized hot path: skips the intermediate NodeSet allocation that
+  # Element#children would create, walking via raw FFI calls and wrapping
+  # nodes directly. Saves one Array + one NodeSet allocation per parent
+  # node. For a tree of N nodes that's ~N fewer allocations on a full
+  # traversal.
+  #
+  # Still pays ~2 FFI calls per visited node (first_child + next_sibling).
+  # Beating Nokogiri on this benchmark needs C-side traverse with a
+  # callback (libleptris #273); the per-node FFI cost is the floor.
+  def traverse
+    return enum_for(:traverse) unless block_given?
+    callback = ::FFI::Function.new(:int, [:pointer, :pointer], blocking: true) do |node_ptr, _|
+      yield Leptris::XML::Node.wrap(node_ptr, @document)
+      0
+    end
+    Leptris::XML::FFI.leptris_node_traverse(
+      @c_ptr, Leptris::XML::FFI::TRAVERSE_POST_ORDER, callback, nil)
+  end
+
+  def path
+    str_ptr = Leptris::XML::FFI.leptris_node_get_xpath(@c_ptr)
+    return nil if str_ptr.null?
+    Leptris::XML::FFI.read_owned_string(str_ptr)
+  end
+
+  def css_path
+    return nil if path.nil?
+    path.split("/").filter_map do |part|
+      next nil if part.empty?
+      part.gsub(/\[(\d+)\]/, ':nth-of-type(\1)')
+    end.join(" > ")
+  end
+
+  def dup
+    elem_ptr = Leptris::XML::FFI.leptris_node_as_element(@c_ptr)
+    raise Leptris::XML::Error, "dup is only supported for element nodes" if elem_ptr.null?
+    copy_ptr = Leptris::XML::FFI.leptris_element_copy(elem_ptr, @document.c_ptr)
+    raise Leptris::XML::Error, "leptris_element_copy failed" if copy_ptr.null?
+    Leptris::XML::Node.wrap(copy_ptr, @document)
+  end
+  alias_method :clone, :dup
+
+  def ==(other)
+    return false unless other.is_a?(Leptris::XML::Node)
+    @c_ptr == other.c_ptr
+  end
+
+  def inspect
+    "#<#{self.class.name} ptr=#{c_ptr}>"
+  end
+
+  protected
+
+  def as_element_or_self
+    is_a?(Leptris::XML::Element) ? self : nil
+  end
+
+  include Leptris::XML::Searchable
+end

data/lib/leptris/xml/node_set.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+class Leptris::XML::NodeSet
+  include Enumerable
+  include Leptris::XML::Searchable
+
+  attr_reader :document
+
+  # Two construction modes:
+  # - eager: pass an Array of Nodes (e.g. Element#children builds one)
+  # - lazy:  pass an FFI::Pointer to a LeptrisXPathResult that this NodeSet
+  #          will keep alive and free on GC. Each [i] / each call goes
+  #          through leptris_xpath_result_get instead of pre-materializing.
+  def initialize(document, source = nil)
+    @document = document
+    case source
+    when ::FFI::Pointer
+      if source.null?
+        @result_ptr = nil
+        @array = []
+      else
+        # Wrap in AutoPointer for automatic GC-time cleanup. NodeSet has no
+        # explicit #free method (Nokogiri doesn't either), so the AutoPointer
+        # double-free risk that Document#free hit doesn't apply here.
+        @result_ptr = ::FFI::AutoPointer.new(source, Leptris::XML::FFI.method(:leptris_xpath_result_free))
+        @array = nil
+      end
+    when nil
+      @result_ptr = nil
+      @array = []
+    else
+      @result_ptr = nil
+      @array = source.to_a
+    end
+  end
+
+  def self.from_result(document, result_ptr)
+    new(document, result_ptr)
+  end
+
+  def length
+    @result_ptr ? Leptris::XML::FFI.leptris_xpath_result_count(@result_ptr) : @array.length
+  end
+  alias_method :size, :length
+
+  def empty?
+    length == 0
+  end
+
+  def [](idx)
+    if @result_ptr
+      return nil if idx < 0 || idx >= length
+      ptr = Leptris::XML::FFI.leptris_xpath_result_get_node(@result_ptr, idx)
+      return nil if ptr.null?
+      Leptris::XML::Node.wrap(ptr, @document)
+    else
+      @array[idx]
+    end
+  end
+
+  def each
+    return enum_for(:each) unless block_given?
+    if @result_ptr
+      # Batch-fetch all node pointers in one FFI call (leptris_xpath_result_get_nodes,
+      # libleptris v0.11.4) and wrap each. Saves N-1 FFI calls vs the per-index
+      # leptris_xpath_result_get loop. Wrappers are still cached per-Document via
+      # Node.wrap, so a re-iteration of the same NodeSet hits the cache.
+      n = length
+      if n > 0
+        buf = ::FFI::MemoryPointer.new(:pointer, n)
+        begin
+          copied = Leptris::XML::FFI.leptris_xpath_result_get_nodes(@result_ptr, buf, n)
+          copied.times do |i|
+            ptr = buf.get_pointer(i * ::FFI.type_size(:pointer))
+            next if ptr.null?
+            yield Leptris::XML::Node.wrap(ptr, @document)
+          end
+          # The batch accessor under-copies mixed-kind results (upstream
+          # leptris#477); fall back to per-index fetch for the remainder.
+          (copied...n).each do |i|
+            ptr = Leptris::XML::FFI.leptris_xpath_result_get_node(@result_ptr, i)
+            next if ptr.null?
+            yield Leptris::XML::Node.wrap(ptr, @document)
+          end
+        ensure
+          buf.free
+        end
+      end
+    else
+      @array.each { |n| yield n }
+    end
+    self
+  end
+
+  def to_a
+    return @array if @array
+    return [] if @result_ptr.nil?
+    out = []
+    each { |n| out << n }
+    @array = out  # memoize so subsequent to_a / each avoids re-fetch
+    out
+  end
+  alias_method :to_ary, :to_a
+
+  def first(n = nil)
+    return self[0] if n.nil?
+    n.times.map { |i| self[i] }.take_while { |x| !x.nil? }
+  end
+
+  def last
+    if @result_ptr
+      self[length - 1]
+    else
+      @array.last
+    end
+  end
+
+  def inner_text
+    map(&:content).join
+  end
+  alias_method :text, :inner_text
+
+  def xpath(*paths)
+    handler, _ns, _vars = parse_search_args(paths)
+    raise ArgumentError, "custom XPath handlers not supported" if handler
+    expr = paths.join(" | ")
+    accumulated = Leptris::XML::NodeSet.new(@document)
+    each do |node|
+      next unless node.is_a?(Leptris::XML::Element)
+      result_ptr = Leptris::XML::FFI.leptris_xpath_eval(
+        @document.c_ptr, node.c_ptr, expr)
+      next if result_ptr.null?
+      sub = Leptris::XML::NodeSet.send(:from_result, @document, result_ptr)
+      accumulated = merge_node_sets(accumulated, sub)
+    end
+    accumulated
+  end
+
+  def inspect
+    to_a.inspect
+  end
+
+  private
+
+  def merge_node_sets(a, b)
+    Leptris::XML::NodeSet.new(@document, a.to_a + b.to_a)
+  end
+end

data/lib/leptris/xml/parse_options.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# Parser flags, mirroring LeptrisParseFlags in libleptris's public
+# headers. Pass an instance as `Leptris::XML.parse(xml, options:)`.
+class Leptris::XML::ParseOptions
+  # Discard whitespace-only text nodes (runs between tags that contain
+  # nothing but spaces/tabs/newlines). Matches libxml2's
+  # XML_PARSE_NOBLANKS and Nokogiri's noblanks. Documents parsed this
+  # way do not round-trip pretty-printed formatting byte-for-byte.
+  NOBLANKS = Leptris::XML::FFI::LEPTRIS_PARSE_DROP_WS_TEXT
+
+  attr_reader :flags
+
+  def initialize(flags = Leptris::XML::FFI::LEPTRIS_PARSE_DEFAULT)
+    @flags = flags.to_i
+  end
+
+  def self.noblanks
+    new(NOBLANKS)
+  end
+
+  def noblanks?
+    @flags & NOBLANKS != 0
+  end
+
+  def |(other)
+    self.class.new(@flags | other.flags)
+  end
+end

data/lib/leptris/xml/processing_instruction.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+class Leptris::XML::ProcessingInstruction < Leptris::XML::Node
+  def name
+    Leptris::XML::FFI.leptris_pi_node_get_target(@c_ptr)
+  end
+  alias_method :target, :name
+
+  def content
+    Leptris::XML::FFI.leptris_pi_node_get_data(@c_ptr).to_s
+  end
+
+  def target=(new_target)
+    Leptris::XML::FFI.check_status(
+      Leptris::XML::FFI.leptris_pi_node_set_target(@c_ptr, new_target.to_s))
+    new_target
+  end
+
+  def data=(new_data)
+    Leptris::XML::FFI.check_status(
+      Leptris::XML::FFI.leptris_pi_node_set_data(@c_ptr, new_data.to_s))
+    new_data
+  end
+end

data/lib/leptris/xml/sax/document.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+class Leptris::XML::SAX::Document
+  # Called when an XML declaration is parsed.
+  def xmldecl(version, encoding, standalone)
+  end
+
+  def start_document
+  end
+
+  def end_document
+  end
+
+  # Called at the beginning of an element.
+  # +attrs+ is an Array of [name, value] pairs in source order.
+  def start_element(name, attrs = [])
+  end
+
+  def end_element(name)
+  end
+
+  def characters(string)
+  end
+
+  def comment(string)
+  end
+
+  def cdata_block(string)
+  end
+
+  def processing_instruction(name, content)
+  end
+
+  def start_prefix_mapping(prefix, uri)
+  end
+
+  def end_prefix_mapping(prefix)
+  end
+
+  def warning(string)
+  end
+
+  def error(message, line = 0, column = 0)
+  end
+end

data/lib/leptris/xml/sax/parser.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+class Leptris::XML::SAX::Parser
+  CHUNK_SIZE = 4096
+  private_constant :CHUNK_SIZE
+
+  attr_accessor :document, :encoding
+
+  def initialize(handler = Leptris::XML::SAX::Document.new, encoding = nil)
+    @document = handler
+    @encoding = encoding
+  end
+
+  # Parse a string, IO, or file path. Dispatches to parse_memory /
+  # parse_io / parse_file based on the argument type.
+  def parse(input)
+    case input
+    when String                then parse_memory(input)
+    when ->(x) { x.respond_to?(:read) } then parse_io(input)
+    else
+      raise ArgumentError, "SAX parser expects a String or IO, got #{input.class}"
+    end
+  end
+
+  def parse_memory(string)
+    string = string.dup.force_encoding("UTF-8")
+    handler_struct = build_handler_struct
+    rc = Leptris::XML::FFI.leptris_sax_parse(
+      string, string.bytesize, handler_struct.pointer, nil)
+    if rc != 0
+      raise Leptris::XML::ParseError,
+        "leptris_sax_parse failed (rc=#{rc})"
+    end
+    self
+  end
+
+  def parse_io(io)
+    handler_struct = build_handler_struct
+    parser_ptr = Leptris::XML::FFI.leptris_sax_parser_create(
+      handler_struct.pointer, nil)
+    if parser_ptr.null?
+      raise Leptris::XML::Error, "leptris_sax_parser_create failed"
+    end
+    begin
+      while (chunk = io.read(CHUNK_SIZE))
+        rc = Leptris::XML::FFI.leptris_sax_parser_feed(
+          parser_ptr, chunk, chunk.bytesize, 0)
+        if rc != 0
+          raise Leptris::XML::ParseError, "leptris_sax_parser_feed failed (rc=#{rc})"
+        end
+      end
+      # Final flush
+      rc = Leptris::XML::FFI.leptris_sax_parser_feed(parser_ptr, "", 0, 1)
+      if rc != 0
+        raise Leptris::XML::ParseError, "leptris_sax_parser_feed (final) failed (rc=#{rc})"
+      end
+    ensure
+      Leptris::XML::FFI.leptris_sax_parser_free(parser_ptr)
+    end
+    self
+  end
+
+  def parse_file(path)
+    File.open(path, "r") { |f| parse_io(f) }
+  end
+
+  private
+
+  # Build a LeptrisSAXHandler struct populated with FFI::Function callbacks
+  # that dispatch to the Ruby handler. The struct (and its callbacks) are
+  # anchored against GC via the local variable for the duration of the
+  # synchronous parse call.
+  def build_handler_struct
+    s = Leptris::XML::FFI::SAXHandler.new
+    handler = @document  # capture in closures
+
+    s[:start_document] = callback(:void, [:pointer]) do |_|
+      handler.start_document
+    end
+
+    s[:end_document] = callback(:void, [:pointer]) do |_|
+      handler.end_document
+    end
+
+    s[:start_element] = callback(:void, [:pointer, :string, :pointer]) do |_, name, attrs_ptr|
+      attrs = walk_attr_array(attrs_ptr)
+      handler.start_element(name, attrs)
+    end
+
+    s[:end_element] = callback(:void, [:pointer, :string]) do |_, name|
+      handler.end_element(name)
+    end
+
+    s[:characters] = callback(:void, [:pointer, :pointer, :size_t]) do |_, text_ptr, len|
+      handler.characters(text_ptr.read_bytes(len).force_encoding("UTF-8"))
+    end
+
+    s[:comment] = callback(:void, [:pointer, :string]) do |_, comment|
+      handler.comment(comment)
+    end
+
+    s[:cdata] = callback(:void, [:pointer, :string]) do |_, cdata|
+      handler.cdata_block(cdata)
+    end
+
+    s[:processing_instruction] = callback(:void, [:pointer, :string, :string]) do |_, target, data|
+      handler.processing_instruction(target, data)
+    end
+
+    s[:start_prefix_mapping] = callback(:void, [:pointer, :string, :string]) do |_, prefix, uri|
+      handler.start_prefix_mapping(prefix, uri)
+    end
+
+    s[:end_prefix_mapping] = callback(:void, [:pointer, :string]) do |_, prefix|
+      handler.end_prefix_mapping(prefix)
+    end
+
+    s[:error] = callback(:void, [:pointer, :string, :int, :int]) do |_, msg, line, col|
+      handler.error(msg, line, col)
+    end
+
+    s
+  end
+
+  def callback(return_type, params, blocking: true, &block)
+    ::FFI::Function.new(return_type, params, blocking: blocking, &block)
+  end
+
+  # The C `const char** attrs` is a NULL-terminated flat array of
+  # name/value pairs; CStringArray owns the format, we slice into pairs.
+  def walk_attr_array(attrs_ptr)
+    Leptris::XML::CStringArray.to_ruby(attrs_ptr).each_slice(2).to_a
+  end
+end

data/lib/leptris/xml/sax.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+module Leptris
+  module XML
+    module SAX
+      autoload :Document, "leptris/xml/sax/document"
+      autoload :Parser, "leptris/xml/sax/parser"
+    end
+  end
+end

data/lib/leptris/xml/searchable.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Leptris::XML::Searchable
+  def xpath(*paths)
+    handler, _ns, _vars = parse_search_args(paths)
+    raise ArgumentError, "custom XPath handlers not supported" if handler
+    expr = paths.join(" | ")
+
+    doc_ptr = is_a?(Leptris::XML::Document) ? c_ptr : document.c_ptr
+    context_ptr = is_a?(Leptris::XML::Document) ? nil : c_ptr
+
+    result_ptr = Leptris::XML::FFI.leptris_xpath_eval(doc_ptr, context_ptr, expr)
+    if result_ptr.null?
+      raise Leptris::XML::XPathError,
+        Leptris::XML::FFI.leptris_status_string(Leptris::XML::FFI::LEPTRIS_ERROR_XPATH)
+    end
+
+    wrap_xpath_result(result_ptr)
+  end
+
+  def at_xpath(*paths)
+    result = xpath(*paths)
+    result.is_a?(Leptris::XML::NodeSet) ? result.first : result
+  end
+
+  def search(*args)
+    paths = args.first.is_a?(Array) ? args.first : [args.first]
+    paths.map(&:to_s).all? { |p| looks_like_xpath?(p) } ? xpath(*paths) : css(*paths)
+  end
+  alias_method :/, :search
+
+  def at(*args)
+    result = search(*args)
+    result.is_a?(Leptris::XML::NodeSet) ? result.first : result
+  end
+  alias_method :%, :at
+
+  def css(*args)
+    handler, ns, _ = parse_search_args(args)
+    raise ArgumentError, "namespace bindings not supported in css" if ns && !ns.empty?
+    raise ArgumentError, "custom CSS handlers not supported" if handler
+    expr = args.map { |r| Leptris::XML::CssToXPath.convert(r) }.join(" | ")
+    xpath(expr)
+  end
+
+  def at_css(*args)
+    result = css(*args)
+    result.is_a?(Leptris::XML::NodeSet) ? result.first : result
+  end
+
+  protected
+
+  def parse_search_args(args)
+    handler = args.find { |a| !a.is_a?(String) && !a.is_a?(Hash) && !a.is_a?(Symbol) }
+    args = args - [handler] if handler
+    hashes = []
+    while args.last.is_a?(Hash) || args.last.nil?
+      hashes << args.pop
+      break if args.empty?
+    end
+    ns, vars = hashes.reverse
+    [handler, ns, vars]
+  end
+
+  def looks_like_xpath?(str)
+    %r{\A(\./|/|\.\.|\.)}.match?(str)
+  end
+
+  def wrap_xpath_result(result_ptr)
+    type = Leptris::XML::FFI.leptris_xpath_result_type(result_ptr)
+    case type
+    when Leptris::XML::FFI::XPATH_NODESET
+      Leptris::XML::NodeSet.send(:from_result, document, result_ptr)
+    when Leptris::XML::FFI::XPATH_BOOLEAN
+      v = Leptris::XML::FFI.leptris_xpath_result_boolean(result_ptr) != 0
+      Leptris::XML::FFI.leptris_xpath_result_free(result_ptr)
+      v
+    when Leptris::XML::FFI::XPATH_NUMBER
+      v = Leptris::XML::FFI.leptris_xpath_result_number(result_ptr)
+      Leptris::XML::FFI.leptris_xpath_result_free(result_ptr)
+      v
+    when Leptris::XML::FFI::XPATH_STRING
+      str_ptr = Leptris::XML::FFI.leptris_xpath_result_string(result_ptr)
+      v = Leptris::XML::FFI.read_owned_string(str_ptr)
+      Leptris::XML::FFI.leptris_xpath_result_free(result_ptr)
+      v
+    else
+      Leptris::XML::FFI.leptris_xpath_result_free(result_ptr)
+      raise Leptris::XML::XPathError, "unknown xpath result type #{type}"
+    end
+  end
+end