leptris 1.9.25 → 1.9.26

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: afa52b007ec23d222a3562207fcef3f9975f62c11378da91de2d238eff7a74be
-  data.tar.gz: 878468ec897ba3f9b60aca28e1379ac712e261c4500c4cc51c2a7379545730ee
+  metadata.gz: 4c1650cd7d5f1be133b6c265c5ea6bfd646265ac443a86361bb30593dd0d255a
+  data.tar.gz: babd8da0971c8f6820f2692e7283d249cea85455f84620a73e86fe488caa1a18
 SHA512:
-  metadata.gz: a8caa0b2d6052ff1e72a1d23c59d1f283b887c852e7cb669fa8449d85438f8f89a2005726f96644f6bc46c880d717e54c922210fb9b638c2d890d6d0cdc57fbe
-  data.tar.gz: 19fab1e638971c2402b69e70447657c9dfe4d140ba55e588f09b4a394690b34c2e43ba46433615209f66be1660ee6755b83827e7b51e84516c5793b67f44d0d2
+  metadata.gz: 62d2b51adc4bd84f8a3f6c0ebc749ad328b1ceed1d9a6502234819e0c5f3bf054ac758f008beba3692f2781981d7a4de23dc0e0d6f44462f2e3d385c2eb468e8
+  data.tar.gz: 22a1369e2755c016019691507c2e867e792352fcd999be595c9fd485934f6170f44ce4320366487b1f0d30fd314b6db4941773663a6722b542af501ebc131bac

data/CHANGELOG.md

