moxml 0.5.84 → 0.5.86

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff836e409dd2cf77368c7b26015e57de1b0af5e0678489e6e10452a6c70cc61a
-  data.tar.gz: a2a09b561505f90fc624089e925c3b41d4ab867668b00fd35f1132787e9dbfde
+  metadata.gz: 24155b1be6da49c7e24b3be5bef79caeac8e76f19c006329382330dee7d4e259
+  data.tar.gz: 0f8b8736e98239902ad1dfe0deba7f7c4b22f61400ae6628ebcc8e5484ef319b
 SHA512:
-  metadata.gz: decb847bc6cfd50e816c916d98c74b837d63e9e38a9b49a2d964333a141a8fafd9e55291f83a52739403ad99126884c2a37928567ac9f4f8fdaae3ca9df37692
-  data.tar.gz: 59be5497f4f1a4d439e86b4138be240b1bcabb370bc6d991d79b92aa64e9a40f0243b29f090d4171fd45146593ed27fc2da29ae2a2a72d0f542919e3e5aecf3b
+  metadata.gz: 4a1a93ce53b2dee189b74c608f930483c4a0ecffaeed03a570486bede424e6cf9244d7262e038ba8cb0a5a2d3b2d2c99711a47fac53f5abdc87640957a9ae379
+  data.tar.gz: 5b997e1cf171d4f6c08bfedb2fb9cb0caa02e022d491e26a63e1e613fe8340972e8629cfe28e158d23ee1c24956d4e54d541af8b76c44f1be6ca25d9e7aa0d76

data/README.adoc

@@ -102,8 +102,13 @@ entity references (`entity_mode: :keep`), 1.9.193.4+ native plan rows
 (`Moxml::Plan`), 1.9.194.1+ hot-read aliases, 1.9.201.1+ the C struct
 executor (`Moxml::StructPlan`; the floor is the varargs-mint fix),
 1.9.204+ native document-level parts (created DOCTYPEs as native
-nodes, document-PI removal, declaration clear). Current
-recommendation: 1.9.228+ (the #318 text-set fix train; carries
+nodes, document-PI removal, declaration clear), 1.9.240+ the bulk
+SAX record drain (`Handler#on_sax_records`) — and 1.9.242+ is
+REQUIRED for that drain to be CORRECT: 1.9.240/241 drain documents
+containing duplicate attributes without surfacing the fatal error
+(moxml#281), so the drain arms only on 1.9.242+, where such
+documents fall back to the callback path and the error fires.
+Current recommendation: 1.9.242+ (the record-drain train; carries
 the plan-ABI surface — bound plan rows, typed scalars, fused
 Descriptor#materialize — plus the 1.9.217+ borrowed-text-run and
 1.9.221+ memory wins).
@@ -681,6 +686,66 @@ doc.parse_diagnostics
 # => [{ kind: :recover, message: "Attribute a redefined" }]
 ----
 
+=== Hot-loop SAX consumption (bulk record drain)
+
+On the leptris adapter (binding >= 1.9.240), `sax_parse` drains the
+whole document in ONE crossing into a record table. Handlers that
+override `on_sax_records` walk the records directly and materialize
+only the strings they consume — allocations drop from the callback
+path's ~15/element to the consumer-chosen floor (~1/element for a
+name-materializing walker):
+
+[source,ruby]
+----
+class RecordDriver < Moxml::SAX::Handler
+  def initialize(builder)
+    super()
+    @builder = builder
+  end
+
+  def on_sax_records(table)
+    idx_stack = []
+    name_stack = []
+    i = 0
+    while i < table.count
+      # a parent mismatch is the exact close boundary; end events
+      # reconstruct from the records' parent indices
+      while !idx_stack.empty? && table.parent(i) != idx_stack.last
+        idx_stack.pop
+        @builder.end_element(name_stack.pop)
+      end
+      if table.kind(i).zero? # element
+        name = table.view(i)
+        attrs = []
+        k = table.attr_first(i)
+        last = k + table.attr_count_of(i)
+        while k < last
+          v = table.attr_value(k)
+          attrs << [table.attr_name(k),
+                    table.attr_value_has_ws?(k) ? v.tr("\t\n\r", " ") : v]
+          k += 1
+        end
+        @builder.start_element(name, attrs)
+        idx_stack << i
+        name_stack << name
+      else # text
+        @builder.characters(table.view(i))
+      end
+      i += 1
+    end
+    @builder.end_element(name_stack.pop) until name_stack.empty?
+    :claimed # claimed the table — no callback replay
+  end
+end
+----
+
+Measured on the 2 x 226-element bench shape (`rake benchmark:sax`):
+callback recorder 6,835 allocs / 1,735µs; default replay 6,353 /
+1,991µs; record-driven builder 3,638 / 1,248µs; counting walk 482 /
+778µs. Documents outside the drain's subset (comments, PIs, CDATA,
+DOCTYPE, xmlns, entities) fall back to the callback path
+transparently.
+
 == Real-world examples
 
 Practical, runnable examples demonstrating Moxml usage in common scenarios are

