leptris 1.9.1 → 1.9.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed2f1d5755923f389734df36cc9c40c513535e58e7abe5a40aa87dd93f858788
-  data.tar.gz: eb4e9c9c3b12a7584572746053c9aaf318ee5481fa002909d8502d5565bcf543
+  metadata.gz: c3e961e97c5ce359508474f70efda320521debdd4eb5e851241a82a49ffe7512
+  data.tar.gz: 8fd855b22026aacac080e734658e115826b45e59dcbfee6bb01a0e2b024a8cd1
 SHA512:
-  metadata.gz: 35a1a34584014746679c39098f60c6009871007e3e5016562b669437e6f00d84412c7a26f286034f628421f72846c810b1b3568faacbbae86fa3e6c47b6db20f
-  data.tar.gz: 5e4785ee975db46c2f7798a4effd7c3d2be729e94ded98db78e3cdd830891b0704170e104d9b2287ff1e4e8a98833917a70a7ec4d5591615931020cf67f18e54
+  metadata.gz: b1e58c09914cc12d9541410e1e5e46ff1c7135646bed22a46c6f796e41444ebdb0d039d1eabc1a5dc6790c6bcf2c3e1e31ae8fa6d8a33e25005138c5c0889fef
+  data.tar.gz: 42acbecab9c56654468540fa1cf7cda8dd666023a0d40b8f298ef2e18691d50e1e577393a0fb8bee36db27b743cdddf349db745e3b9c1bbb817d0a8681687a78

data/CHANGELOG.md

@@ -5,6 +5,60 @@ 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.3] - 2026-08-25
+
+### Fixed
+
+- **UTF-8 at the FFI seam**: every string crossing the C boundary
+  (names, content, attribute values, paths, pull attributes, PI
+  data, error strings) now arrives as UTF-8 per the headers'
+  contract, instead of FFI's default ASCII-8BIT. Downstream string
+  comparisons, hash keys, and regexes stop paying compatibility
+  checks — and non-ASCII content can no longer raise
+  Encoding::CompatibilityError in consumer code.
+
+### Changed
+
+- **Readonly read-path cache completed**: `namespace`,
+  `namespace_definitions`, `namespaces`, `keys`, `values`,
+  `attribute_nodes`, `element_children`, `path`, `css_path`,
+  Text/Comment/CDATA/PI `content` (and PI `name`), and
+  `Document#processing_instructions` now memoize under readonly —
+  the same cannot-go-stale invariant the first four readers already
+  had. Measured steady-state wins (readonly documents, 400-iteration
+  loops): namespace inspection 13.5× faster, attribute listing 3.2×,
+  text content 2×.
+- **CSS translation cache**: `CssToXPath.convert` memoizes per
+  selector string (failures raise before caching); repeated
+  `css`/`at_css` vocabularies skip the regex cascade (~28% on the
+  selector loop benchmark).
+- `Attr#to_xml` escapes the five XML entities in one gsub pass
+  instead of five chained passes; `Attr#prefix` slices instead of
+  split-and-discard.
+
+## [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.3"
 end

data/lib/leptris/xml/attr.rb

@@ -28,7 +28,8 @@ class Leptris::XML::Attr
   # immutable — the same semantics as leptris_attribute_prefix, so
   # no declaration lookup is involved.
   def prefix
-    @name.include?(":") ? @name.split(":", 2).first : nil
+    i = @name.index(":")
+    i ? @name[0, i] : nil
   end
 
   # The attribute's namespace URI, resolved through the OWNING
@@ -52,14 +53,15 @@ class Leptris::XML::Attr
   def to_str; @value; end
 
   # Serialized attribute form: name="value" with the five XML special
-  # characters escaped in the value.
+  # characters escaped in the value — single pass, no chained gsubs.
+  ESCAPE_TABLE = {
+    "&" => "&amp;", "<" => "&lt;", ">" => "&gt;",
+    '"' => "&quot;", "'" => "&apos;",
+  }.freeze
+  private_constant :ESCAPE_TABLE
+
   def to_xml
