moxml 0.5.58 → 0.5.60

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 03fd3940f1334b3f417e4847f35e87497581404372209de4426819a8acc6d363
-  data.tar.gz: 805f6966495456ff6e36c4f1be3df9fcbbf1c89cfcf2ddc6a4153c37e1bcec71
+  metadata.gz: 70fbb27b6a314c772f06699958b27c017a5033c33a62f84ff98d15c3c8a866a0
+  data.tar.gz: 4222b8eb5f128d74bc55a3284596f11bc975684eae28ff3f0cb8fe56bb2a4899
 SHA512:
-  metadata.gz: 872ba59e6f8b72779d2ea43c8af201052a69be9d75ad1add3fa2618bc58e81cee0503ce352d06c8b46c64cc6340859006b36afeadef4302f29c81e2760285baa
-  data.tar.gz: 01eed98fc6ac76efb35d2456c9af57487bbdddf13092a09b0667d11e6e2d48a1905865046aab6a59ca8a89523fc4337a705c1b1cf95d98342d56cb4494c0d91e
+  metadata.gz: '08307faaef4bfdfbda347f2f860f71f4aedabfc1b30bf81bcdfe876296ee68df6138e42efcf92c04cb94f3696a8ff33b038ce40bf826ad87491a1ee07364e2c3'
+  data.tar.gz: 1f084671c8983ed53172652e6322670b09550758b76378b30905bf1c1c30e7cc531d9fdd46edc3ecd7d9bf2ffa6cbd23e79a989a9d0237eae020191265c29641

data/lib/moxml/adapter/base.rb

@@ -358,6 +358,15 @@ namespace_validation_mode: :strict)
           nil
         end
 
+        # Plan row stream (Moxml::Plan): yields |name, attrs_pairs
+        # (flat [k, v, ...]), first-text, depth| per element in
+        # document order (pre-order). Returns true when the adapter
+        # provided the stream; nil/false lets the plan run its
+        # generic wrapper walk.
+        def plan_rows(_native)
+          nil
+        end
+
         # Deterministic native-memory release for adapters backed by
         # C trees (issue #134). GC-managed engines no-op; released
         # documents raise the engine's use-after-free error on

data/lib/moxml/adapter/leptris.rb

@@ -222,10 +222,30 @@ module Moxml
               ELEMENT_CONTRACT_READ =
                 ::Moxml::ElementBehavior.instance_method(:[])
 
+              # Marker presence is a DOCUMENT fact, but the wrapper
+              # memo re-derives it per node (the per-read machinery
+              # was ~a quarter of the consumer walk). Doc-level
+              # WeakMap, generation-stamped into one Integer
+              # (immediates make safe weak values): one C document
+              # read plus one map hit per bare read. Entries die
+              # with their documents; a stale generation re-derives.
+              ENTITY_DOC_MEMO = ::ObjectSpace::WeakMap.new
+
+              def doc_entity_bearing?
+                doc = NN_DOCUMENT.bind_call(self)
+                memo = ENTITY_DOC_MEMO[doc]
+                gen = ::Moxml::Adapter::Leptris.serialize_generation
+                return memo.allbits?(1) if memo && (memo >> 1) == gen
+
+                bearing = ::Moxml::Adapter::Leptris.entity_bearing?(self)
+                ENTITY_DOC_MEMO[doc] = (gen << 1) | (bearing ? 1 : 0)
+                bearing
+              end
+
               def [](key)
                 if key.is_a?(String) && !key.include?(":")
                   value = NN_ATTRIBUTE.bind_call(self, key)
-                  return value unless value.is_a?(String) && entity_bearing?
+                  return value unless value.is_a?(String) && doc_entity_bearing?
 
                   return ::Moxml::Adapter::Leptris.restore_entities(value)
                 end
@@ -235,7 +255,7 @@ module Moxml
 
               def text
                 value = NN_CONTENT.bind_call(self)
-                value.is_a?(String) && entity_bearing? ? ::Moxml::Adapter::Leptris.restore_entities(value) : value
+                value.is_a?(String) && doc_entity_bearing? ? ::Moxml::Adapter::Leptris.restore_entities(value) : value
               end
             end
             ELEMENT.include(Reads)
@@ -473,6 +493,50 @@ module Moxml
       extend Markers
       extend Materialize
 