data/benchmark/sax_bench.rb

@@ -41,6 +41,53 @@ module SaxBenchHandlers
       :claimed
     end
   end
+
+  # The builder-protocol shape (canon's comparison driver): walk the
+  # records but materialize the full event payload — name, attr
+  # name/value pairs, text — exactly what the callback protocol
+  # delivers, minus the recorder's double marshaling and the Hash.
+  class RecordBuilderHandler < Moxml::SAX::Handler
+    attr_reader :events
+
+    def initialize
+      super
+      @events = 0
+    end
+
+    def on_sax_records(table)
+      idx_stack = []
+      name_stack = []
+      i = 0
+      count = table.count
+      while i < count
+        while !idx_stack.empty? && table.parent(i) != idx_stack.last
+          idx_stack.pop
+          name_stack.pop
+          @events += 1
+        end
+        if table.kind(i).zero?
+          name = table.view(i)
+          k = table.attr_first(i)
+          last = k + table.attr_count_of(i)
+          while k < last
+            table.attr_name(k)
+            v = table.attr_value(k)
+            v = v.tr("\t\n\r", " ") if table.attr_value_has_ws?(k)
+            @events += 1
+            k += 1
+          end
+          idx_stack << i
+          name_stack << name
+        else
+          table.view(i)
+          @events += 1
+        end
+        i += 1
+      end
+      @events += name_stack.size
+      :claimed
+    end
+  end
 end
 
 CTX = Moxml.new(:leptris).freeze # rubocop:disable Lint/ConstantDefinitionInBlock
@@ -68,6 +115,8 @@ handler = SaxBenchHandlers::NullHandler.new
 3.times { DOCS.each { |doc| Leptris::XML::SAX::Parser.new(BRIDGE.new(handler)).parse(doc) } }
 walker = SaxBenchHandlers::RecordWalkHandler.new
 3.times { DOCS.each { |doc| Moxml::Adapter::Leptris.sax_parse(doc, walker) } }
+builder = SaxBenchHandlers::RecordBuilderHandler.new
+3.times { DOCS.each { |doc| Moxml::Adapter::Leptris.sax_parse(doc, builder) } }
 
 recorder_allocs = allocations do
   DOCS.each { |doc| Leptris::XML::SAX::Parser.new(BRIDGE.new(handler)).parse(doc) }
@@ -78,13 +127,18 @@ end
 walk_allocs = allocations do
   DOCS.each { |doc| Moxml::Adapter::Leptris.sax_parse(doc, walker) }
 end
+builder_allocs = allocations do
+  DOCS.each { |doc| Moxml::Adapter::Leptris.sax_parse(doc, builder) }
+end
 
 replay_time = cpu_micros { 5.times { DOCS.each { |doc| Moxml::Adapter::Leptris.sax_parse(doc, handler) } } }
 recorder_time = cpu_micros { 5.times { DOCS.each { |doc| Leptris::XML::SAX::Parser.new(BRIDGE.new(handler)).parse(doc) } } }
 walk_time = cpu_micros { 5.times { DOCS.each { |doc| Moxml::Adapter::Leptris.sax_parse(doc, walker) } } }
+builder_time = cpu_micros { 5.times { DOCS.each { |doc| Moxml::Adapter::Leptris.sax_parse(doc, builder) } } }
 
 puts format("recorder           %<allocs>6d allocs  %<time>6dµs", allocs: recorder_allocs, time: recorder_time / 5)
 puts format("drain replay       %<allocs>6d allocs  %<time>6dµs", allocs: replay_allocs, time: replay_time / 5)
+puts format("drain builder-walk %<allocs>6d allocs  %<time>6dµs", allocs: builder_allocs, time: builder_time / 5)
 puts format("drain records-walk %<allocs>6d allocs  %<time>6dµs", allocs: walk_allocs, time: walk_time / 5)
 puts "(#{walker.elements} elements walked cumulatively; 452 per rep)"
 

data/lib/moxml/adapter/leptris.rb

@@ -132,12 +132,15 @@ module Moxml
 
       # Bulk SAX record drain (leptris#1298): leptris_sax_records_parse
       # + Leptris::XML::SAX::Records — one crossing per document,
-      # handlers replay or walk the table. Ships in the binding ride
-      # 1.9.240.0 (1.9.239.0 predates the walker — the gate must name
-      # the carrying release, not the engine surface). Dev floor pins
-      # ~> 1.9.238; older bindings take the callback Parser below.
+      # handlers replay or walk the table. Ships in binding 1.9.242.0:
+      # 1.9.240/241 carry the drain WITHOUT the duplicate-attribute
+      # bail (moxml#281 — the record table has no error channel, so a
+      # fatal dup-attr document parses with on_error never firing),
+      # so the gate names the first release where the drain is
+      # CORRECT, not merely present. Dev floor pins ~> 1.9.238;
+      # older bindings take the callback Parser below.
       NATIVE_SAX_RECORDS =