-    escaped = @value.to_s.gsub("&", "&amp;")
-                       .gsub("<", "&lt;")
-                       .gsub(">", "&gt;")
-                       .gsub('"', "&quot;")
-                       .gsub("'", "&apos;")
-    "#{@name}=\"#{escaped}\""
+    "#{@name}=\"#{@value.to_s.gsub(/[&<>"']/, ESCAPE_TABLE)}\""
   end
 
   def ==(other)

data/lib/leptris/xml/c_string_array.rb

@@ -29,7 +29,7 @@ module Leptris::XML::CStringArray
     result = []
     offset = 0
     while (entry = ptr.get_pointer(offset)) && !entry.null?
-      result << entry.read_string
+      result << entry.read_string.force_encoding(Encoding::UTF_8)
       offset += ptr_size
     end
     result

data/lib/leptris/xml/cdata.rb

@@ -4,7 +4,10 @@ class Leptris::XML::CDATA < Leptris::XML::Text
   def name; "#cdata-section"; end
 
   def content
-    Leptris::XML::FFI.leptris_cdata_node_get_content(@c_ptr)
+    return @content if readonly_cached?(:@content)
+    Leptris::XML::FFI.leptris_cdata_node_get_content(@c_ptr).tap do |text|
+      @content = text if @document&.readonly?
+    end
   end
 
   def content=(new_content)

data/lib/leptris/xml/comment.rb

@@ -4,7 +4,10 @@ class Leptris::XML::Comment < Leptris::XML::Node
   def name; "comment"; end
 
   def content
-    Leptris::XML::FFI.leptris_comment_node_get_content(@c_ptr)
+    return @content if readonly_cached?(:@content)
+    Leptris::XML::FFI.leptris_comment_node_get_content(@c_ptr).tap do |text|
+      @content = text if @document&.readonly?
+    end
   end
 
   def content=(new_content)

data/lib/leptris/xml/css_to_xpath.rb

@@ -35,8 +35,19 @@ module Leptris
 
       module_function
 
+      # Translation is a pure function of the rule string, and real
+      # workloads repeat a small selector vocabulary in loops —
+      # memoize. Failed translations raise before caching.
+      CACHE = {}
+      private_constant :CACHE
+
       def convert(rule)
-        rule.to_s.split(COMMA_SPLIT).map { |r| convert_one(r.strip) }.join(" | ")
+        key = rule.to_s
+        CACHE.fetch(key) { CACHE[key] = convert_rule(key) }
+      end
+
+      def convert_rule(rule)
+        rule.split(COMMA_SPLIT).map { |r| convert_one(r.strip) }.join(" | ")
       end
 
       def convert_one(rule)

data/lib/leptris/xml/document.rb

@@ -247,11 +247,16 @@ class Leptris::XML::Document
   # Document-level processing instructions (not tree nodes):
   # an array of [target, data] pairs in document order.
   def processing_instructions
+    if readonly? && instance_variable_defined?(:@processing_instructions)
+      return @processing_instructions
+    end
     count = Leptris::XML::FFI.leptris_document_pi_count(@c_ptr)
-    count.times.map do |i|
+    result = count.times.map do |i|
       [Leptris::XML::FFI.leptris_document_pi_target(@c_ptr, i),
        Leptris::XML::FFI.leptris_document_pi_data(@c_ptr, i)]
     end
+    @processing_instructions = result if readonly?
+    result
   end
 
   # Append a document-level processing instruction. Returns self.

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/element.rb

@@ -88,11 +88,17 @@ class Leptris::XML::Element < Leptris::XML::Node
   end
 
   def keys
-    each_attribute.to_a.map(&:name)
+    return @keys if readonly_cached?(:@keys)
+    result = each_attribute.to_a.map(&:name)
+    @keys = result if @document&.readonly?
+    result
   end
 
   def values