+      # Plan row stream (Moxml::Plan): the engine's one-pass C
+      # snapshot is pre-order with the first text child on the row —
+      # exactly the plan's shape, with no wrapper minting at all.
+      # Marker-bearing documents stay on the generic path (the bulk
+      # stream has no marker split).
+      NATIVE_PLAN_ROWS =
+        NATIVE_READ_LAYER &&
+        Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.193.4")
+
+      def self.plan_rows(native)
+        return nil unless NATIVE_READ_LAYER
+
+        doc = if native.is_a?(::Leptris::XML::Document)
+                native
+              else
+                doc_for(native)
+              end
+        return nil if doc.nil? || attachments.get(doc, :entity_markers)
+
+        root_binding = if native.is_a?(::Leptris::XML::Document)
+                         doc.root
+                       else
+                         to_binding(native)
+                       end
+        return nil unless root_binding
+
+        rows = if NATIVE_PLAN_ROWS
+                 ::Leptris::XML::Native.snapshot_rows(doc,
+                                                      root_binding.c_address)
+               else
+                 doc.snapshot(root_binding)
+               end
+        rows.each do |row|
+          if row.is_a?(::Array)
+            yield(row[0], row[1], row[2], row[3])
+          else
+            next unless row[:kind] == "element"
+
+            yield(row[:name], row[:attrs].flatten, row[:text], row[:depth])
+          end
+        end
+        true
+      end
+
       class << self
         def attachments
           @attachments ||= Moxml::NativeAttachment.new

data/lib/moxml/node.rb

@@ -164,30 +164,18 @@ module Moxml
     # entity-marker flag flips at parse and entity-reference mint,
     # both adapter-level, and the generation bump is the invalidation
     # signal. Adapters with static answers (base class) never bump.
+    # The adapter resolves the owning document itself (doc_for is a
+    # single C read on the native layer); wrappers no longer climb.
     def entity_bearing?
       gen = adapter.serialize_generation
       if @entity_bearing_gen == gen
         @entity_bearing
       else
         @entity_bearing_gen = gen
-        @entity_bearing = adapter.entity_bearing?(@native, document_native_for_markers)
+        @entity_bearing = adapter.entity_bearing?(@native)
       end
     end
 
-    # Binding document through the wrapper parent chain — pure Ruby
-    # attr reads; the native-layer fallback climbs C parents per
-    # call (the doc_for walk was the largest wrapper-layer cost on
-    # the consumer pipeline after the native adoption).
-    def document_native_for_markers
-      node = self
-      while node
-        return node.native if node.document?
-
-        node = node.parent_node
-      end
-      nil
-    end
-
     def xpath(expression, namespaces = {})
       result = adapter.xpath(@native, expression, namespaces)
       # Adapter contract: Array<native> | LazyNodeSet | scalar.

