moxml 0.5.59 → 0.5.61

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0093cdce010f7f3dbc901b0c202b524f6df10b821fd8ed07e290688c22957ab1'
-  data.tar.gz: bffcd7f1fc07278194510a2a1cc427bf19917028643b210380bd3f37f831f22d
+  metadata.gz: 432ffb6c040c2b5689552a050b01835b792cde27ddc816981fd186fd83b9df7d
+  data.tar.gz: 917f7712e1799209f6d1c3f832fb5a3de492da5e570959a9d8bf2a8b4902d537
 SHA512:
-  metadata.gz: 47fab72bf502121e85e39358ffe615618af913cf5a3535c014ad2a614d0c910102b0c763c31a3d0ab4f0032bc2af407ce11da511fed05725d1fe0e2e53591ccf
-  data.tar.gz: dca3fd95a60a848a34cc880b5173a8f98b0f24f17b7be71e5a7eff00f92add6c807b44fa7525e70d7488f13ba8e037bf5f8b9e84fb26d9c7ddf9c02cc7ed8f10
+  metadata.gz: b6f0a69c52df888bf9afbc2706e755d9844d8d65247720d887cc6fb34c8d855964f278d798b947bfb028ce58f32253ff6ed92101fcc2cf45fe28695170c23405
+  data.tar.gz: 90b841bd8eb58119a38dce5333a53f9b37abc70755e69a887c52ab4565d1101727a2dcc40903a4671b92a10d4ba1bd67ab712ac97d37bdd04861359dd4b09bba

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

@@ -213,49 +213,84 @@ module Moxml
               processing_instruction: PROCESSING_INSTRUCTION,
             }.freeze
 
-            module Reads
-              # The C methods sit BELOW the contract modules in the
-              # ancestry (NativeNode is the superclass), so super
-              # from here would run the contract implementation and
-              # ADD frames. bind_call reaches the C surface
-              # directly; prefixed names take the contract path.
-              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
+            # Hot-read face selection: bindings >= 1.9.194.1 carry
+            # unshadowed aliases (attr_read/text_read) that plain
+            # dispatch reaches at method-cache cost — beats
+            # UnboundMethod#bind_call (~86ns) on every bare read.
+            ELEMENT_CONTRACT_READ =
+              ::Moxml::ElementBehavior.instance_method(:[])
+
+            NATIVE_HOT_ALIASES =
+              Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.194.1")
+
+            # Doc-level entity-marker memo shared by both hot-read
+            # faces (one WeakMap, generation-stamped Integer values).
+            ENTITY_DOC_MEMO = ::ObjectSpace::WeakMap.new
+
+            if NATIVE_HOT_ALIASES
+              module Reads
+                # 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.
+                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) && doc_entity_bearing?
+                def [](key)
+                  if key.is_a?(String) && !key.include?(":")
+                    value = attr_read(key)
+                    return value unless value.is_a?(String) && doc_entity_bearing?
 
-                  return ::Moxml::Adapter::Leptris.restore_entities(value)
+                    return ::Moxml::Adapter::Leptris.restore_entities(value)
+                  end
+
+                  ELEMENT_CONTRACT_READ.bind_call(self, key)
                 end
 
-                ELEMENT_CONTRACT_READ.bind_call(self, key)
+                def text
+                  value = text_read
+                  value.is_a?(String) && doc_entity_bearing? ? ::Moxml::Adapter::Leptris.restore_entities(value) : value
+                end
               end
+            else
+              module Reads
+                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) && doc_entity_bearing?
+
+                    return ::Moxml::Adapter::Leptris.restore_entities(value)
+                  end
 
-              def text
-                value = NN_CONTENT.bind_call(self)
-                value.is_a?(String) && doc_entity_bearing? ? ::Moxml::Adapter::Leptris.restore_entities(value) : value
+                  ELEMENT_CONTRACT_READ.bind_call(self, key)
+                end
+
+                def text
+                  value = NN_CONTENT.bind_call(self)
+                  value.is_a?(String) && doc_entity_bearing? ? ::Moxml::Adapter::Leptris.restore_entities(value) : value
+                end
               end
             end
             ELEMENT.include(Reads)
@@ -493,6 +528,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/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.59"
+  VERSION = "0.5.61"
 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.59
+  version: 0.5.61
 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