-    each_attribute.to_a.map(&:value)
+    return @values if readonly_cached?(:@values)
+    result = each_attribute.to_a.map(&:value)
+    @values = result if @document&.readonly?
+    result
   end
 
   def attributes
@@ -104,7 +110,10 @@ class Leptris::XML::Element < Leptris::XML::Node
   end
 
   def attribute_nodes
-    each_attribute.to_a
+    return @attribute_nodes if readonly_cached?(:@attribute_nodes)
+    result = each_attribute.to_a
+    @attribute_nodes = result if @document&.readonly?
+    result
   end
 
   # The element's own namespace prefix (e.g. "foo" for <foo:child/>),
@@ -221,26 +230,37 @@ class Leptris::XML::Element < Leptris::XML::Node
   alias_method :<<, :add_child
 
   def namespace
+    return @namespace if readonly_cached?(:@namespace)
     uri = Leptris::XML::FFI.leptris_element_namespace(@c_ptr)
-    return nil if uri.nil? || uri.empty?
-    # The resolved namespace is reached via this element's own prefix,
-    # so carry it through: consumers that distinguish
-    # {"p" => "urn:p"} from the default {"nil => "urn:p"} need it.
-    prefix = Leptris::XML::FFI.leptris_element_prefix(@c_ptr)
-    prefix = nil if prefix.nil? || prefix.empty?
-    Leptris::XML::Namespace.new(self, uri, prefix: prefix)
+    result =
+      if uri.nil? || uri.empty?
+        nil
+      else
+        # The resolved namespace is reached via this element's own
+        # prefix, so carry it through: consumers that distinguish
+        # {"p" => "urn:p"} from the default {"nil => "urn:p"} need it.
+        prefix = Leptris::XML::FFI.leptris_element_prefix(@c_ptr)
+        prefix = nil if prefix.nil? || prefix.empty?
+        Leptris::XML::Namespace.new(self, uri, prefix: prefix)
+      end
+    @namespace = result if @document&.readonly?
+    result
   end
 
   def namespace_definitions
+    return @namespace_definitions if readonly_cached?(:@namespace_definitions)
     count = Leptris::XML::FFI.leptris_element_namespace_count(@c_ptr)
-    count.times.map do |i|
+    result = count.times.map do |i|
       prefix = Leptris::XML::FFI.leptris_element_namespace_decl_prefix(@c_ptr, i)
       uri = Leptris::XML::FFI.leptris_element_namespace_decl_uri(@c_ptr, i)
       Leptris::XML::Namespace.new(self, uri, prefix: prefix)
     end
+    @namespace_definitions = result if @document&.readonly?
+    result
   end
 
   def namespaces
+    return @namespaces if readonly_cached?(:@namespaces)
     scopes = {}
     node = self
     while node.is_a?(Leptris::XML::Element)
@@ -250,6 +270,7 @@ class Leptris::XML::Element < Leptris::XML::Node
       end
       node = node.parent
     end
+    @namespaces = scopes if @document&.readonly?
     scopes
   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,
@@ -600,11 +615,45 @@ module Leptris
       LEPTRIS_PARSE_DEFAULT = 0
       LEPTRIS_PARSE_DROP_WS_TEXT = 1
 
