leptris 1.9.1 → 1.9.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed2f1d5755923f389734df36cc9c40c513535e58e7abe5a40aa87dd93f858788
-  data.tar.gz: eb4e9c9c3b12a7584572746053c9aaf318ee5481fa002909d8502d5565bcf543
+  metadata.gz: 6d6cc4a584231a903d60b34a8b3e438c729d804743f66ada5b9944dac2c2662e
+  data.tar.gz: 2cfcc126bf8e78363d6614e06ddfed0d72bd653eac0087f80781e237a7c1f85a
 SHA512:
-  metadata.gz: 35a1a34584014746679c39098f60c6009871007e3e5016562b669437e6f00d84412c7a26f286034f628421f72846c810b1b3568faacbbae86fa3e6c47b6db20f
-  data.tar.gz: 5e4785ee975db46c2f7798a4effd7c3d2be729e94ded98db78e3cdd830891b0704170e104d9b2287ff1e4e8a98833917a70a7ec4d5591615931020cf67f18e54
+  metadata.gz: 6fe8c57e921c84a0c31552c255151e1f0a756236282b7d8ac184a7f54da5dcac465747d33acc77fbd38d47506fcfc7d89961711c7ae3daf45aa08cbc9ef337fe
+  data.tar.gz: ea5561b2e483f0dc17c9942d60763565873f3d983b2f188e71153afd60e83909ce53a40a61d3c73e15be13592e0c00f2752aaad9cca8365e3e68d5b2bd5455a8

data/CHANGELOG.md

@@ -5,6 +5,29 @@ 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.2] - 2026-08-25
+
+### Changed
+
+Architecture deepening — all C ABI and buffer knowledge now lives
+behind the FFI seam (`lib/leptris/xml/ffi.rb`); no public API change.
+
+- `PullEventStruct` (FFI::Struct) replaces the pull parser's
+  hand-rolled ABI offsets (`get_int(0)` / `get_pointer(8)` /
+  `get_pointer(16)`); struct-layout changes become a one-line
+  layout edit instead of silent offset drift.
+- `FFI.with_ns_set(hash)` concentrates the namespace-binding
+  lifecycle (flatten → CStringArray wire format → build → yield →
+  free) that ad-hoc and compiled XPath each hand-wrote.
+- `FFI.serialize_into_string` / `FFI.fetch_children` /
+  `FFI.fetch_result_nodes` / `FFI.parse_fragment_with_status` own
+  the size-query/allocate/fill/read buffer protocols; Serialization,
+  NodeSet and DocumentFragment now contain no `MemoryPointer` code.
+- `Node#children` and `DocumentFragment#children` fetch all child
+  handles in one batched call (the libleptris 1.7.0 surface, now
+  attached) instead of the first_child + N next_sibling walk —
+  N+1 FFI round trips collapse to 2 dispatches plus N wraps.
+
 ## [1.9.1] - 2026-08-24
 
 ### Fixed

data/lib/leptris/version.rb

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

data/lib/leptris/xml/document_fragment.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "ffi"
-
 # Wraps the synthetic "#document-fragment" element returned by
 # leptris_parse_fragment. Children of this fragment are the parsed nodes;
 # the fragment itself isn't part of any document tree but borrows its
@@ -15,23 +13,18 @@ class Leptris::XML::DocumentFragment
   end
 
   def self.parse(xml, document)
-    status_ptr = ::FFI::MemoryPointer.new(:int)
-    raw = Leptris::XML::FFI.leptris_parse_fragment(
-      xml.to_s, xml.to_s.bytesize, document.c_ptr, status_ptr)
+    raw, status = Leptris::XML::FFI.parse_fragment_with_status(
+      xml.to_s, document.c_ptr)
     if raw.null?
       raise Leptris::XML::ParseError,
-        "leptris_parse_fragment failed (status=#{status_ptr.read_int})"
+        "leptris_parse_fragment failed (status=#{status})"
     end
     new(document, raw)
   end
 
   def children
