leptris 1.9.197.2-arm-linux

data/lib/leptris/xml/node_set.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+class Leptris::XML::NodeSet
+  include Enumerable
+  include Leptris::XML::Searchable
+
+  attr_reader :document
+
+  # Two construction modes:
+  # - eager: pass an Array of Nodes (e.g. Element#children builds one)
+  # - lazy:  pass an FFI::Pointer to a LeptrisXPathResult that this NodeSet
+  #          will keep alive and free on GC. Each [i] / each call goes
+  #          through leptris_xpath_result_get instead of pre-materializing.
+  def initialize(document, source = nil)
+    @document = document
+    case source
+    when ::FFI::Pointer
+      if source.null?
+        @result_ptr = nil
+        @array = []
+      else
+        # Wrap in AutoPointer for automatic GC-time cleanup. NodeSet has no
+        # explicit #free method (Nokogiri doesn't either), so the AutoPointer
+        # double-free risk that Document#free hit doesn't apply here.
+        @result_ptr = ::FFI::AutoPointer.new(source, Leptris::XML::FFI.method(:leptris_xpath_result_free))
+        @array = nil
+      end
+    when nil
+      @result_ptr = nil
+      @array = []
+    else
+      @result_ptr = nil
+      @array = source.to_a
+    end
+  end
+
+  def self.from_result(document, result_ptr)
+    new(document, result_ptr)
+  end
+
+  def length
+    return @array.length if @array
+    @result_ptr ? Leptris::XML::FFI.leptris_xpath_result_count(@result_ptr) : 0
+  end
+  alias_method :size, :length
+
+  def empty?
+    length == 0
+  end
+
+  # The materialized array (after to_a) is authoritative: every
+  # reader consults it first so a materialized set stops paying the
+  # batch fetch on each iteration or index.
+  def [](idx)
+    return @array[idx] if @array
+    # Negative indexes are Ruby-Array semantics (Nokogiri's NodeSet
+    # is slice-like); materialize rather than answer nil
+    # inconsistently with an eager set.
+    return to_a[idx] if idx.negative?
+    if @result_ptr
+      ptr = Leptris::XML::FFI.leptris_xpath_result_get_node(@result_ptr, idx)
+      return nil if ptr.null?
+      Leptris::XML::Node.wrap(
+        ptr, @document,
+        result_value: text_item_value(
+          Leptris::XML::FFI.leptris_xpath_result_node_kind(@result_ptr, idx), idx))
+    end
+  end
+
+  # Sequence/map/array items ride synthetic text nodes whose value
+  # only the live result handle can serve — capture it now.
+  def native_fast?
+    defined?(Leptris::XML::NATIVE_FAST)
+  end
+  private :native_fast?
+
+  def text_item_value(kind, index)
+    case kind
+    when Leptris::XML::FFI::XPATH_NODE_TEXT
+      Leptris::XML::FFI.leptris_xpath_result_node_value(@result_ptr, index)
+    when Leptris::XML::FFI::XPATH_NODE_ATTRIBUTE
+      # ruby#153: capture both faces — only the live result handle
+      # can serve an attribute node's name and value.
+      {
+        name: Leptris::XML::FFI.leptris_xpath_result_node_name(@result_ptr, index),
+        value: Leptris::XML::FFI.leptris_xpath_result_node_value(@result_ptr, index)
+      }
+    end
+  end
+  private :text_item_value
+
+  # Iteration materializes: the first pass batch-fetches into @array
+  # (yielding as it wraps), and every subsequent reader — each, [],
+  # length — serves from the array. Repeated iteration without an
+  # explicit to_a pays the batch exactly once.
+  def each
+    return enum_for(:each) unless block_given?
+    unless @array
+      return self unless @result_ptr
+      n = length
+      if n > 0 && native_fast?
+        # TODO.perf/03: one C pass materializes the whole result —
+        # class dispatch, synthetic text/attr value capture, and
+        # element identity-cache check/store in the ext. Qundef
+        # slots (rare non-element/attr/text kinds) and the >512
+        # remainder fall back to the per-index path below.
+        fast = Leptris::XML::Native.bulk_xpath(
+          @document, @result_ptr.to_i)
+        nodes = []
+        fast.each_with_index do |node, i|
+          if node.equal?(Leptris::XML::Native)
+            ptr = Leptris::XML::FFI.leptris_xpath_result_get_node(@result_ptr, i)
+            next if ptr.null?
+            nodes << Leptris::XML::Node.wrap(
+              ptr, @document,
+              result_value: text_item_value(
+                Leptris::XML::FFI.leptris_xpath_result_node_kind(@result_ptr, i), i))
+          else
+            nodes << node
+          end
+        end
+        (fast.length...n).each do |i|
+          ptr = Leptris::XML::FFI.leptris_xpath_result_get_node(@result_ptr, i)
+          next if ptr.null?
+          nodes << Leptris::XML::Node.wrap(
+            ptr, @document,
+            result_value: text_item_value(
+              Leptris::XML::FFI.leptris_xpath_result_node_kind(@result_ptr, i), i))
+        end
+        @array = nodes
+      elsif n > 0
+        # Batch-fetch all node pointers through the FFI seam
+        # (leptris_xpath_result_get_nodes_ex copies every node kind,
+        # not just elements); the batch accessor under-copies
+        # mixed-kind results (upstream leptris#477), so per-index
+        # fetch covers the remainder.
+        pointers, kinds, raw = Leptris::XML::FFI.fetch_result_nodes(@result_ptr, n)
+        nodes = []
+        pointers.each_with_index do |ptr, i|
+          next if ptr.null?
+          nodes << Leptris::XML::Node.wrap(
+            ptr, @document, node_type: kinds[i],
+            result_value: text_item_value(raw[i], i))
+        end
+        (pointers.length...n).each do |i|
+          ptr = Leptris::XML::FFI.leptris_xpath_result_get_node(@result_ptr, i)
+          next if ptr.null?
+          nodes << Leptris::XML::Node.wrap(
+            ptr, @document,
+            result_value: text_item_value(
+              Leptris::XML::FFI.leptris_xpath_result_node_kind(@result_ptr, i), i))
+        end
+        @array = nodes
+      else
+        @array = []
+      end
+    end
+    @array.each { |n| yield n }
+    self
+  end
+
+  def to_a
+    return @array if @array
+    return [] if @result_ptr.nil?
+    each { |n| }  # materializes @array as a side effect
+    @array
+  end
+  alias_method :to_ary, :to_a
+
+  def first(n = nil)
+    return self[0] if n.nil?
+    n.times.map { |i| self[i] }.take_while { |x| !x.nil? }
+  end
+
+  def last
+    if @result_ptr
+      self[length - 1]
+    else
+      @array.last
+    end
+  end
+
+  def inner_text
+    map(&:content).join
+  end
+  alias_method :text, :inner_text
+
+  # 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(" | ")
+    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
+    to_a.inspect
+  end
+end

