leptris 1.9.197.2-arm-linux

data/lib/leptris/xml/iteration_scope.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+# The owning context for elements yielded by an Iterparse run —
+# the lifetime and memoization authority that a Document is for
+# parsed trees, scoped to one iteration:
+#
+# - `#c_ptr` carries the iterator handle and goes nil on `#free` —
+#   the same signal `Node#ensure_alive!` reads, so using a held
+#   element after the iterator frees RAISES UseAfterFreeError
+#   instead of segfaulting (ruby#152).
+# - `#wrapper_cache` gives wrapper identity within a yielded
+#   subtree (children() twice returns the same wrappers).
+# - `#version` advances per yield and on mutation — stale memos on
+#   held wrappers invalidate as subtrees are released.
+#
+# `Node#document` answers nil for scope-owned elements (the
+# documented iterparse contract) while the internal machinery
+# engages — including the fast bare-name attribute path, which is
+# what makes iterparse attribute reads match document-backed cost.
+class Leptris::XML::IterationScope
+  def initialize(iterator_handle)
+    @c_ptr = iterator_handle
+    @wrapper_cache = {}
+    @version = 0
+  end
+
+  attr_reader :c_ptr, :wrapper_cache
+
+  def version
+    @version
+  end
+
+  def advance_version
+    @version += 1
+  end
+
+  def readonly?
+    false
+  end
+
+  # Called by the owning Iterparse when it frees the C iterator —
+  # every wrapper it handed out fails liveness from here on.
+  def mark_freed
+    @c_ptr = nil
+  end
+
+  # Called before each yield: the previous subtree is released and
+  # its pool memory recycled — a fresh element may land at a cached
+  # address, so the identity cache and the memo version both reset.
+  def new_subtree!
+    @wrapper_cache = {}
+    @version += 1
+  end
+end