+      # The headers' contract is UTF-8 for every C string, but FFI's
+      # read_string hands back ASCII-8BIT — the platform default
+      # leaks through the seam. Every string-returning attached
+      # function this binding CALLS is wrapped here so its result
+      # arrives as UTF-8; mirror-only attachments stay raw (add the
+      # name here when a call site starts using its string).
+      UTF8_RETURNS = %i[
+        leptris_version
+        leptris_status_string leptris_last_error
+        leptris_document_last_error leptris_document_encoding
+        leptris_document_pi_target leptris_document_pi_data
+        leptris_element_name leptris_element_text leptris_element_prefix
+        leptris_element_namespace
+        leptris_element_attribute leptris_element_attribute_ns
+        leptris_attribute_get_name leptris_attribute_get_value
+        leptris_attribute_namespace_uri
+        leptris_element_namespace_decl_prefix
+        leptris_element_namespace_decl_uri
+        leptris_text_node_get_content leptris_comment_node_get_content
+        leptris_cdata_node_get_content
+        leptris_pi_node_get_target leptris_pi_node_get_data
+        leptris_pull_attr_name leptris_pull_attr_value
+      ].freeze
+      private_constant :UTF8_RETURNS
+
+      UTF8_RETURNS.each do |name|
+        raw = method(name)
+        define_singleton_method(name) do |*args|
+          str = raw.call(*args)
+          str.nil? ? nil : str.force_encoding(Encoding::UTF_8)
+        end
+      end
+
       # Reads an libleptris-owned char* result and frees it as one unit,
       # so a call site can neither leak nor double-free.
       def self.read_owned_string(ptr)
         return "" if ptr.nil? || ptr.null?
         ptr.read_string.tap { leptris_free_string(ptr) }
+          .force_encoding(Encoding::UTF_8)
       end
 
       # Single status seam: turns a C status code into a Ruby error,
@@ -623,6 +672,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?
@@ -150,7 +148,10 @@ class Leptris::XML::Node
   end
 
   def element_children
-    children.select(&:element?)
+    return @element_children if readonly_cached?(:@element_children)
+    result = children.select(&:element?)
+    @element_children = result if @document&.readonly?
+    result
   end
   alias_method :elements, :element_children
 
@@ -197,17 +198,26 @@ class Leptris::XML::Node
   end
 
   def path
+    return @path if readonly_cached?(:@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)
+    result = str_ptr.null? ? nil : Leptris::XML::FFI.read_owned_string(str_ptr)
+    @path = result if @document&.readonly?
+    result
   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(" > ")
+    return @css_path if readonly_cached?(:@css_path)
+    result =
+      if path.nil?
+        nil
+      else
+        path.split("/").filter_map do |part|
+          next nil if part.empty?
+          part.gsub(/\[(\d+)\]/, ':nth-of-type(\1)')
+        end.join(" > ")
+      end
+    @css_path = result if @document&.readonly?
+    result
   end
 
   def dup

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/processing_instruction.rb

@@ -2,12 +2,18 @@
 
 class Leptris::XML::ProcessingInstruction < Leptris::XML::Node
   def name
-    Leptris::XML::FFI.leptris_pi_node_get_target(@c_ptr)
+    return @name if readonly_cached?(:@name)
+    Leptris::XML::FFI.leptris_pi_node_get_target(@c_ptr).tap do |target|
+      @name = target if @document&.readonly?
+    end
   end
   alias_method :target, :name
 
   def content
-    Leptris::XML::FFI.leptris_pi_node_get_data(@c_ptr).to_s
+    return @content if readonly_cached?(:@content)
+    Leptris::XML::FFI.leptris_pi_node_get_data(@c_ptr).to_s.tap do |data|
+      @content = data if @document&.readonly?
+    end
   end
 
   def target=(new_target)

data/lib/leptris/xml/pull.rb

@@ -67,23 +67,18 @@ 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)
-      ptr.null? ? nil : ptr.read_string
+    def read_owned(ptr)
+      ptr.null? ? nil : ptr.read_string.force_encoding(Encoding::UTF_8)
     end
 
     def capture_attrs

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/text.rb

@@ -4,7 +4,10 @@ class Leptris::XML::Text < Leptris::XML::Node
   def name; "text"; end
 
   def content
-    Leptris::XML::FFI.leptris_text_node_get_content(@c_ptr)
+    return @content if readonly_cached?(:@content)
+    Leptris::XML::FFI.leptris_text_node_get_content(@c_ptr).tap do |text|
+      @content = text if @document&.readonly?
+    end
   end
 
   def content=(new_content)

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.3
 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