data/lib/leptris/xml/parse_options.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+# Parser flags, mirroring LeptrisParseFlags in libleptris's public
+# headers. Pass an instance as `Leptris::XML.parse(xml, options:)`.
+class Leptris::XML::ParseOptions
+  # Discard whitespace-only text nodes (runs between tags that contain
+  # nothing but spaces/tabs/newlines). Matches libxml2's
+  # XML_PARSE_NOBLANKS and Nokogiri's noblanks. Documents parsed this
+  # way do not round-trip pretty-printed formatting byte-for-byte.
+  NOBLANKS = Leptris::XML::FFI::LEPTRIS_PARSE_DROP_WS_TEXT
+
+  # Apply DTD ATTLIST default (and #FIXED) attribute values at parse
+  # time (libleptris >= 1.9.8, leptris/leptris#606). Matches libxml2's
+  # XML_PARSE_DTDATTR and Nokogiri's dtdload+dtdattr semantics. Off by
+  # default: the ecosystem compares against libxml2's no-DTDATTR
+  # default, and W3C C14N 1.1 example 3.3's canonical form excludes
+  # defaulted attributes.
+  DTDATTR = Leptris::XML::FFI::LEPTRIS_PARSE_DTDATTR
+
+  # Keep &name; entity references unexpanded as first-class
+  # EntityReference nodes (libleptris 1.9.176, upstream #1094 /
+  # leptris-ruby#212): text runs split around them, character
+  # references still expand, and the references serialize back
+  # verbatim.
+  KEEP_ENTITY_REFS = Leptris::XML::FFI::LEPTRIS_PARSE_KEEP_ENTITY_REFS
+
+  attr_reader :flags
+
+  # Recover (libleptris 1.9.0, #547): a parse failure returns an
+  # empty document with the failure recorded in Document#last_error
+  # instead of raising — the libxml2 XML_PARSE_RECOVER semantics
+  # adapters emulate. Struct-only (not a parse flag): carrying it
+  # routes Document.parse through leptris_parse_string_ex.
+  attr_reader :recover
+
+  def initialize(flags = Leptris::XML::FFI::LEPTRIS_PARSE_DEFAULT,
+                 recover: false)
+    @flags = flags.to_i
+    @recover = recover ? true : false
+  end
+
+  def self.keep_entity_refs
+    new(KEEP_ENTITY_REFS)
+  end
+
+  def self.noblanks
+    new(NOBLANKS)
+  end
+
+  def self.recovering
+    new(recover: true)
+  end
+
+  def noblanks?
+    @flags & NOBLANKS != 0
+  end
+
+  def self.dtdattr
+    new(DTDATTR)
+  end
+
+  def dtdattr?
+    @flags & DTDATTR != 0
+  end
+
+  def keep_entity_refs?
+    @flags & KEEP_ENTITY_REFS != 0
+  end
+
+  def dtdattr=(value)
+    if value then @flags |= DTDATTR else @flags &= ~DTDATTR end
+  end
+
+  def recover?
+    @recover == true
+  end
+
+  def |(other)
+    self.class.new(@flags | other.flags, recover: @recover || other.recover?)
+  end
+
+  # True when the options cannot ride the flags-only parse path and
+  # need the full LeptrisParseOptions struct (leptris_parse_string_ex).
+  def struct_required?
+    recover?
+  end
+
+  # Builds the C LeptrisParseOptions struct mirroring this instance.
+  def to_c_struct
+    struct = Leptris::XML::FFI::ParseOptionsStruct.new
+    struct[:flags] = @flags
+    struct[:strict_mode] = -1
+    struct[:max_depth] = 0
+    struct[:recover] = @recover ? 1 : 0
+    struct
+  end
+end