-        Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.240")
+        Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.242")
 
       # Defined unconditionally: the body self-guards, and call
       # sites must never depend on the layer having loaded

data/lib/moxml/version.rb

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

data/spec/moxml/adapter/leptris_record_driver_spec.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# Worked hot-loop adoption (moxml#279 follow-up): a builder-protocol
+# driver — the shape canon's comparison lane uses — consuming the
+# bulk record table directly via on_sax_records instead of the
+# callback replay. The walker materializes only the strings the
+# builder consumes (one name/value/text get_string each) and
+# reconstructs end events from the records' parent indices, so its
+# event stream is identical to the callback path while allocations
+# land at the consumer-chosen floor.
+#
+# Docs: README "Hot-loop SAX consumption".
+module RecordDriverSpec
+  class Builder
+    attr_accessor :events
+
+    def initialize
+      @events = []
+    end
+
+    def start_element(name, attrs)
+      @events << [:start, name, attrs]
+    end
+
+    def end_element(name)
+      @events << [:end, name]
+    end
+
+    def characters(text)
+      @events << [:chars, text]
+    end
+  end
+
+  class RecordDriver < Moxml::SAX::Handler
+    def initialize(builder)
+      super()
+      @builder = builder
+    end
+
+    def on_sax_records(table)
+      idx_stack = []
+      name_stack = []
+      i = 0
+      count = table.count
+      while i < count
+        while !idx_stack.empty? && table.parent(i) != idx_stack.last
+          idx_stack.pop
+          @builder.end_element(name_stack.pop)
+        end
+        if table.kind(i).zero?
+          name = table.view(i)
+          attrs = []
+          k = table.attr_first(i)
+          last = k + table.attr_count_of(i)
+          while k < last
+            v = table.attr_value(k)
+            attrs << [table.attr_name(k),
+                      table.attr_value_has_ws?(k) ? v.tr("\t\n\r", " ") : v]
+            k += 1
+          end
+          @builder.start_element(name, attrs)
+          idx_stack << i
+          name_stack << name
+        else
+          @builder.characters(table.view(i))
+        end
+        i += 1
+      end
+      @builder.end_element(name_stack.pop) until name_stack.empty?
+      :claimed
+    end
+  end
+
+  class CallbackDriver < Moxml::SAX::Handler
+    attr_reader :events
+
+    def initialize
+      super
+      @events = []
+    end
+
+    def on_start_element(name, attributes = {}, _namespaces = {})
+      @events << [:start, name, attributes.to_a]
+    end
+
+    def on_end_element(name)
+      @events << [:end, name]
+    end
+
+    def on_characters(text)
+      @events << [:chars, text]
+    end
+  end
+end
+
+RSpec.describe "record-driven builder protocol",
+               if: defined?(Leptris::XML::SAX::Records) do
+  let(:context) { Moxml.new(:leptris) }
+  let(:xml) do
+    '<r a="x  y"><item n="1">t1</item><item n="2">t2<b>k</b></item><last/></r>'
+  end
+
+  it "feeds the builder the same stream the callback path produces" do
+    record_events = RecordDriverSpec::Builder.new
+    driver = RecordDriverSpec::RecordDriver.new(record_events)
+    context.sax_parse(xml, driver)
+    walked = record_events.events
+
+    callback_events = RecordDriverSpec::Builder.new
+    callback = RecordDriverSpec::CallbackDriver.new
+    callback_events.events = []
+    bridge = Moxml::Adapter::Leptris::LeptrisSAXBridge.new(callback)
+    Leptris::XML::SAX::Parser.new(bridge).parse(xml)
+
+    expect(walked).to eq(callback.events)
+    expect(walked).to include([:start, "item", [["n", "1"]]])
+    expect(walked).to include([:start, "r", [["a", "x  y"]]])
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: moxml
 version: !ruby/object:Gem::Version
-  version: 0.5.84
+  version: 0.5.86
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-25 00:00:00.000000000 Z
+date: 2026-09-26 00:00:00.000000000 Z
 dependencies: []
 description: |
   Moxml is a unified XML manipulation library that provides a common API
@@ -438,6 +438,7 @@ files:
 - spec/moxml/adapter/entity_restoration_spec.rb
 - spec/moxml/adapter/headed_ox_spec.rb
 - spec/moxml/adapter/leptris_doc_parts_spec.rb
+- spec/moxml/adapter/leptris_record_driver_spec.rb
 - spec/moxml/adapter/leptris_sax_dup_attr_spec.rb
 - spec/moxml/adapter/leptris_sax_records_spec.rb
 - spec/moxml/adapter/leptris_spec.rb