-    count = Leptris::XML::FFI.leptris_element_child_count(@c_ptr)
-    nodes = []
-    ptr = Leptris::XML::FFI.leptris_node_first_child(@c_ptr)
-    until ptr.nil? || ptr.null?
-      nodes << Leptris::XML::Node.wrap(ptr, @document)
-      ptr = Leptris::XML::FFI.leptris_node_next_sibling(ptr)
+    nodes = Leptris::XML::FFI.fetch_children(@c_ptr).map do |ptr|
+      Leptris::XML::Node.wrap(ptr, @document)
     end
     Leptris::XML::NodeSet.new(@document, nodes)
   end

data/lib/leptris/xml/ffi.rb

@@ -80,6 +80,17 @@ module Leptris
           :recover, :int
       end
 
+      # struct LeptrisPullEvent (leptris/sax.h): FFI::Struct derives
+      # the field offsets from the layout, so ABI changes are a
+      # one-line edit here instead of silent offset drift in callers.
+      class PullEventStruct < ::FFI::Struct
+        layout \
+          :type, :int,
+          :name, :pointer,
+          :text, :pointer,
+          :text_len, :size_t
+      end
+
       attach_function :leptris_version, [], :string
       attach_function :leptris_version_components, [:pointer, :pointer, :pointer], :void
 
@@ -158,6 +169,10 @@ module Leptris
         [:leptris_node_ref], :leptris_node_ref
       attach_function :leptris_node_child_count,
         [:leptris_node_ref], :size_t
+      # libleptris 1.7.0: all-kind child batch — out_nodes=NULL is a
+      # count-only query returning the TOTAL across every child kind.
+      attach_function :leptris_node_children,
+        [:leptris_node_ref, :pointer, :size_t], :size_t
       attach_function :leptris_node_as_element,
         [:leptris_node_ref], :leptris_element
       attach_function :leptris_element_as_node,
@@ -623,6 +638,90 @@ module Leptris
         detail = leptris_last_error.to_s
         detail.empty? ? base : "#{base} (#{detail})"
       end
+
+      # Namespace-binding lifecycle, written once: flatten the
+      # prefix/URI hash into the alternating CStringArray wire
+      # format, build the caller-owned set, yield it, free it under
+      # all outcomes. Every eval variant uses this; none of them
+      # knows how a set is born or dies.
+      def self.with_ns_set(hash)
+        flat = hash.flat_map { |prefix, uri| [prefix.to_s, uri.to_s] }
+        buffer, _anchors = Leptris::XML::CStringArray.to_c(flat)
+        set = leptris_xpath_ns_set_new_from_pairs(buffer, flat.length / 2)
+        if set.null?
+          raise Leptris::XML::Error,
+            "leptris_xpath_ns_set_new_from_pairs failed"
+        end
+        begin
+          yield set
+        ensure
+          leptris_xpath_ns_set_free(set)
+        end
+      end
+
+      # Caller-buffer serialization cycle: size query (buf=NULL),
+      # allocate exactly, fill, read. Since libleptris 1.9.0 the
+      # pair reuses one serialization through the per-document
+      # cache. +ffi_function+ is leptris_document_serialize_into or
+      # leptris_element_serialize_into. The buffer holds the
+      # serialization + NUL and XML output is NUL-free, so the
+      # bounded read is exact.
+      def self.serialize_into_string(ffi_function, c_ptr, options)
+        need = ffi_function.call(c_ptr, nil, 0, nil, options)
+        return "" if need.zero?
+        buffer = ::FFI::MemoryPointer.new(:char, need)
+        begin
+          ffi_function.call(c_ptr, buffer, need, nil, options)
+          buffer.read_string
+        ensure
+          buffer.free
+        end
+      end
+
+      # All-kind child handle batch (libleptris 1.7.0): count-only
+      # query sizes the buffer, one fetch copies every child kind,
+      # one bulk read materializes the pointers.
+      def self.fetch_children(c_ptr)
+        count = leptris_node_children(c_ptr, nil, 0)
+        return [] if count.zero?
+        with_pointer_buffer(count) do |buffer|
+          copied = leptris_node_children(c_ptr, buffer, count)
+          buffer.get_array_of_pointer(0, copied)
+        end
+      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.
+      def self.fetch_result_nodes(result_ptr, count)
+        return [] 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)
+        end
+      end
+
+      # Fragment parse with the status out-param read: returns
+      # [document-or-fragment pointer, status].
+      def self.parse_fragment_with_status(xml, document_ptr)
+        status = ::FFI::MemoryPointer.new(:int)
+        raw = leptris_parse_fragment(
+          xml, xml.bytesize, document_ptr, status)
+        [raw, status.read_int]
+      end
+
+      # The one buffer-allocation point for handle-array fetches:
+      # everything MemoryPointer-related above this line is either
+      # an attached C call or another seam helper.
+      def self.with_pointer_buffer(count)
+        buffer = ::FFI::MemoryPointer.new(:pointer, count)
+        begin
+          yield buffer
+        ensure
+          buffer.free
+        end
+      end
     end
   end
 end