data/lib/leptris/xml/iterparse.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+# Incremental tree iteration (libleptris v1.6.0): yields each
+# completed TOP-LEVEL child element of the document root as it
+# parses. The previous element's whole subtree is released when the
+# next is produced — memory stays bounded by the largest subtree,
+# not the document.
+#
+#     Leptris::XML::Iterparse.parse(huge_xml) do |element|
+#       process(element)   # subtree valid until the next iteration
+#     end
+#
+# v2 (libleptris 1.9.4, #586): an explicit yield mode —
+# :top_level (v1: the root's completed children) or
+# :full_document (every element in document-order completion —
+# post-order, child before parent, subtree attached) — plus
+# namespace resolution on the last yielded element and an error
+# channel for truncated input:
+#
+#     it = Leptris::XML::Iterparse.parse(xml, mode: :full_document)
+#     it.run do |el|
+#       it.namespace_uri("p")   # in scope on el, the last yielded
+#     end
+#     it.free
+#
+#     Leptris::XML::Iterparse.parse(xml) { |el| ... }.error
+#     # => nil, or the parse failure (readable after the run: the
+#     #    block form frees the iterator on return, snapshotting it)
+#
+# The yielded elements are owned by an internal IterationScope:
+# #document returns nil (the documented contract) while liveness
+# guards and memoization engage — using an element after the
+# iterator frees raises UseAfterFreeError instead of crashing.
+class Leptris::XML::Iterparse
+  MODES = {
+    top_level: Leptris::XML::FFI::ITERPARSE_TOP_LEVEL,
+    full_document: Leptris::XML::FFI::ITERPARSE_FULL_DOCUMENT,
+  }.freeze
+
+  # NOTE: an IO argument is read fully into memory before the C
+  # iterator starts — the bounded-memory path is parse_file (C-side
+  # file streaming). The C API takes one (xml, len) buffer.
+  def self.parse(xml_or_io, mode: :top_level, &block)
+    xml = xml_or_io.is_a?(String) ? xml_or_io : xml_or_io.read
+    iterator = new(Leptris::XML::FFI.leptris_iterparse_new_ex(
+      xml, xml.bytesize, mode_code(mode)))
+    return iterator unless block
+    begin
+      iterator.run(&block)
+    ensure
+      iterator.free
+    end
+    iterator
+  end
+
+  def self.parse_file(path, mode: :top_level, &block)
+    iterator = new(Leptris::XML::FFI.leptris_iterparse_new_file_ex(
+      path, mode_code(mode)))
+    return iterator unless block
+    begin
+      iterator.run(&block)
+    ensure
+      iterator.free
+    end
+    iterator
+  end
+
+  def self.mode_code(mode)
+    MODES.fetch(mode) do
+      raise ArgumentError,
+        "mode must be :top_level or :full_document, got #{mode.inspect}"
+    end
+  end
+  private_class_method :mode_code
+
+  def initialize(handle)
+    raise Leptris::XML::ParseError, "leptris_iterparse_new failed" if handle.null?
+    @handle = handle
+    @scope = Leptris::XML::IterationScope.new(handle)
+  end
+
+  # Yields completed elements until the document is exhausted or the
+  # parse fails (see #error). Does not free the iterator — the block
+  # form of .parse/.parse_file does, or call #free explicitly.
+  def run
+    return enum_for(:run) unless block_given?
+    while @handle
+      ptr = Leptris::XML::FFI.leptris_iterparse_next(@handle)
+      break if ptr.null?
+      # The scope owns lifetime + memoization for yielded elements
+      # (ruby#152): liveness guards engage (post-free use raises
+      # instead of segfaulting), wrapper identity holds within a
+      # subtree, and memoized reads match document-backed cost.
+      # Each yield starts a fresh subtree — the released pool
+      # memory is recycled, so the identity cache resets with the
+      # memo version. #document still answers nil on the elements.
+      @scope.new_subtree!
+      yield Leptris::XML::Node.wrap(ptr, @scope)
+    end
+    self
+  end
+
+  # The URI bound to +prefix+ ("" for the default namespace) in the
+  # last yielded element's in-scope namespace snapshot, or nil when
+  # unbound (v2, #586). Valid only while the iterator is live —
+  # call it inside the #run block; nil after #free.
+  def namespace_uri(prefix)
+    return nil if @handle.nil?
+    Leptris::XML::FFI.leptris_iterparse_ns_uri(@handle, prefix.to_s)
+  end
+
+  # Number of namespace bindings in the last yielded element's
+  # scope. Valid only while the iterator is live; 0 after #free.
+  def namespace_count
+    return 0 if @handle.nil?
+    Leptris::XML::FFI.leptris_iterparse_ns_count(@handle)
+  end
+
+  # The parse error for malformed/truncated input, or nil when the
+  # document is well-formed and exhausted. Yielded elements stop at
+  # the failure point; #free snapshots the message so this stays
+  # readable after the block form of .parse returns.
+  def error
+    @handle ? live_error : @last_error
+  end
+
+  # Releases the C iterator. Safe to call twice.
+  def free
+    return if @handle.nil?
+    @last_error = live_error
+    Leptris::XML::FFI.leptris_iterparse_free(@handle)
+    @handle = nil
+    @scope.mark_freed
+  end
+
+  private
+
+  def live_error
+    msg = Leptris::XML::FFI.leptris_iterparse_error(@handle)
+    msg.nil? || msg.empty? ? nil : msg
+  end
+end

data/lib/leptris/xml/namespace.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# libleptris's LeptrisNamespace is `const char*` (the URI directly). The Ruby
+# Namespace wrapper holds (element, uri, optional prefix). When the prefix
+# isn't supplied (e.g. via Element#namespace), it can be derived by walking
+# the element's namespace declarations via leptris_element_namespace_decl_*.
+
+class Leptris::XML::Namespace
+  attr_reader :element, :href, :prefix
+
+  def initialize(element, href, prefix: :derive)
+    @element = element
+    @href = href
+    @prefix = prefix == :derive ? derive_prefix : prefix
+  end
+
+  def document
+    @element&.document
+  end
+
+  def ==(other)
+    other.is_a?(Leptris::XML::Namespace) &&
+      @href == other.href && @prefix == other.prefix
+  end
+
+  def inspect
+    "#<#{self.class.name} prefix=#{@prefix.inspect} href=#{@href.inspect}>"
+  end
+
+  private
+
+  def derive_prefix
+    return nil if @element.nil?
+    count = Leptris::XML::FFI.leptris_element_namespace_count(@element.c_ptr)
+    count.times do |i|
+      uri = Leptris::XML::FFI.leptris_element_namespace_decl_uri(@element.c_ptr, i)
+      next unless uri == @href
+      prefix = Leptris::XML::FFI.leptris_element_namespace_decl_prefix(@element.c_ptr, i)
+      return prefix.nil? || prefix.empty? ? nil : prefix
+    end
+    nil
+  end
+end

