leptris 1.9.199.0-arm-linux

data/lib/leptris/xml/sax.rb

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

data/lib/leptris/xml/schematron.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+module Leptris::XML::Schematron
+  module_function
+
+  def parse(schema_xml, phase: nil)
+    Schema.parse(schema_xml, phase: phase)
+  end
+
+  def parse_file(path, phase: nil)
+    Schema.parse_file(path, phase: phase)
+  end
+
+  # A compiled Schematron schema (libleptris >= 1.9.126): parse
+  # once — optionally selecting a PHASE, which activates only its
+  # patterns — then validate any number of documents. #validate
+  # returns the SVRL report as a queryable Document; #valid?
+  # answers the boolean.
+  #
+  #     sch = Leptris::XML::Schematron.parse(schema_xml)
+  #     sch.valid?(doc)      # => true/false
+  #     svrl = sch.validate(doc)   # => Document (svrl:schema root)
+  #     sch = Leptris::XML::Schematron.parse(schema_xml, phase: "Basic")
+  #
+  class Schema
+    class Handle < ::FFI::AutoPointer
+      def self.release(ptr)
+        Leptris::XML::FFI.leptris_schematron_free(ptr)
+      end
+    end
+
+    def self.parse(schema_xml, phase: nil)
+      xml = schema_xml.to_s
+      raw =
+        if phase
+          Leptris::XML::FFI.leptris_schematron_parse_phase(
+            xml, xml.bytesize, phase.to_s, nil)
+        else
+          Leptris::XML::FFI.leptris_schematron_parse(xml, xml.bytesize, nil)
+        end
+      if raw.null?
+        raise Leptris::XML::Error,
+          "schema parse failed: #{Leptris::XML::FFI.leptris_last_error}"
+      end
+      new(Handle.new(raw))
+    end
+
+    def self.parse_file(path, phase: nil)
+      raw =
+        if phase
+          xml = File.read(path)
+          Leptris::XML::FFI.leptris_schematron_parse_phase(
+            xml, xml.bytesize, phase.to_s, nil)
+        else
+          Leptris::XML::FFI.leptris_schematron_parse_file(path.to_s, nil)
+        end
+      if raw.null?
+        raise Leptris::XML::Error,
+          "schema parse failed: #{Leptris::XML::FFI.leptris_last_error}"
+      end
+      new(Handle.new(raw))
+    end
+
+    def initialize(handle)
+      @handle = handle
+    end
+
+    # The SVRL report as a Document (svrl:schema root — query
+    # failed-assert / successful-report elements like any other
+    # tree), or the schema-level error text.
+    def validate(document)
+      report = Leptris::XML::FFI.leptris_schematron_validate(
+        @handle, document.c_ptr)
+      if report.null?
+        Leptris::XML::FFI.leptris_schematron_error(@handle)
+      else
+        Leptris::XML::Document.wrap(report)
+      end
+    end
+
+    def valid?(document)
+      Leptris::XML::FFI.leptris_schematron_valid(
+        @handle, document.c_ptr) != 0
+    end
+  end
+end

data/lib/leptris/xml/searchable.rb