data/lib/moxml/plan.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Moxml
+  # Plan-compiled materialization: declare the document shape once,
+  # execute it against the adapter's bulk row stream — no wrapper
+  # tree, no NodeSet, no per-node contract dispatch. The compiled
+  # grammar instead of the interpreted walk.
+  #
+  #   plan = Moxml::Plan.new do
+  #     on("record") { |attrs, _text, fields| Record.new(attrs["id"], attrs["kind"], fields) }
+  #     on("field")  { |attrs, text, _kids| Field.new(attrs["name"], attrs["unit"], text) }
+  #   end
+  #   records = plan.parse(xml, ctx)
+  #
+  # Handlers run bottom-up as each element completes; +children+ is
+  # the array of handler values for matched child elements whose
+  # parent ALSO matched (values of unmatched parents are dropped —
+  # matching a parent is the consumer's decision to keep a subtree).
+  # +attrs+ is a Hash of the element's attributes (local name =>
+  # value); +text+ is the first text child's content, or nil.
+  #
+  # Name matching is global (flat table, not path-relative): element
+  # names unique per role — the dominant consumer shape — work as-is;
+  # distinct roles sharing a name need distinct documents or a
+  # rename upstream.
+  #
+  # Adapters with a bulk stream answer plan_rows (leptris: the
+  # engine's one-pass C snapshot — pre-order, first-text on the
+  # row); the rest run the generic pre-order wrapper walk below,
+  # emitting the identical stream — spec-pinned equal.
+  class Plan
+    def initialize(&block)
+      @handlers = {}
+      instance_eval(&block) if block
+    end
+
+    # Registers a handler for elements named +name+ (local name).
+    # Returns self so registrations chain.
+    def on(name, &handler)
+      raise ArgumentError, "on(#{name.inspect}) requires a block" unless handler
+
+      @handlers[name] = handler
+      self
+    end
+
+    # Parses +xml+ and materializes the plan against it.
+    def parse(xml, context)
+      materialize(context.parse(xml))
+    end
+
+    # Materializes the plan against a document (or element) wrapper.
+    # Returns the values of top-level matched elements.
+    def materialize(node)
+      results = []
+      frames = []   # per open depth: children values (nil = unmatched)
+      meta = []     # per open depth: [name, attrs, text] (nil = unmatched)
+
+      close_top = lambda do
+        m = meta.pop
+        children = frames.pop
+        next unless m
+
+        value = @handlers[m[0]].call(m[1], m[2], children)
+        if frames.empty? || frames.last.nil?
+          results << value
+        else
+          frames.last << value
+        end
+      end
+
+      row = lambda do |name, attrs_pairs, text, depth|
+        close_top.call while frames.size > depth
+        handler = @handlers[name]
+        if handler
+          attrs = {}
+          i = 0
+          while i < attrs_pairs.length
+            attrs[attrs_pairs[i]] = attrs_pairs[i + 1]
+            i += 2
+          end
+          frames << []
+          meta << [name, attrs, text]
+        else
+          frames << nil
+          meta << nil
+        end
+      end
+
+      adapter = node.context.config.adapter
+      ran = adapter.plan_rows(node.native) do |name, pairs, text, depth|
+        row.call(name, pairs, text, depth)
+      end
+      unless ran
+        walk_wrappers(node) do |name, pairs, text, depth|
+          row.call(name, pairs, text, depth)
+        end
+      end
+
+      close_top.call while meta.any?
+      results
+    end
+
+    private
+
+    # Generic pre-order walk over the wrapper tree — the fallback
+    # stream for adapters without a bulk path. Same protocol as
+    # plan_rows: |name, attrs_pairs (flat [k, v, ...]), first-text,
+    # depth|.
+    def walk_wrappers(node, depth = 0)
+      case node
+      when Document
+        (root = node.root) && walk_wrappers(root, depth) { |*a| yield(*a) }
+      when Element
+        first_text = nil
+        node.children.each do |child|
+          first_text ||= child.content if child.is_a?(Text)
+        end
+        yield(node.name, attribute_pairs(node), first_text, depth)
+        node.children.each do |child|
+          walk_wrappers(child, depth + 1) { |*a| yield(*a) } if child.is_a?(Element)
+        end
+      end
+    end
+
+    def attribute_pairs(element)
+      pairs = []
+      element.attributes.each do |attr|
+        pairs << attr.name << attr.value
+      end
+      pairs
+    end
+  end
+end

data/lib/moxml/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Moxml
-  VERSION = "0.5.58"
+  VERSION = "0.5.60"
 end

data/lib/moxml.rb

@@ -93,6 +93,7 @@ module Moxml
   autoload :XmlUtils, "moxml/xml_utils"
   autoload :XmlEmitter, "moxml/xml_emitter"
   autoload :Materializer, "moxml/materializer"
+  autoload :Plan, "moxml/plan"
   autoload :Adapter, "moxml/adapter"
   autoload :XPath, "moxml/xpath"
   autoload :SAX, "moxml/sax"

