leptris 1.9.15 → 1.9.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c1b73d7abca12056f163aed086825140416384075955e593f11191156db475fc
-  data.tar.gz: ead9075339cfd0736ca79cbede18612702f4632c95d9d90a512f67b3e4c32ec7
+  metadata.gz: 790fde1b932902a17438b2abed525393ebb61464a61ff35081384409277a42cc
+  data.tar.gz: 356b2a9a9426c03a25c42577952f3634127162e449e3540816b99a8bf6cd354f
 SHA512:
-  metadata.gz: 22ec81a95a094913096d9c0749c42a64274f7af9225c4128b51529c8160f6480d3f23476b548f7c766202be9744dee9a830eaa715dbeea77a42e4d374f61b6e5
-  data.tar.gz: 5e5408837f3ca2b4b54e4069a36798000b67d87fee9ed7021927b4e6c8b95d6a04a9f9d770fcd786763569d700182f87fc5b7df54c14462391c0420f69d108ed
+  metadata.gz: 8fdfd7ed098ae1501040d5f82808c57813f5f2f8dec606d6ac966bd916cff635dd510ebf68e235a4a3e9c0da6a5a10cc9765ffe20eb06a476876dc2cf6dbc2fc
+  data.tar.gz: 26142e64a808758e72332fa8aaef029b7fee19c82c3f634f6f0ec9ba7afe7990261f958173a124f2f89ced5270c253f53256f4b12eafc99235a066e38c5b7f3a

data/CHANGELOG.md

@@ -5,6 +5,36 @@ All notable changes to Leptris will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.9.17] - 2026-08-27
+
+### Changed
+
+- **Element-hinted batch materialization**: the XPath result-set
+  batch (`leptris_xpath_result_get_nodes_ex`) fills an out_kinds
+  array the binding discarded; `Node.wrap` now accepts a known
+  `node_type:` so element entries skip the per-node get_type
+  dispatch. ELEMENT is the only hintable value — XPath's data
+  model reports CDATA as TEXT, so a TEXT hint cannot distinguish
+  Text from CDATA (different content getters); comments/CDATA/PIs
+  keep the get_type fallback. Cold 500-element materialization:
+  0.131 s -> 0.110 s (~15%). Upstream note: a full-type out_kinds
+  (or kinds on `leptris_node_children`) belongs to the #560/#562
+  ask family.
+
+## [1.9.16] - 2026-08-27
+
+### Changed
+
+- **at_xpath / at_css take the single-node path**: a new
+  `wrap_xpath_first_result` seam answers nodeset results via
+  get_node(0) + wrap + free — no NodeSet container, no AutoPointer,
+  one fewer FFI than xpath().first; scalar results keep full-wrapper
+  semantics. Measured on the canonical scraper loop: at_xpath 0.018 s
+  -> 0.005 s (3.6x — the per-iteration container churn was GC
+  pressure the old path paid twice), at_css ~24%. Equivalence with
+  xpath().first is spec-pinned across nodeset/empty/scalar shapes.
+  Also drops a vestigial `.send(:from_result)` on a public factory.
+
 ## [1.9.15] - 2026-08-27
 
 ### Changed

data/lib/leptris/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Leptris
-  VERSION = "1.9.15"
+  VERSION = "1.9.17"
 end

data/lib/leptris/xml/ffi.rb

@@ -747,14 +747,27 @@ module Leptris
       end
 
       # XPath result-set batch (leptris_xpath_result_get_nodes_ex):
-      # copies all node kinds into a caller buffer and hands back
-      # the pointer array.
+      # the call fills out_kinds in the 4-value XPATH_NODE space
+      # (ELEMENT/ATTRIBUTE/TEXT/OTHER). ELEMENT is the only value
+      # that maps unambiguously — XPath's data model reports CDATA
+      # as TEXT, so a TEXT hint cannot distinguish Text from CDATA
+      # (different content getters) — everything else falls back to
+      # get_type in the wrapper. Returns [pointers, element_hints].
+      XPATH_KIND_HINT = { XPATH_NODE_ELEMENT => NODE_ELEMENT }.freeze
+
       def self.fetch_result_nodes(result_ptr, count)
-        return [] if count.zero?
+        return [[], nil] if count.zero?
         with_pointer_buffer(count) do |buffer|
-          copied = leptris_xpath_result_get_nodes_ex(
-            result_ptr, buffer, nil, count)
-          buffer.get_array_of_pointer(0, copied)
+          kinds = ::FFI::MemoryPointer.new(:int, count)
+          begin
+            copied = leptris_xpath_result_get_nodes_ex(
+              result_ptr, buffer, kinds, count)
+            hints = kinds.get_array_of_int(0, copied)
+              .map { |k| XPATH_KIND_HINT[k] }
+            [buffer.get_array_of_pointer(0, copied), hints]
+          ensure
+            kinds.free
+          end
         end
       end
 