@@ -0,0 +1,361 @@
+# frozen_string_literal: true
+
+module Leptris::XML::Searchable
+  # Values that make a :version key the version channel (#183,
+  # mirroring leptris-py#105); anything else is a namespace prefix.
+  VERSION_SELECTORS = ["1.0", "3.1", :xpath10, :xpath31].freeze
+
+  # Compiled-expression cache (TODO.perf/15): the engine caches
+  # compiled strings internally, but the string path still pays
+  # lookup + hashing per call — a direct handle eval measured 34%
+  # under it on repeat expressions. Bounded LRU keyed on the
+  # expression string; only successful compiles cache; GVL makes
+  # the Hash operations safe. Version-pinned and namespace-bound
+  # evaluations keep their dedicated string entries.
+  COMPILED_CACHE_LIMIT = 64
+
+  def self.compiled_expression(expr)
+    cache = (@compiled_expressions ||= {})
+    if (hit = cache[expr])
+      cache.delete(expr)
+      cache[expr] = hit # LRU refresh
+      return hit
+    end
+    compiled = Leptris::XML::XPath.compile(expr)
+    cache.shift while cache.size >= COMPILED_CACHE_LIMIT
+    cache[expr] = compiled
+    compiled
+  rescue Leptris::XML::XPathError
+    nil # fall back to the string path — its error surface is the contract
+  end
+
+  # CSS translation cache (TODO.perf/20): the selector -> XPath
+  # translation is a pure function of (selector, prefix); without
+  # it every css call re-ran the regex machinery before the
+  # compiled-expression cache could hit. Same bounded-LRU shape.
+  def self.css_expression(selector, prefix)
+    cache = (@css_expressions ||= {})
+    key = "#{prefix}#{selector}"
+    if (hit = cache[key])
+      cache.delete(key)
+      cache[key] = hit # LRU refresh
+      return hit
+    end
+    expr = Leptris::XML::CssToXPath.convert(selector, prefix: prefix)
+    cache.shift while cache.size >= COMPILED_CACHE_LIMIT
+    cache[key] = expr
+    expr
+  end
+
+  def xpath(*paths)
+    handler, ns, version = parse_search_args(paths)
+    raise ArgumentError, "custom XPath handlers not supported" if handler
+    # Single-String shape (the common call): join would mint a
+    # fresh String per call even for one path.
+    expr = paths.one? && paths.first.is_a?(String) ? paths.first
+                                                    : paths.join(" | ")
+
+    # TODO.perf/37: the document's Pointer is lazy (materializes
+    # once per document lifetime, not per parse); the ffi gem
+    # does NOT convert Integers for typedef'd pointer params, so
+    # the Pointer object is still what crosses here.
+    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 version
+        if ns && !ns.empty?
+          raise ArgumentError,
+            "version: cannot be combined with namespace bindings " \
+            "(the versioned engine entry takes no ns set yet)"
+        end
+        Leptris::XML::FFI.leptris_xpath_eval_versioned(
+          doc_ptr, context_ptr, expr,
+          Leptris::XML::Searchable.xpath_version_code(version), nil)
+      elsif ns && !ns.empty?
+        # TODO.perf/29: the compiled handle is ns-independent —
+        # ride the cache and the cached ns set instead of the
+        # engine's string parse per call.
+        if (compiled = Leptris::XML::Searchable.compiled_expression(expr))
+          Leptris::XML::FFI.with_ns_set(ns) do |set|
+            compiled.eval_ns_ptrs(doc_ptr, context_ptr, set)
+          end
+        else
+          xpath_eval_with_namespaces(doc_ptr, context_ptr, expr, ns)
+        end
+      elsif (compiled = Leptris::XML::Searchable.compiled_expression(expr))
+        compiled.eval_ptrs(doc_ptr, context_ptr)
+      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_result(document, result_ptr)
+  end
+
+  def at_xpath(*paths)
+    handler, ns, version = parse_search_args(paths)
+    raise ArgumentError, "custom XPath handlers not supported" if handler
+    # Single-String shape (the common call): join would mint a
+    # fresh String per call even for one path.
+    expr = paths.one? && paths.first.is_a?(String) ? paths.first
+                                                    : paths.join(" | ")
+
+    # TODO.perf/37: the document's Pointer is lazy (materializes
+    # once per document lifetime, not per parse); the ffi gem
+    # does NOT convert Integers for typedef'd pointer params, so
+    # the Pointer object is still what crosses here.
+    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 version
+        if ns && !ns.empty?
+          raise ArgumentError,
+            "version: cannot be combined with namespace bindings " \
+            "(the versioned engine entry takes no ns set yet)"
+        end
+        Leptris::XML::FFI.leptris_xpath_eval_versioned(
+          doc_ptr, context_ptr, expr,
+          Leptris::XML::Searchable.xpath_version_code(version), nil)
+      elsif ns && !ns.empty?
+        # TODO.perf/29: the compiled handle is ns-independent —
+        # ride the cache and the cached ns set instead of the
+        # engine's string parse per call.
+        if (compiled = Leptris::XML::Searchable.compiled_expression(expr))
+          Leptris::XML::FFI.with_ns_set(ns) do |set|
+            compiled.eval_ns_ptrs(doc_ptr, context_ptr, set)
+          end
+        else
+          xpath_eval_with_namespaces(doc_ptr, context_ptr, expr, ns)
+        end
+      elsif (compiled = Leptris::XML::Searchable.compiled_expression(expr))
+        compiled.eval_ptrs(doc_ptr, context_ptr)
+      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)
+    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
+
+  # Single-node seam (round XIV): dispatch on syntax like #search,
+  # then call the at_* fast paths directly — no NodeSet container,
+  # no result handle, one fewer dispatch than search().first.
+  def at(*args)
+    paths = args.first.is_a?(Array) ? args.first : [args.first]
+    if paths.map(&:to_s).all? { |p| looks_like_xpath?(p) }
+      at_xpath(*paths)
+    else
+      at_css(*args)
+    end
+  end
+  alias_method :%, :at
+
+  def css(*args)
+    handler, ns, version = parse_search_args(args)
+    raise ArgumentError, "namespace bindings not supported in css" if ns && !ns.empty?
+    raise ArgumentError, "version: is XPath-only" if version
+    raise ArgumentError, "custom CSS handlers not supported" if handler
+    # Nokogiri semantics: css is receiver-relative — absolute "//"
+    # from a Document, descendant ".//" from elements and fragments.
+    prefix = is_a?(Leptris::XML::Document) ? "//" : ".//"
+    expr = args.map { |r| Leptris::XML::Searchable.css_expression(r, prefix) }
+      .join(" | ")
+    xpath(expr)
+  end
+
+  def at_css(*args)
+    handler, ns, version = parse_search_args(args)
+    raise ArgumentError, "namespace bindings not supported in css" if ns && !ns.empty?
+    raise ArgumentError, "version: is XPath-only" if version
+    raise ArgumentError, "custom CSS handlers not supported" if handler
+    prefix = is_a?(Leptris::XML::Document) ? "//" : ".//"
+    expr = args.map { |r| Leptris::XML::Searchable.css_expression(r, prefix) }
+      .join(" | ")
+    at_xpath(expr)
+  end
+
+  # Version-pinned evaluation (libleptris lane 15,
+  # leptris_xpath_eval_versioned): :xpath10 keeps the strict XPath
+  # 1.0 surface — 3.x syntax (arrow, bang, lookup, let, inline
+  # functions, string templates) raises; :xpath31 evaluates the
+  # full grammar (identical to #xpath's default entry). A separate
+  # method by design: #xpath's trailing-hash argument is the
+  # namespace-binding channel, and a declared keyword would
+  # capture it.
+  def xpath_versioned(expression, version)
+    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_versioned(
+      doc_ptr, context_ptr, expression,
+      Leptris::XML::Searchable.xpath_version_code(version), nil)
+    if result_ptr.null?
+      raise Leptris::XML::XPathError,
+        Leptris::XML::FFI.leptris_last_error.to_s
+    end
+    Leptris::XML::Searchable.wrap_xpath_result(document, result_ptr)
+  end
+
+  protected
+
+  # 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)
+    Leptris::XML::FFI.with_ns_set(ns) do |set|
+      Leptris::XML::FFI.leptris_xpath_eval_ns(doc_ptr, context_ptr, expr, set)
+    end
+  end
+
+
+  # Version pin for xpath_versioned: :xpath10
+  # keeps the strict XPath 1.0 surface (3.x syntax — arrow, bang,
+  # lookup, let, inline functions — raises); :xpath31 evaluates the
+  # full grammar (identical to the default entry).
+  def self.xpath_version_code(version)
+    case version
+    when :xpath10, "1.0" then Leptris::XML::FFI::XPATH_10
+    when :xpath31, "3.1" then Leptris::XML::FFI::XPATH_31
+    else
+      raise ArgumentError,
+        "version must be :xpath10 or :xpath31, got #{version.inspect}"
+    end
+  end
+
+  # Trailing-argument contract (#183): a String-keyed hash is the
+  # namespace-binding channel — as is a Symbol-keyed hash (the
+  # legacy prefix vocabulary, {x: "urn:x"}); a :version key whose
+  # VALUE is a version selector is the version-selection channel
+  # (xpath("//b", version: "1.0"), mirroring leptris-py#105). A
+  # DECLARED keyword cannot carry this: the moment #xpath declares
+  # one, Ruby converts the trailing namespace hash into keywords
+  # (unknown keyword: "p") — so both channels stay positional and
+  # dispatch on key/value here.
+  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
+    unless vars.nil? || vars.empty?
+      raise ArgumentError, "XPath variable bindings are not supported"
+    end
+    # Value-based disambiguation is load-bearing: Symbol keys are
+    # also the namespace vocabulary, and bare keywords FUSE into a
+    # preceding String-keyed hash at the call site ({"p" => uri,
+    # version: "1.0"} arrives as ONE hash). A :version key with any
+    # other value stays a prefix binding.
+    version = nil
+    if ns.is_a?(Hash)
+      v = ns[:version]
+      if VERSION_SELECTORS.include?(v)
+        version = ns.delete(:version)
+        ns = nil if ns.empty?
+      elsif v.is_a?(String) && v.match?(/\A\d+\.\d+\z/)
+        # A dotted-number :version value is version INTENT — raise
+        # with the valid values rather than silently binding a
+        # prefix literally. Genuine prefix bindings carry URIs.
+        raise ArgumentError,
+          "unknown XPath version #{v.inspect} " \
+          "(valid: \"1.0\"/:xpath10, \"3.1\"/:xpath31)"
+      end
+    end
+    [handler, ns, version]
+  end
+
+  def looks_like_xpath?(str)
+    %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)
+    # C seam (TODO.perf/16): nodesets materialize entry 0, free
+    # the handle, and return in one dispatch. The module object
+    # back means non-nodeset — the scalar path below owns it.
+    if defined?(Leptris::XML::NATIVE_FAST)
+      first = Leptris::XML::Native.at_xpath_first(
+        document, result_ptr.address)
+      return first unless first.equal?(Leptris::XML::Native)
+    end
+    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)
+      if ptr.null?
+        node = nil
+      else
+        kind = Leptris::XML::FFI.leptris_xpath_result_node_kind(result_ptr, 0)
+        node = if kind == Leptris::XML::FFI::XPATH_NODE_ATTRIBUTE
+                 Leptris::XML::ResultAttr.new(
+                   ptr, document,
+                   Leptris::XML::FFI.leptris_xpath_result_node_name(result_ptr, 0),
+                   Leptris::XML::FFI.leptris_xpath_result_node_value(result_ptr, 0))
+               else
+                 Leptris::XML::Node.wrap(ptr, document)
+               end
+      end
+      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.
+  def self.wrap_xpath_result(document, result_ptr)
+    type = Leptris::XML::FFI.leptris_xpath_result_type(result_ptr)
+    case type
+    when Leptris::XML::FFI::XPATH_NODESET
+      # TODO.perf/22: materialize AND free in C — no Ruby
+      # AutoPointer + finalizer per xpath call. Qnil means an
+      # exotic kind needs the Ruby fallback per entry; the lazy
+      # path below keeps the handle.
+      if defined?(Leptris::XML::NATIVE_FAST)
+        nodes = Leptris::XML::Native.materialize_xpath(
+          document, result_ptr.address)
+        return Leptris::XML::NodeSet.new(document, nodes) if nodes
+      end
+      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)
+      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
+    when Leptris::XML::FFI::XPATH_FUNCTION
+      Leptris::XML::FFI.leptris_xpath_result_free(result_ptr)
+      raise Leptris::XML::XPathError,
+            'XPath function items cannot cross the FFI boundary yet ' \
+            '(libleptris TODO 07; call them inside the expression, ' \
+            'e.g. for-each((1,2), function($n){$n+1}))'
+    else
+      Leptris::XML::FFI.leptris_xpath_result_free(result_ptr)
+      raise Leptris::XML::XPathError, "unknown xpath result type #{type}"
+    end
+  end
+end