data/lib/leptris/xml/plan_value.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+# One node of a Descriptor#walk result (libleptris 1.9.162, upstream
+# #1039): a lazy view over the engine-owned value tree. The ROOT
+# value owns the whole-result handle (freed by GC); child values
+# borrow from their parent — #at returns borrowed views, so the
+# root must outlive them (hold the root, read freely).
+#
+# The C result API reads attributes BY NAME only, so element
+# attribute enumeration threads the producing plan's attribute
+# rows: Descriptor#walk plants the root plan, #to_ruby walks
+# (value, plan) pairs in parallel.
+class Leptris::XML::PlanValue
+  VALUE_KINDS = {
+    Leptris::XML::FFI::PLAN_VALUE_ELEMENT => :element,
+    Leptris::XML::FFI::PLAN_VALUE_SCALAR => :scalar,
+    Leptris::XML::FFI::PLAN_VALUE_COLLECTION => :collection,
+    Leptris::XML::FFI::PLAN_VALUE_RAW => :raw,
+    Leptris::XML::FFI::PLAN_VALUE_CALLBACK => :callback,
+  }.freeze
+  private_constant :VALUE_KINDS
+
+  def initialize(ptr, owner: nil, plans: nil, plan: nil)
+    @ptr = ptr
+    @owner = owner
+    @plans = plans
+    @plan = plan
+  end
+
+  def kind
+    VALUE_KINDS.fetch(Leptris::XML::FFI.leptris_plan_value_kind(@ptr))
+  end
+
+  # wire_name of the plan row that produced this value.
+  def name
+    Leptris::XML::FFI.leptris_plan_value_name(@ptr)
+  end
+
+  # Host type_tag echoed verbatim (0 when the row had none).
+  def type_tag
+    Leptris::XML::FFI.leptris_plan_value_type_tag(@ptr)
+  end
+
+  # SCALAR / RAW / CALLBACK string value.
+  def string_value
+    Leptris::XML::FFI.leptris_plan_value_string(@ptr)
+  end
+
+  # CALLBACK: document byte offset of the source node (0 unknown).
+  def position
+    Leptris::XML::FFI.leptris_plan_value_position(@ptr)
+  end
+
+  # ELEMENT: child-value count. COLLECTION: item count.
+  def count
+    Leptris::XML::FFI.leptris_plan_value_count(@ptr)
+  end
+
+  # ELEMENT child value / COLLECTION item at +i+ (nil out of
+  # range). Borrowed: the owning root must stay alive.
+  def at(i)
+    ptr = Leptris::XML::FFI.leptris_plan_value_at(@ptr, i)
+    return nil if ptr.null?
+    child_name = Leptris::XML::FFI.leptris_plan_value_name(ptr)
+    child_plan = @plan ? child_row_plan(child_name) : nil
+    Leptris::XML::PlanValue.new(ptr, plans: @plans, plan: child_plan)
+  end
+
+  # ELEMENT: attribute value by wire_name (nil when absent).
+  def attribute(wire_name)
+    Leptris::XML::FFI.leptris_plan_value_attribute(@ptr, wire_name.to_s)
+  end
+
+  # The eager Ruby tree:
+  #   :element    => { kind:, name:, type_tag:, attributes: {...},
+  #                   children: [values] }
+  #   :scalar/:raw => String
+  #   :collection => [values]
+  #   :callback   => { value:, position:, type_tag: }
+  def to_ruby
+    case kind
+    when :element
+      {
+        kind: :element,
+        name: name,
+        type_tag: type_tag,
+        attributes: collected_attributes,
+        children: Array.new(count) { |i| at(i).to_ruby },
+      }
+    when :collection
+      Array.new(count) { |i| at(i).to_ruby }
+    when :callback
+      { value: string_value, position: position, type_tag: type_tag }
+    else
+      string_value
+    end
+  end
+
+  private
+
+  # The element plan that a child row with this wire_name recurses
+  # into (nil for non-nested rows — their values carry no plan).
+  def child_row_plan(child_wire_name)
+    row = (@plan[:children] || []).find do |r|
+      r[:kind] == :nested && r[:name] == child_wire_name
+    end
+    return nil unless row && @plans
+    @plans[row[:child_plan_index]]
+  end
+
+  def collected_attributes
+    result = {}
+    ((@plan && @plan[:attributes]) || []).each do |row|
+      v = attribute(row[:name])
+      result[row[:name]] = v unless v.nil?
+    end
+    result
+  end
+end