data/lib/leptris/xml/native_layer.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+# Opt-in native read layer (TODO.restructure/21 round 2, #185):
+# TypedData node wrappers with C-bound hot reads and bulk children
+# construction — measured 6.2x on raw walks. Load explicitly:
+#
+#     require "leptris/xml/native"
+#     root = doc.native_node
+#     root.children.each { |c| c.name }
+#
+# Identity is shared with the binding through the per-document
+# wrapper cache, so native and binding views of one document
+# interoperate. The default require path never loads this file;
+# installs without the compiled bundle (ruby-platform gem) raise
+# a clear LoadError from the require.
+
+require "ffi" unless defined?(::FFI::Library)
+
+begin
+  # The compiled bundle. A sanctioned require exception: a
+  # .bundle/.so cannot go through autoload. Missing in installs
+  # that do not vendor it (ruby-platform gem). Windows names the
+  # artifact per Ruby minor, DOT-FREE (#207/#227): a PE DLL must
+  # bind its build Ruby's runtime (one DLL per minor), and MRI
+  # derives the init symbol from the basename cut at the first
+  # dot — native_3_3.so resolves Init_native_3_3.
+  if Gem.win_platform?
+    require "leptris/xml/native_#{RUBY_VERSION[/\A\d+\.\d+/].tr('.', '_')}"
+  else
+    require "leptris/xml/native"
+  end
+rescue LoadError => e
+  raise LoadError, <<~MSG
+    leptris: the compiled native read layer is not available in
+    this install (#{e.message}). It ships in platform gems; the
+    ruby-platform variant does not carry it.
+  MSG
+end
+
+module Leptris::XML::Native
+  # FFI.libleptris_candidates is the single source of truth — the
+  # native layer MUST dlsym the exact image the FFI layer loaded,
+  # or two library instances split per-document state.
+  def self.lib_candidates
+    Leptris::XML::FFI.libleptris_candidates
+  end
+end
+
+# TODO.perf/01: accelerate the DEFAULT binding classes while the
+# bundle is loaded (name/content/prefix/[] hot reads).
+Leptris::XML::NATIVE_FAST = true
+
+candidates = Leptris::XML::Native.lib_candidates
+resolved = candidates.any? do |path|
+  begin
+    Leptris::XML::NativeNode.resolve!(path)
+    true
+  rescue RuntimeError
+    false
+  end
+end
+raise LoadError,
+  "leptris: native layer loaded but libleptris could not be " \
+  "resolved from #{candidates.inspect}" unless resolved
+
+class Leptris::XML::Document
+  # Separate identity cache for NativeNodes so binding Node.wrap
+  # and the native layer never overwrite each other.
+  def native_cache
+    @native_cache ||= {}
+  end
+
+  def native_node
+    r = root or raise Leptris::XML::Error, "document has no root element"
+    Leptris::XML::NativeNode.from(self, r.c_ptr)
+  end
+
+  # Builder factories that return NativeNodes (#149): one C call
+  # and a TypedData wrap — no FFI::Pointer, no wrap_fresh path.
+  def native_create_element(name)
+    Leptris::XML::NativeNode.create_element(self, name.to_s)
+  end
+
+  def native_create_text(content)
+    Leptris::XML::NativeNode.create_text(self, content.to_s)
+  end
+
+  def native_root=(element)
+    Leptris::XML::NativeNode.set_root(self, element)
+    element
+  end
+end