data/lib/leptris/xml/serialization.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+# Owns the SerializeOptions lifecycle and the owned-string read for
+# document and subtree serialization/canonicalization. Document and
+# Element expose one-line methods over this module — the options
+# struct, the encoding anchor, the C call, and the read-and-free all
+# live here.
+module Leptris::XML::Serialization
+  # The default options struct (indent 0, declaration on, no encoding
+  # override) is constant: build it once and reuse its pointer on the
+  # fast path instead of allocating a fresh struct per call.
+  DEFAULT_OPTIONS, _default_anchor = begin
+    opts = Leptris::XML::FFI::SerializeOptions.new
+    opts[:indent] = 0
+    opts[:xml_declaration] = 1
+    opts[:encoding] = nil
+    [opts, nil]
+  end
+  private_constant :DEFAULT_OPTIONS
+
+  # Bound serializer entries, hoisted: Element#to_xml and the
+  # inner_html per-child loop passed FFI.method(:...) — one Method
+  # allocation per serialized child.
+  ELEMENT_SERIALIZE_INTO =
+    Leptris::XML::FFI.method(:leptris_element_serialize_into)
+  DOCUMENT_SERIALIZE_INTO =
+    Leptris::XML::FFI.method(:leptris_document_serialize_into)
+  # Public within the library: Element#to_xml and Document#to_xml
+  # pass the hoisted bound methods straight through.
+
+  # +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)
+    # TODO.perf/04+36: the whole sized-buffer cycle in the ext —
+    # one C dispatch, no options marshaling, no Ruby buffer
+    # management; encoding rides the face (nil -> no override).
+    if defined?(Leptris::XML::NATIVE_FAST)
+      decl = !no_decl
+      return Leptris::XML::Native.fast_element_xml(
+        c_ptr.address, indent.to_i, decl, encoding) if
+        ffi_function == ELEMENT_SERIALIZE_INTO
+      return Leptris::XML::Native.fast_document_xml(
+        c_ptr.address, indent.to_i, decl, encoding) if
+        ffi_function == DOCUMENT_SERIALIZE_INTO
+    end
+    opts =
+      if indent.to_i.zero? && !no_decl && encoding.nil?
+        DEFAULT_OPTIONS
+      else
+        opts, _encoding_anchor = build_options(
+          indent: indent, no_decl: no_decl, encoding: encoding)
+        opts
+      end
+    Leptris::XML::FFI.serialize_into_string(ffi_function, c_ptr, opts.pointer)
+  end
+
+  # Default-options element serialization for inner_html's per-child
+  # loop: no kwargs, no options rebuild, no method allocation —
+  # one FFI fast-path dispatch per child.
+  def self.element_xml_default(c_ptr)
+    return Leptris::XML::Native.fast_element_xml(c_ptr.address, 0, true,
+                                                  nil) if
+      defined?(Leptris::XML::NATIVE_FAST)
+    Leptris::XML::FFI.serialize_into_string(
+      ELEMENT_SERIALIZE_INTO, c_ptr, DEFAULT_OPTIONS.pointer)
+  end
+
+  # Element serialization with expand_empty (libleptris 1.9.95,
+  # #882): empty elements emit <a></a> instead of <a/> — the
+  # inverse of libxml2's XML_SAVE_NO_EMPTY, through the element
+  # ext entry (the sized form keeps older ext allocations safe).
+  EXPAND_EMPTY_EXT = begin
+    ext = Leptris::XML::FFI::SerializeExtStruct.new
+    ext[:indent_text] = 0
+    ext[:indent_unit] = nil
+    ext[:expand_empty] = 1
+    ext
+  end
+  private_constant :EXPAND_EMPTY_EXT
+
+  def self.element_xml_expand_empty(c_ptr)
+    str_ptr = Leptris::XML::FFI.leptris_element_serialize_ext_sized(
+      c_ptr, DEFAULT_OPTIONS.pointer,
+      EXPAND_EMPTY_EXT.pointer, EXPAND_EMPTY_EXT.size)
+    Leptris::XML::FFI.read_owned_string(str_ptr)
+  end
+
+  # Display-form document serialization (libleptris 1.9.9, #129):
+  # the ext struct's indent_text hands ALL whitespace to the
+  # formatter — text and mixed content indent too. Display-oriented:
+  # the output is NOT guaranteed to round-trip byte-exactly.
+  INDENT_TEXT_EXT = begin
+    ext = Leptris::XML::FFI::SerializeExtStruct.new
+    ext[:indent_text] = 1
+    ext
+  end
+  private_constant :INDENT_TEXT_EXT
+
+  def self.to_xml_display(c_ptr, indent: 0, no_decl: false, encoding: nil)
+    opts, encoding_anchor = build_options(
+      indent: indent, no_decl: no_decl, encoding: encoding)
+    str_ptr = Leptris::XML::FFI.leptris_document_serialize_ext_sized(
+      c_ptr, opts.pointer, INDENT_TEXT_EXT.pointer, INDENT_TEXT_EXT.size)
+    Leptris::XML::FFI.read_owned_string(str_ptr)
+  end
+
+  # Indent-unit serialization (libleptris 1.9.22, #633 —
+  # leptris-ruby#109): Nokogiri's indent_text semantics — the unit
+  # string replaces the default spaces, repeated `indent` times per
+  # depth level, standard layout otherwise. The engine emits ONE
+  # copy of the unit string per level (options->indent is ignored
+  # when a unit is set), so the binding multiplies unit x indent to
+  # reach Nokogiri's repeat count.
+  def self.to_xml_indent_unit(c_ptr, unit, indent: 0, no_decl: false,
+                              encoding: nil)
+    opts, encoding_anchor = build_options(
+      indent: indent, no_decl: no_decl, encoding: encoding)
+    ext = Leptris::XML::FFI::SerializeExtStruct.new
+    unit_anchor = ::FFI::MemoryPointer.from_string(
+      indent.positive? ? unit.to_s * indent : unit.to_s)
+    ext[:indent_unit] = unit_anchor
+    str_ptr = Leptris::XML::FFI.leptris_document_serialize_ext_sized(
+      c_ptr, opts.pointer, ext.pointer, ext.size)
+    Leptris::XML::FFI.read_owned_string(str_ptr)
+  end
+
+  # +ffi_function+ is a bound FFI function taking
+  # (c_ptr, version, mode, ns_ptr, flags): leptris_c14n_canonicalize_ex
+  # or leptris_c14n_canonicalize_subtree_ex.
+  def self.canonicalize(ffi_function, c_ptr, version:, mode:,
+                        inclusive_namespaces: nil, with_comments: false)
+    ns_ptr, _ns_anchor = Leptris::XML::CStringArray.to_c(inclusive_namespaces)
+    str_ptr = ffi_function.call(c_ptr, version, mode, ns_ptr, with_comments ? 1 : 0)
+    Leptris::XML::FFI.read_owned_string(str_ptr)
+  end
+
+  # XML-escapes text content for inner_html: & first, then < >
+  # and CR (libxml2 emits &#xD; for a bare carriage return).
+  ESCAPE_TEXT = {
+    "&" => "&amp;", "<" => "&lt;", ">" => "&gt;", "\r" => "&#xD;",
+  }.freeze
+  private_constant :ESCAPE_TEXT
+  ESCAPE_TEXT_RE = /[&<>\r]/.freeze
+  private_constant :ESCAPE_TEXT_RE
+
+  def self.escape_text(string)
+    string.gsub(ESCAPE_TEXT_RE, ESCAPE_TEXT)
+  end
+
+  # Element-face indent unit (leptris-ruby#109 residual 2): no
+  # element-level ext-serialize entry exists yet, so the unit path
+  # copies the subtree into a fresh document via Document.copy_of
+  # (the single copy seam) and serializes that document without a
+  # declaration — identical output to the element serializer for
+  # the standard layout, with the unit and every child kind intact.
+  def self.to_xml_element_unit(element, unit, indent: 0)
+    document = Leptris::XML::Document.copy_of(element).document
+    begin
+      to_xml_indent_unit(document.c_ptr, unit,
+                         indent: indent, no_decl: true)
+    ensure
+      document.free
+    end
+  end
+
+  # Builds a SerializeOptions struct. Returns [opts, encoding_anchor];
+  # the anchor must stay referenced while opts is in an FFI call.
+  def self.build_options(indent: 0, no_decl: false, encoding: nil)
+    opts = Leptris::XML::FFI::SerializeOptions.new
+    opts[:indent] = indent.to_i
+    opts[:xml_declaration] = no_decl ? 0 : 1
+    encoding_anchor = nil
+    if encoding
+      encoding_anchor = ::FFI::MemoryPointer.from_string(encoding.to_s)
+      opts[:encoding] = encoding_anchor
+    end
+    [opts, encoding_anchor]
+  end
+end

data/lib/leptris/xml/text.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+class Leptris::XML::Text < Leptris::XML::Node
+  def name; "text"; end
+
+  def content
+    return @content if memo_hit?(@content_version)
+    ensure_alive!
+    result = if @addr_reads_fast
+               Leptris::XML::Native.fast_text_content(@c_address)
+             else
+               Leptris::XML::FFI.leptris_text_node_get_content(c_ptr)
+             end
+    if @document
+      @content = result
+      @content_version = @document.version
+    end
+    result
+  end
+
+  def content=(new_content)
+    if @native_fast
+      Leptris::XML::Native.set_binding_text(
+        @document, @c_address, new_content.to_s)
+      return new_content
+    end
+    ensure_writable!
+    Leptris::XML::FFI.check_status(
+      Leptris::XML::FFI.leptris_text_node_set_content(c_ptr, new_content.to_s))
+    new_content
+  end
+end