data/lib/leptris/xml/processing_instruction.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+class Leptris::XML::ProcessingInstruction < Leptris::XML::Node
+  def name
+    return @name if memo_hit?(@name_version)
+    ensure_alive!
+    result = if @addr_reads_fast
+               Leptris::XML::Native.fast_pi_target(@c_address)
+             else
+               Leptris::XML::FFI.leptris_pi_node_get_target(c_ptr)
+             end
+    if @document
+      @name = result
+      @name_version = @document.version
+    end
+    result
+  end
+  alias_method :target, :name
+
+  def content
+    return @content if memo_hit?(@content_version)
+    ensure_alive!
+    raw = if @addr_reads_fast
+            Leptris::XML::Native.fast_pi_data(@c_address)
+          else
+            Leptris::XML::FFI.leptris_pi_node_get_data(c_ptr)
+          end
+    result = Leptris::XML::FFI.read_pi_data(raw).to_s
+    if @document
+      @content = result
+      @content_version = @document.version
+    end
+    result
+  end
+
+  # Since libleptris 1.9.9 (#612) parse-created document-level PIs
+  # carry document linkage — the setters work on them like on any
+  # tree-level PI.
+  def target=(new_target)
+    ensure_writable!
+    Leptris::XML::FFI.check_status(
+      Leptris::XML::FFI.leptris_pi_node_set_target(c_ptr, new_target.to_s))
+    new_target
+  end
+
+  def data=(new_data)
+    ensure_writable!
+    Leptris::XML::FFI.check_status(
+      Leptris::XML::FFI.leptris_pi_node_set_data(c_ptr, new_data.to_s))
+    new_data
+  end
+
+  # Document-level PIs have no tree parent for leptris_node_unlink
+  # — route through the document-level removal (libleptris 1.9.9,
+  # #612), identity-matched by index so the right same-target PI
+  # comes out.
+  def unlink
+    ensure_writable!
+    rc = Leptris::XML::FFI.leptris_node_unlink(c_ptr)
+    if rc == Leptris::XML::FFI::LEPTRIS_ERROR_NOT_FOUND
+      index = document_pi_index
+      if index.negative?
+        raise Leptris::XML::Error,
+          "PI not found in its document — already removed?"
+      end
+      removed = @document.remove_pi(index)
+      unless removed && removed.c_ptr == c_ptr
+        raise Leptris::XML::Error, "document-level PI removal missed"
+      end
+      @parent = nil
+      return self
+    end
+    Leptris::XML::FFI.check_status(rc)
+    @parent = nil
+    self
+  end
+
+  private
+
+  # This PI's 0-based index among the document's PIs (document
+  # order — the same enumeration leptris_document_remove_pi uses).
+  def document_pi_index
+    pi_index = -1
+    @document.children.each do |child|
+      pi_index += 1 if child.pi?
+      return pi_index if child.c_ptr == c_ptr
+    end
+    -1
+  end
+end