moxml 0.5.59 → 0.5.60

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0093cdce010f7f3dbc901b0c202b524f6df10b821fd8ed07e290688c22957ab1'
-  data.tar.gz: bffcd7f1fc07278194510a2a1cc427bf19917028643b210380bd3f37f831f22d
+  metadata.gz: 70fbb27b6a314c772f06699958b27c017a5033c33a62f84ff98d15c3c8a866a0
+  data.tar.gz: 4222b8eb5f128d74bc55a3284596f11bc975684eae28ff3f0cb8fe56bb2a4899
 SHA512:
-  metadata.gz: 47fab72bf502121e85e39358ffe615618af913cf5a3535c014ad2a614d0c910102b0c763c31a3d0ab4f0032bc2af407ce11da511fed05725d1fe0e2e53591ccf
-  data.tar.gz: dca3fd95a60a848a34cc880b5173a8f98b0f24f17b7be71e5a7eff00f92add6c807b44fa7525e70d7488f13ba8e037bf5f8b9e84fb26d9c7ddf9c02cc7ed8f10
+  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

@@ -493,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/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.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.59
+  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