@@ -5,6 +5,44 @@ 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.26] - 2026-08-28
+
+### Added
+
+- **libleptris 1.9.7 lockstep** (upstream #602/#604): Rakefile pin
+  bumped; symbol audit 247/247 with the five new functions.
+- **`Pull::Parser#each_batch(max = 256)`** — the #589 batch
+  transport: ONE C call stages up to max events (scratch-staged,
+  layout-offset drain, no per-event dispatch). Streaming big.xml
+  (250k events): 408 ms -> **210 ms per parse (-48%)**; the cursor
+  path also drops to 347 ms (Events are now constructed
+  positionally — the keyword-init Struct cost ~220 ns/event; a
+  minor API change: `Pull::Event` no longer takes keyword args,
+  readers unchanged). Per the engine's attr-mirror protocol,
+  attributes are captured for each batch's LAST start_element —
+  use `#each` when every start's attrs must be present. Attr
+  capture on both paths is now one count query + one flat copy
+  (`leptris_pull_attrs`) instead of 2N per-index dispatches.
+- **`Document#node` / `Document#children`** (#580, our upstream
+  ask): document-level PIs/comments are tree children behind a
+  stable singleton navigation head — `children` is
+  [prolog…, root, epilog…] in document order (the libxml2/Nokogiri
+  model), and `/comment()` / `//processing-instruction()` see the
+  document-level nodes. The dedicated memoized
+  `#processing_instructions` / `#comments` readers are unchanged.
+- **`NodeSet#xpath` through the union entry** (`leptris_xpath_
+  eval_nodeset`, #589): one C call for N contexts — results
+  de-duplicated and document-ordered, which the per-member Ruby
+  loop it replaces could not guarantee.
+
+### Meta
+
+- Engine swap 1.9.4 -> 1.9.7 regression battery (interleaved
+  best-of-3): cold walk 4,637 vs 4,652 µs, DOM parse 72 vs 73 µs,
+  SAX text-only 22.7 vs 22.6 ms — parity across the board. The
+  v1.9.6 XPath fixes (`/descendant::` root inclusion, $var head
+  dropping) are covered by the existing suite plus the new specs.
+
 ## [1.9.25] - 2026-08-28
 
 ### Fixed

data/Rakefile

@@ -8,7 +8,7 @@ RSpec::Core::RakeTask.new(:spec)
 # Pin for `rake compile` and the platform-gem builds. Keep in lockstep
 # with .github/workflows/build.yml (which calls `rake compile`) and the
 # CHANGELOG when libleptris releases.
-LIBLEPTRIS_VERSION = "1.9.4"
+LIBLEPTRIS_VERSION = "1.9.7"
 
 CMAKE_FLAGS = %w[
   -DCMAKE_BUILD_TYPE=Release

data/lib/leptris/version.rb

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

data/lib/leptris/xml/document.rb

@@ -151,6 +151,26 @@ class Leptris::XML::Document
     Leptris::XML::Node.wrap(ptr, self)
   end
 
+  # The document node — navigation head over the whole tree chain
+  # [prolog comments/PIs, root element, epilog comments/PIs] in
+  # document order (libleptris 1.9.7, upstream #580: the libxml2
+  # model; XPath /comment() and //processing-instruction() see the
+  # document-level nodes). A stable, document-owned singleton —
+  # Node.wrap's cache keeps the returned wrapper identical.
+  def node
+    raise Leptris::XML::UseAfterFreeError if @freed.state == :freed
+    @node ||= Leptris::XML::Node.wrap(
+      Leptris::XML::FFI.leptris_document_node(@c_ptr), self)
+  end
+
+  # The document's children, via the document node: prolog
+  # comments/PIs, the root element, epilog comments/PIs, in
+  # document order (Nokogiri-parity shape).
+  def children
+    doc_node = node
+    doc_node ? doc_node.children : Leptris::XML::NodeSet.new(self, [])
+  end
+
   # Attach +element+ as the document's root element. The element must
   # have been created against this document and must not already have
   # a parent. Any previous root is left detached (still owned by the

data/lib/leptris/xml/ffi.rb

@@ -143,6 +143,11 @@ module Leptris
         [:leptris_document, :leptris_element], :leptris_status
       attach_function :leptris_document_root,
         [:leptris_document], :leptris_element
+      # The document node — navigation head over the whole tree
+      # chain [prolog comments/PIs, root, epilog...] (libleptris
+      # 1.9.7, upstream #580; the libxml2 model).
+      attach_function :leptris_document_node,
+        [:leptris_document], :leptris_node_ref
       # Document-level PIs (v1.6.0): not tree nodes — enumerate via
       # these accessors only.
       attach_function :leptris_document_pi_count,
@@ -430,6 +435,14 @@ module Leptris
         [:leptris_document, :leptris_element, :string], :leptris_xpath_result
       attach_function :leptris_xpath_eval_with_vars,
         [:leptris_document, :string, :leptris_xpath_var_set], :leptris_xpath_result
+      # Union semantics (NodeSet#xpath): N contexts, ONE call — the
+      # engine merges the per-context results into a de-duplicated,
+      # document-ordered nodeset (libleptris 1.9.7, upstream #589).
+      attach_function :leptris_xpath_eval_nodeset,
+        [:leptris_document, :pointer, :size_t, :string], :leptris_xpath_result
+      attach_function :leptris_xpath_compiled_eval_nodeset,
+        [:leptris_document, :pointer, :size_t, :leptris_xpath_compiled],
+        :leptris_xpath_result
       attach_function :leptris_xpath_eval_with_vars_context,
         [:leptris_document, :leptris_element, :string, :leptris_xpath_var_set],
         :leptris_xpath_result
@@ -552,12 +565,16 @@ module Leptris
         [:string], :leptris_pull_parser
       attach_function :leptris_pull_next,
         [:leptris_pull_parser], :pointer
+      attach_function :leptris_pull_next_batch,
+        [:leptris_pull_parser, :pointer, :size_t], :size_t
       attach_function :leptris_pull_attr_count,
         [:leptris_pull_parser], :size_t
       attach_function :leptris_pull_attr_name,
         [:leptris_pull_parser, :size_t], :string
       attach_function :leptris_pull_attr_value,
         [:leptris_pull_parser, :size_t], :string
+      attach_function :leptris_pull_attrs,
+        [:leptris_pull_parser, :pointer, :size_t], :size_t
       attach_function :leptris_pull_free,
         [:leptris_pull_parser], :void
 
@@ -908,6 +925,20 @@ module Leptris
         end
         ptr
       end
+
+      # Pull-event staging block for leptris_pull_next_batch (the
+      # #589 bulk transport): LeptrisPullEvent records, stride from
+      # the struct layout that mirrors the ABI.
+      def self.scratch_events(count)
+        need = count * PullEventStruct.size
+        scratch = (Thread.current[:leptris_scratch] ||= {})
+        ptr = scratch[:pull_events]
+        if ptr.nil? || ptr.size < need
+          ptr&.free
+          ptr = scratch[:pull_events] = ::FFI::MemoryPointer.new(need)
+        end
+        ptr
+      end
     end
   end
 end

data/lib/leptris/xml/node_set.rb

@@ -127,24 +127,23 @@ class Leptris::XML::NodeSet
   end
   alias_method :text, :inner_text
 
-  # Union semantics: evaluate the expression against each element
-  # member (one C eval per member — the engine has no multi-context
-  # eval yet; leptris/leptris ask pending) and accumulate into ONE
-  # NodeSet, instead of merging NodeSets per member.
+  # Union semantics: ONE engine call evaluates the expression
+  # against every element member and merges the results into a
+  # de-duplicated, document-ordered nodeset (libleptris 1.9.7,
+  # upstream #589 — the per-member Ruby loop this replaces could
+  # neither dedup nor order).
   def xpath(*paths)
     handler, _ns, _vars = parse_search_args(paths)
     raise ArgumentError, "custom XPath handlers not supported" if handler
     expr = paths.join(" | ")
-    accumulated = []
-    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?
-      accumulated.concat(
-        Leptris::XML::NodeSet.from_result(@document, result_ptr).to_a)
-    end
-    Leptris::XML::NodeSet.new(@document, accumulated)
+    contexts = to_a.select { |node| node.is_a?(Leptris::XML::Element) }
+    return Leptris::XML::NodeSet.new(@document, []) if contexts.empty?
+    buffer = Leptris::XML::FFI.scratch_pointers(contexts.size)
+    buffer.write_array_of_pointer(contexts.map(&:c_ptr))
+    result_ptr = Leptris::XML::FFI.leptris_xpath_eval_nodeset(
+      @document.c_ptr, buffer, contexts.size, expr)
+    return Leptris::XML::NodeSet.new(@document, []) if result_ptr.null?
+    Leptris::XML::NodeSet.from_result(@document, result_ptr)
   end
 
   def inspect

data/lib/leptris/xml/pull.rb

@@ -14,7 +14,10 @@ require "ffi"
 #     end
 #
 module Leptris::XML::Pull
-  Event = Struct.new(:type, :name, :text, :attrs, keyword_init: true)
+  # Constructed positionally by the parser: the keyword-init
+  # variant cost ~220ns/event in batch drains (round XXI). Readers
+  # (event.type, event.attrs, ...) are unchanged.
+  Event = Struct.new(:type, :name, :text, :attrs)
 
   TYPES = {
     Leptris::XML::FFI::PULL_START_ELEMENT => :start_element,
@@ -60,6 +63,49 @@ module Leptris::XML::Pull
       self
     end
 
+    # Bulk-delivers events (libleptris 1.9.7, upstream #589): ONE C
+    # call stages up to +max_count+ events — the per-event dispatch
+    # that made streaming ~145x slower than a DOM parse collapses to
+    # amortized noise. Per the engine's protocol, attributes are
+    # captured only for the LAST start_element of each batch
+    # (earlier starts in the same batch carry nil attrs — segment
+    # boundaries fall where they fall); use #each when every
+    # start's attrs must be captured.
+    def each_batch(max_count = 256)
+      return enum_for(:each_batch, max_count) unless block_given?
+      stride = Leptris::XML::FFI::PullEventStruct.size
+      type_off = 0
+      name_off = Leptris::XML::FFI::PullEventStruct.offset_of(:name)
+      text_off = Leptris::XML::FFI::PullEventStruct.offset_of(:text)
+      buffer = Leptris::XML::FFI.scratch_events(max_count)
+      while (n = Leptris::XML::FFI.leptris_pull_next_batch(
+               @handle, buffer, max_count)) > 0
+        events = Array.new(n) do |i|
+          base = i * stride
+          name_ptr = buffer.get_pointer(base + name_off)
+          text_ptr = buffer.get_pointer(base + text_off)
+          Event.new(
+            TYPES[buffer.get_int(base + type_off)],
+            name_ptr.null? ? nil :
+              name_ptr.read_string.force_encoding(Encoding::UTF_8),
+            text_ptr.null? ? nil :
+              text_ptr.read_string.force_encoding(Encoding::UTF_8),
+            nil
+          )
+        end
+        # The attr mirror holds the batch's most recent start.
+        last_start = nil
+        events.each_with_index do |event, i|
+          last_start = i if event.type == :start_element
+        end
+        events[last_start].attrs = capture_attrs if last_start
+        events.each { |event| yield event }
+        tail = events.last.type
+        break if tail == :end_document || tail == :error
+      end
+      self
+    end
+
     # Hot-loop offsets: derived from PullEventStruct's layout (the
     # struct stays the single source of truth for the ABI), read via
     # get_int/get_pointer so the per-event struct-wrapper allocation
@@ -80,23 +126,32 @@ module Leptris::XML::Pull
       text_ptr = raw.get_pointer(TEXT_OFFSET)
       attrs = type == :start_element ? capture_attrs : nil
       Event.new(
-        type: type,
-        name: name_ptr.null? ? nil : name_ptr.read_string.force_encoding(Encoding::UTF_8),
-        text: text_ptr.null? ? nil : text_ptr.read_string.force_encoding(Encoding::UTF_8),
-        attrs: attrs
+        type,
+        name_ptr.null? ? nil : name_ptr.read_string.force_encoding(Encoding::UTF_8),
+        text_ptr.null? ? nil : text_ptr.read_string.force_encoding(Encoding::UTF_8),
+        attrs
       )
     end
 
     private
 
+    # One count-only query plus one flat copy (leptris_pull_attrs,
+    # 1.9.7) — the char** wire format the SAX callbacks already use —
+    # replaces the 2N per-index dispatches.
     def capture_attrs
-      count = Leptris::XML::FFI.leptris_pull_attr_count(@handle)
-      return nil if count.zero?
+      total = Leptris::XML::FFI.leptris_pull_attrs(@handle, nil, 0)
+      return nil if total.zero?
+      buffer = Leptris::XML::FFI.scratch_pointers(2 * total)
+      copied = Leptris::XML::FFI.leptris_pull_attrs(@handle, buffer, total)
+      ptr_size = ::FFI.type_size(:pointer)
       hash = {}
       i = 0
-      while i < count
-        hash[Leptris::XML::FFI.leptris_pull_attr_name(@handle, i)] =
-          Leptris::XML::FFI.leptris_pull_attr_value(@handle, i)
+      while i < copied
+        name = buffer.get_pointer(2 * i * ptr_size).read_string
+          .force_encoding(Encoding::UTF_8)
+        value = buffer.get_pointer((2 * i + 1) * ptr_size).read_string
+          .force_encoding(Encoding::UTF_8)
+        hash[name] = value
         i += 1
       end
       hash

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: leptris
 version: !ruby/object:Gem::Version
-  version: 1.9.25
+  version: 1.9.26
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-27 00:00:00.000000000 Z
+date: 2026-08-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi