moxml 0.5.84 → 0.5.85

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff836e409dd2cf77368c7b26015e57de1b0af5e0678489e6e10452a6c70cc61a
-  data.tar.gz: a2a09b561505f90fc624089e925c3b41d4ab867668b00fd35f1132787e9dbfde
+  metadata.gz: 0e2ec5341779cd310306935433ce87caceacbf8662ea449582afe042841957a6
+  data.tar.gz: 9425324aad5a99169a737a72d8f3fe73c82cd97112faf66fdbdbc016dccba910
 SHA512:
-  metadata.gz: decb847bc6cfd50e816c916d98c74b837d63e9e38a9b49a2d964333a141a8fafd9e55291f83a52739403ad99126884c2a37928567ac9f4f8fdaae3ca9df37692
-  data.tar.gz: 59be5497f4f1a4d439e86b4138be240b1bcabb370bc6d991d79b92aa64e9a40f0243b29f090d4171fd45146593ed27fc2da29ae2a2a72d0f542919e3e5aecf3b
+  metadata.gz: 55f4eca7d59c175151bc8cd5217ab238323af351ff4a4dc6caf35fe83847905acaf28c1c2d2906811315282d497fbea0f2e6f241260c9c4cf375e63b26a8d2ed
+  data.tar.gz: 0e90df291ceb7d1eb093ea4c204e6e8df0fc8f4d8db2233cc8fd74d7f5f119562aa8e2c14b3239cfbc057c0ed0e0f5f81d505f716951122fd6381c97146b893e

data/README.adoc

@@ -681,6 +681,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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Moxml
-  VERSION = "0.5.84"
+  VERSION = "0.5.85"
 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.85
 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