data/lib/leptris/xml/node.rb

@@ -12,7 +12,10 @@ class Leptris::XML::Node
     @node_type = node_type
   end
 
-  def self.wrap(c_ptr, document, parent: nil)
+  # node_type: callers holding a batch-fetched kind (the XPath
+  # result-set batch fills out_kinds) pass it so the wrap skips the
+  # get_type dispatch; nil (the default) dispatches as before.
+  def self.wrap(c_ptr, document, parent: nil, node_type: 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
@@ -21,7 +24,7 @@ class Leptris::XML::Node
       return cached
     end
 
-    node_type = Leptris::XML::FFI.leptris_node_get_type(c_ptr)
+    node_type ||= Leptris::XML::FFI.leptris_node_get_type(c_ptr)
     node =
       case node_type
       when Leptris::XML::FFI::NODE_ELEMENT

data/lib/leptris/xml/node_set.rb

@@ -81,11 +81,11 @@ class Leptris::XML::NodeSet
         # not just elements); the batch accessor under-copies
         # mixed-kind results (upstream leptris#477), so per-index
         # fetch covers the remainder.
-        pointers = Leptris::XML::FFI.fetch_result_nodes(@result_ptr, n)
+        pointers, kinds = Leptris::XML::FFI.fetch_result_nodes(@result_ptr, n)
         nodes = []
-        pointers.each do |ptr|
+        pointers.each_with_index do |ptr, i|
           next if ptr.null?
-          nodes << Leptris::XML::Node.wrap(ptr, @document)
+          nodes << Leptris::XML::Node.wrap(ptr, @document, node_type: kinds[i])
         end
         (pointers.length...n).each do |i|
           ptr = Leptris::XML::FFI.leptris_xpath_result_get_node(@result_ptr, i)

data/lib/leptris/xml/searchable.rb

@@ -24,8 +24,24 @@ module Leptris::XML::Searchable
   end
 
   def at_xpath(*paths)
-    result = xpath(*paths)
-    result.is_a?(Leptris::XML::NodeSet) ? result.first : result
+    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 =
+      if ns && !ns.empty?
+        xpath_eval_with_namespaces(doc_ptr, context_ptr, expr, ns)
+      else
+        Leptris::XML::FFI.leptris_xpath_eval(doc_ptr, context_ptr, expr)
+      end
+    if result_ptr.null?
+      raise Leptris::XML::XPathError,
+        Leptris::XML::FFI.leptris_last_error.to_s
+    end
+    Leptris::XML::Searchable.wrap_xpath_first_result(document, result_ptr)
   end
 
   def search(*args)
@@ -53,8 +69,13 @@ module Leptris::XML::Searchable
   end
 
   def at_css(*args)
-    result = css(*args)
-    result.is_a?(Leptris::XML::NodeSet) ? result.first : result
+    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
+    prefix = is_a?(Leptris::XML::Document) ? "//" : ".//"
+    expr = args.map { |r| Leptris::XML::CssToXPath.convert(r, prefix: prefix) }
+      .join(" | ")
+    at_xpath(expr)
   end
 
   protected
@@ -86,6 +107,22 @@ module Leptris::XML::Searchable
     %r{\A(\./|/|\.\.|\.)}.match?(str)
   end
 
+  # Single-node seam beside wrap_xpath_result: a nodeset answers
+  # via result_get_node(0) + wrap + free — no NodeSet container, no
+  # AutoPointer, one fewer FFI than xpath().first; scalars keep the
+  # full-wrapper semantics.
+  def self.wrap_xpath_first_result(document, result_ptr)
+    type = Leptris::XML::FFI.leptris_xpath_result_type(result_ptr)
+    if type == Leptris::XML::FFI::XPATH_NODESET
+      ptr = Leptris::XML::FFI.leptris_xpath_result_get_node(result_ptr, 0)
+      node = ptr.null? ? nil : Leptris::XML::Node.wrap(ptr, document)
+      Leptris::XML::FFI.leptris_xpath_result_free(result_ptr)
+      node
+    else
+      wrap_xpath_result(document, result_ptr)
+    end
+  end
+
   # Shared by Searchable#xpath and Leptris::XML::XPath (compiled
   # expressions): wraps a raw XPathResult pointer into the
   # Ruby-typed result and frees the C handle.
@@ -93,7 +130,7 @@ module Leptris::XML::Searchable
     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)
+      Leptris::XML::NodeSet.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)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: leptris
 version: !ruby/object:Gem::Version
-  version: 1.9.15
+  version: 1.9.17
 platform: ruby
 authors:
 - Ribose Inc.