data/lib/leptris/xml/node.rb

@@ -107,14 +107,12 @@ class Leptris::XML::Node
   end
 
   def children
-    # Immutable in readonly mode: the walk (first_child + one
-    # next_sibling per child) plus wrapper construction is paid once.
+    # Immutable in readonly mode: the batch fetch plus wrapper
+    # construction is paid once.
     return @children if readonly_cached?(:@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)
+    parent = as_element_or_self
+    nodes = Leptris::XML::FFI.fetch_children(@c_ptr).map do |ptr|
+      Leptris::XML::Node.wrap(ptr, @document, parent: parent)
     end
     result = Leptris::XML::NodeSet.new(@document, nodes)
     @children = result if @document&.readonly?

data/lib/leptris/xml/node_set.rb

@@ -63,30 +63,24 @@ class Leptris::XML::NodeSet
   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_ex copies every node kind, not
-      # just elements) and wrap each. Wrappers are cached per-Document
-      # via Node.wrap, so re-iteration of the same NodeSet hits it.
+      # Batch-fetch all node pointers through the FFI seam
+      # (leptris_xpath_result_get_nodes_ex copies every node kind,
+      # not just elements) and wrap each. Wrappers are cached
+      # per-Document via Node.wrap, so re-iteration of the same
+      # NodeSet hits it.
       n = length
       if n > 0