data/spec/moxml/plan_spec.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# Moxml::Plan: shape-compiled materialization over the adapter's
+# bulk row stream (leptris C snapshot) and the generic wrapper walk.
+# Both paths must produce identical values.
+RSpec.describe Moxml::Plan do
+  PlanRow = Struct.new(:id, :kind, :fields) # rubocop:disable Lint/ConstantDefinitionInBlock, RSpec/LeakyConstantDeclaration
+  PlanCell = Struct.new(:name, :unit, :value) # rubocop:disable Lint/ConstantDefinitionInBlock, RSpec/LeakyConstantDeclaration
+
+  let(:xml) do
+    <<~XML
+      <?xml version="1.0"?>
+      <catalog>
+        <record id="r0" kind="k0"><field name="f0" unit="u0">v 0.0</field><field name="f1" unit="u1">v 0.1</field></record>
+        <record id="r1" kind="k1"><field name="f0" unit="u0">v 1.0</field></record>
+      </catalog>
+    XML
+  end
+  let(:plan) do
+    described_class.new do
+      on("record") do |attrs, _text, fields|
+        PlanRow.new(attrs["id"], attrs["kind"], fields)
+      end
+      on("field") do |attrs, text, _kids|
+        PlanCell.new(attrs["name"], attrs["unit"], text)
+      end
+    end
+  end
+
+  shared_examples "plan materialization" do |adapter_name|
+    let(:ctx) { Moxml.new(adapter_name) }
+
+    it "builds the typed shape" do
+      rows = plan.parse(xml, ctx)
+
+      expect(rows.size).to eq(2)
+      expect(rows[0].id).to eq("r0")
+      expect(rows[0].kind).to eq("k0")
+      expect(rows[0].fields.size).to eq(2)
+      expect(rows[0].fields[0]).to eq(PlanCell.new("f0", "u0", "v 0.0"))
+      expect(rows[0].fields[1]).to eq(PlanCell.new("f1", "u1", "v 0.1"))
+      expect(rows[1].fields[0].value).to eq("v 1.0")
+    end
+
+    it "drops values of unmatched parents" do
+      orphans = described_class.new do
+        on("field") { |attrs, text, _| PlanCell.new(attrs["name"], attrs["unit"], text) }
+      end.parse(xml, ctx)
+
+      # fields match everywhere; no record handler keeps them
+      expect(orphans.size).to eq(3)
+    end
+
+    it "returns top-level values for a matched root" do
+      roots = described_class.new do
+        on("catalog") { |_a, _t, kids| [:catalog, kids] }
+        on("record") { |attrs, _t, fields| [attrs["id"], fields] }
+        on("field") { |attrs, text, _| [attrs["name"], text] }
+      end.parse(xml, ctx)
+
+      expect(roots.size).to eq(1)
+      expect(roots[0][0]).to eq(:catalog)
+      expect(roots[0][1].size).to eq(2)
+    end
+
+    it "handles depth-3 nesting" do
+      deep = described_class.new do
+        on("catalog") { |_a, _t, records| records }
+        on("record") { |attrs, _t, fields| [attrs["id"], fields] }
+        on("field") { |attrs, text, _| [attrs["name"], text] }
+      end.parse(xml, ctx)
+
+      expect(deep.size).to eq(1)
+      expect(deep[0]).to eq(
+        [["r0", [["f0", "v 0.0"], ["f1", "v 0.1"]]],
+         ["r1", [["f0", "v 1.0"]]]],
+      )
+    end
+
+    it "is reusable across documents" do
+      first = plan.parse(xml, ctx)
+      second = plan.parse(xml, ctx)
+
+      expect(first).to eq(second)
+    end
+  end
+
+  describe "bulk path (leptris)" do
+    it_behaves_like "plan materialization", :leptris
+  end
+
+  describe "generic path" do
+    it_behaves_like "plan materialization", :nokogiri
+  end
+
+  it "requires a handler block" do
+    expect { described_class.new.on("x") }
+      .to raise_error(ArgumentError, /requires a block/)
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: moxml
 version: !ruby/object:Gem::Version
-  version: 0.5.58
+  version: 0.5.60
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-17 00:00:00.000000000 Z
+date: 2026-09-18 00:00:00.000000000 Z
 dependencies: []
 description: |
   Moxml is a unified XML manipulation library that provides a common API
@@ -214,6 +214,7 @@ files:
 - lib/moxml/native_attachment/opal.rb
 - lib/moxml/node.rb
 - lib/moxml/node_set.rb
+- lib/moxml/plan.rb
 - lib/moxml/processing_instruction.rb
 - lib/moxml/sax.rb
 - lib/moxml/sax/block_handler.rb
@@ -487,6 +488,7 @@ files:
 - spec/moxml/opal_oga_smoke_spec.rb
 - spec/moxml/opal_rexml_adapter_spec.rb
 - spec/moxml/opal_smoke_spec.rb
+- spec/moxml/plan_spec.rb
 - spec/moxml/processing_instruction_spec.rb
 - spec/moxml/readonly_parse_spec.rb
 - spec/moxml/sax/namespace_splitter_spec.rb