-        buf = ::FFI::MemoryPointer.new(:pointer, n)
-        begin
-          copied = Leptris::XML::FFI.leptris_xpath_result_get_nodes_ex(
-            @result_ptr, buf, nil, 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
+        pointers = Leptris::XML::FFI.fetch_result_nodes(@result_ptr, n)
+        pointers.each do |ptr|
+          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.
+        (pointers.length...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
       end
     else

data/lib/leptris/xml/pull.rb

@@ -67,22 +67,17 @@ module Leptris::XML::Pull
     def next_event
       raw = Leptris::XML::FFI.leptris_pull_next(@handle)
       return nil if raw.null?
-      type_code = raw.get_int(0)
-      type = TYPES[type_code]
-      name = read_string_at(raw, 8)
-      text_ptr = raw.get_pointer(16)
-      text = text_ptr.null? ? nil : text_ptr.read_string
+      event = Leptris::XML::FFI::PullEventStruct.new(raw)
+      type = TYPES[event[:type]]
+      name = read_owned(event[:name])
+      text = read_owned(event[:text])
       attrs = type == :start_element ? capture_attrs : nil
       Event.new(type: type, name: name, text: text, attrs: attrs)
     end
 
     private
 
-    # struct LeptrisPullEvent { int type; const char* name; const
-    # char* text; size_t text_len; } — pointer-sized fields follow the
-    # 4-byte enum on 64-bit ABIs (name at 8, text at 16).
-    def read_string_at(raw, offset)
-      ptr = raw.get_pointer(offset)
+    def read_owned(ptr)
       ptr.null? ? nil : ptr.read_string
     end
 

data/lib/leptris/xml/searchable.rb

@@ -55,20 +55,11 @@ module Leptris::XML::Searchable
 
   protected
 
-  # Builds a caller-owned namespace binding set in one FFI call
-  # (ns_set_new_from_pairs takes a flat alternating prefix/URI array,
-  # the same wire format CStringArray owns), evaluates via
-  # leptris_xpath_eval_ns, and frees the set regardless of outcome.
+  # Evaluates against a caller-owned namespace binding set; the
+  # build/teardown lifecycle lives at the FFI seam (FFI.with_ns_set).
   def xpath_eval_with_namespaces(doc_ptr, context_ptr, expr, ns)
-    flat = ns.flat_map { |prefix, uri| [prefix.to_s, uri.to_s] }
-    buffer, _anchors = Leptris::XML::CStringArray.to_c(flat)
-    set = Leptris::XML::FFI.leptris_xpath_ns_set_new_from_pairs(
-      buffer, flat.length / 2)
-    raise Leptris::XML::Error, "leptris_xpath_ns_set_new_from_pairs failed" if set.null?
-    begin
+    Leptris::XML::FFI.with_ns_set(ns) do |set|
       Leptris::XML::FFI.leptris_xpath_eval_ns(doc_ptr, context_ptr, expr, set)
-    ensure
-      Leptris::XML::FFI.leptris_xpath_ns_set_free(set)
     end
   end
 

data/lib/leptris/xml/serialization.rb

@@ -18,12 +18,9 @@ module Leptris::XML::Serialization
   end
   private_constant :DEFAULT_OPTIONS
 
-  # +ffi_function+ is a bound _serialize_into function taking
-  # (c_ptr, buf, capacity, out_len, opts): size query with buf=NULL,
-  # then one fill into a caller buffer. Since libleptris 1.9.0 the
-  # pair reuses a single serialization through a per-document cache
-  # (leptris#541) — no C-side result-string allocation, and repeated
-  # serializations of an unmutated document skip the serialize pass.
+  # +ffi_function+ is a bound _serialize_into function. The buffer
+  # cycle lives at the FFI seam (FFI.serialize_into_string); this
+  # module owns only options selection and construction.
   def self.to_xml(ffi_function, c_ptr, indent: 0, no_decl: false, encoding: nil)
     opts =
       if indent.to_i.zero? && !no_decl && encoding.nil?
@@ -33,18 +30,7 @@ module Leptris::XML::Serialization
           indent: indent, no_decl: no_decl, encoding: encoding)
         opts
       end
-    need = ffi_function.call(c_ptr, nil, 0, nil, opts.pointer)
-    return "" if need.zero?
-    buf = ::FFI::MemoryPointer.new(:char, need)
-    begin
-      ffi_function.call(c_ptr, buf, need, nil, opts.pointer)
-      # The buffer holds exactly the serialization + NUL; XML output
-      # is NUL-free, so a bounded read_string is exact. (Avoids the
-      # out_len param — no portable size_t read exists on Pointer.)
-      buf.read_string
-    ensure
-      buf.free
-    end
+    Leptris::XML::FFI.serialize_into_string(ffi_function, c_ptr, opts.pointer)
   end
 
   # +ffi_function+ is a bound FFI function taking

data/lib/leptris/xml/xpath.rb

@@ -40,16 +40,9 @@ class Leptris::XML::XPath
     document = context.document
     result_ptr =
       if ns && !ns.empty?
-        flat = ns.flat_map { |prefix, uri| [prefix.to_s, uri.to_s] }
-        buffer, _anchors = Leptris::XML::CStringArray.to_c(flat)
-        set = Leptris::XML::FFI.leptris_xpath_ns_set_new_from_pairs(
-          buffer, flat.length / 2)
-        raise Leptris::XML::Error, "leptris_xpath_ns_set_new_from_pairs failed" if set.null?
-        begin
+        Leptris::XML::FFI.with_ns_set(ns) do |set|
           Leptris::XML::FFI.leptris_xpath_compiled_eval_ns(
             @handle, document.c_ptr, context_ptr(context), set)
-        ensure
-          Leptris::XML::FFI.leptris_xpath_ns_set_free(set)
         end
       else
         Leptris::XML::FFI.leptris_xpath_compiled_eval(

metadata

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