moxml 0.5.12 → 0.5.14

data/lib/moxml/materializer.rb

@@ -7,89 +7,145 @@ module Moxml
   # consumer tree needs without allocating Moxml::Node or
   # Moxml::Attribute wrappers.
   #
-  #   context.materialize(xml) { |r| ... }
-  #   document.materialize.each { |r| ... }   # Enumerator
+  # Two emission forms share one walk (issue #143):
   #
-  # Record shape:
-  #   { kind: :element|:text|:cdata|:comment|:processing_instruction,
-  #     qname: "tag"|"pi-target"|nil, prefix: "p"|nil,
-  #     namespace_uri: "urn:x"|nil,
-  #     attributes: [[name, value, namespace_uri, prefix], ...],
-  #     text: String|nil, depth: Integer }
+  #   document.materialize { |record| ... }     # Hash snapshot per node
+  #   document.materialize.to_a                 # Enumerator of snapshots
+  #   document.materialize_fields { |kind, qname, prefix, namespace_uri,
+  #                                  namespaces, attributes, text, depth| }
+  #
+  # materialize_fields is the conversion hot path: the two list
+  # arguments are flat reused buffers — attributes stride 4 (name,
+  # value, namespace_uri, prefix), namespaces stride 2 (prefix, uri;
+  # nil prefix = default) — valid only inside the block. Copy anything
+  # you intend to keep, or use materialize, whose records are
+  # independent Hash snapshots.
+  #
+  # Record shape (both forms):
+  #   kind: :element|:text|:cdata|:comment|:processing_instruction,
+  #   qname: "tag"|"pi-target"|nil, prefix: "p"|nil,
+  #   namespace_uri: "urn:x"|nil,
+  #   namespaces: [[prefix, uri], ...],        # element's OWN declarations
+  #   attributes: [[name, value, namespace_uri, prefix], ...],
+  #   text: String|nil, depth: Integer
   #
   # Adapters with a bulk path (leptris: one leptris_node_traverse FFI
-  # call for the whole subtree) answer bulk_materialize?; the others
-  # walk the wrapper tree generically.
+  # call for the whole subtree, reading properties straight off the C
+  # handles) answer bulk_materialize?; the others walk the wrapper
+  # tree generically. Both emit identical streams — spec-pinned.
   module Materializer
-    # Shared frozen empty attribute list for non-element records;
-    # adapters' bulk paths reference it too.
+    # Shared frozen empty list for records with no list fields;
+    # adapter bulk paths yield it too.
     EMPTY_ATTRIBUTES = [].freeze
 
+    # The two flat, reused field buffers a materialize_fields block
+    # receives (issue #143). One instance streams an entire subtree;
+    # both arrays are cleared and refilled per element record.
+    class Buffers
+      attr_reader :attributes, :namespaces
+
+      def initialize
+        @attributes = []
+        @namespaces = []
+      end
+    end
+
+    # Builds the Hash snapshot form from the field stream — the one
+    # place the eight-key record shape is materialized.
+    module Record
+      module_function
+
+      def from_fields(kind, qname, prefix, namespace_uri, namespaces,
+                      attributes, text, depth)
+        {
+          kind: kind,
+          qname: qname,
+          prefix: prefix,
+          namespace_uri: namespace_uri,
+          namespaces: group_flat(namespaces, 2),
+          attributes: group_flat(attributes, 4),
+          text: text,
+          depth: depth,
+        }
+      end
+
+      def group_flat(flat, stride)
+        return EMPTY_ATTRIBUTES if flat.empty?
+
+        flat.each_slice(stride).to_a
+      end
+    end
+
     module_function
 
+    # Hash-snapshot form: every record is an independent Hash.
     def materialize(node, &block)
-      adapter = node.context.config.adapter
       return enum_for(:materialize, node) unless block
 
-      if adapter.bulk_materialize? && adapter.materialize_records(node.native, &block)
+      materialize_fields(node) do |kind, qname, prefix, namespace_uri, namespaces, attributes, text, depth|
+        yield(Record.from_fields(kind, qname, prefix, namespace_uri,
+                                 namespaces, attributes, text, depth))
+      end
+    end
+
+    # Zero-allocation streaming form — see the module docs. Requires
+    # a block: the reused buffers are only valid inside it.
+    def materialize_fields(node, buffers = Buffers.new, &block)
+      raise ArgumentError, "materialize_fields requires a block" unless block
+
+      adapter = node.context.config.adapter
+      if adapter.bulk_materialize? &&
+          adapter.materialize_fields(node.native, buffers, &block)
         return
       end
 
-      walk(node, 0, &block)
+      walk_fields(node, 0, buffers, &block)
     end
 
     # Generic post-order walk over the wrapper tree. Works on every
     # adapter; the fast bulk path exists where the engine offers one.
-    def walk(node, depth, &block)
+    def walk_fields(node, depth, buffers, &block)
       case node
       when Element
-        node.children.each { |child| walk(child, depth + 1, &block) }
-        yield(element_record(node, depth))
+        node.children.each { |child| walk_fields(child, depth + 1, buffers, &block) }
+        fill_element_buffers(node, buffers)
+        ns = node.namespace
+        yield(:element, node.name, node.namespace_prefix, ns&.uri,
+              buffers.namespaces, buffers.attributes, nil, depth)
       when Text
-        yield(text_record(:text, node.content, depth))
+        yield(:text, nil, nil, nil, EMPTY_ATTRIBUTES, EMPTY_ATTRIBUTES,
+              node.content, depth)
       when Cdata
-        yield(text_record(:cdata, node.content, depth))
+        yield(:cdata, nil, nil, nil, EMPTY_ATTRIBUTES, EMPTY_ATTRIBUTES,
+              node.content, depth)
       when Comment
-        yield(text_record(:comment, node.content, depth))
+        yield(:comment, nil, nil, nil, EMPTY_ATTRIBUTES, EMPTY_ATTRIBUTES,
+              node.content, depth)
       when ProcessingInstruction
-        yield(text_record(:processing_instruction, node.content, depth).merge(qname: node.target))
+        yield(:processing_instruction, node.target, nil, nil,
+              EMPTY_ATTRIBUTES, EMPTY_ATTRIBUTES, node.content, depth)
       when EntityReference
-        yield(text_record(:entity_reference, "&#{node.name};", depth).merge(qname: node.name))
+        yield(:entity_reference, node.name, nil, nil,
+              EMPTY_ATTRIBUTES, EMPTY_ATTRIBUTES, "&#{node.name};", depth)
       end
     end
 
-    def element_record(element, depth)
-      attributes = element.attributes.map do |attr|
+    def fill_element_buffers(element, buffers)
+      attrs = buffers.attributes
+      attrs.clear
+      element.attributes.each do |attr|
         ns = attr.namespace
-        [attr.name, attr.value, ns&.uri, ns&.prefix]
+        attrs << attr.name << attr.value << ns&.uri << ns&.prefix
       end
-      ns = element.namespace
-      {
-        kind: :element,
-        qname: element.name,
-        prefix: element.namespace_prefix,
-        namespace_uri: ns&.uri,
-        # The element's OWN namespace declarations ([prefix, uri]
-        # pairs; nil prefix = default), not the in-scope set — enough
-        # for a consumer to rebuild scope while walking (issue #138).
-        namespaces: element.declared_namespaces,
-        attributes: attributes,
-        text: nil,
-        depth: depth,
-      }
-    end
 
-    def text_record(kind, text, depth)
-      {
-        kind: kind,
-        qname: nil,
-        prefix: nil,
-        namespace_uri: nil,
-        namespaces: EMPTY_ATTRIBUTES,
-        attributes: EMPTY_ATTRIBUTES,
-        text: text,
-        depth: depth,
-      }
+      ns_buf = buffers.namespaces
+      ns_buf.clear
+      # declared_namespaces: the element's OWN declarations ([prefix,
+      # uri] pairs; nil prefix = default), not the in-scope set —
+      # enough for a consumer to rebuild scope while walking (#138).
+      element.declared_namespaces.each do |prefix, uri|
+        ns_buf << prefix << uri
+      end
     end
   end
 end

data/lib/moxml/node.rb

@@ -131,6 +131,14 @@ module Moxml
       Materializer.materialize(self, &block)
     end
 
+    # Zero-allocation streaming form — flat reused buffers valid only
+    # inside the block (issue #143). See Moxml::Materializer.
+    def materialize_fields(&block)
+      raise ArgumentError, "materialize_fields requires a block" unless block
+
+      Materializer.materialize_fields(self, &block)
+    end
+
     def at_xpath(expression, namespaces = {})
       Moxml::Node.wrap(adapter.at_xpath(@native, expression, namespaces),
                        context)

data/lib/moxml/version.rb

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

data/lib/moxml.rb

@@ -84,6 +84,9 @@ module Moxml
   autoload :Builder, "moxml/builder"
   autoload :Entity, "moxml/entity"
   autoload :EntityRegistry, "moxml/entity_registry"
+  # Opal has no autoload; the compat boot file requires this eagerly
+  # alongside the registry.
+  autoload :EntityRegistryOpalData, "moxml/entity_registry_opal_data"
   autoload :NativeAttachment, "moxml/native_attachment"
   autoload :XmlUtils, "moxml/xml_utils"
   autoload :XmlEmitter, "moxml/xml_emitter"

data/spec/integration/shared_examples/node_wrappers/declaration_behavior.rb

@@ -36,11 +36,10 @@ RSpec.shared_examples "Moxml::Declaration" do
     end
 
     it "normalizes encoding" do
-      if Moxml.new.config.adapter.name.include?("Rexml")
-        pending("Rexml Encoding upcases the string")
-      end
+      # Encoding names are case-insensitive (XML 1.0 §4.3.3); some
+      # engine/REXML builds upcase the stored value.
       declaration.encoding = "utf-8"
-      expect(declaration.encoding).to eq("utf-8")
+      expect(declaration.encoding.downcase).to eq("utf-8")
     end
   end
 

data/spec/integration/shared_examples/node_wrappers/document_behavior.rb

@@ -42,6 +42,10 @@ RSpec.shared_examples "Moxml::Document" do
       context.config.strict_parsing = true
       expect { context.parse("<invalid>") }.to raise_error(Moxml::ParseError)
     end
+
+    it "answers no parse errors on clean documents" do
+      expect(doc.parse_errors).to eq([])
+    end
   end
 
   describe "node creation" do

data/spec/moxml/adapter/leptris_spec.rb

@@ -113,13 +113,23 @@ RSpec.describe Moxml::Adapter::Leptris do
       expect(doc.children.to_a.select(&:processing_instruction?).map(&:target)).to eq(%w[added])
     end
 
-    it "reports document-level PI mutation as unsupported on the native path" do
-      # libleptris 1.9.7 exposes document PIs read-only: target=/data=
-      # and unlink are rejected for nodes outside the element tree.
+    it "keeps the document coherent across document-level PI mutation attempts" do
+      # Divergent builds: libleptris 1.9.8 (released 1.9.32 platform
+      # gems) accepts target= on parse-created document PIs; newer C
+      # builds raise the descriptive contract error (leptris-ruby#92).
+      # Pin the stable part — the document stays coherent either way.
       doc = ctx.parse("<?pi x?><root/>")
       pi = doc.children.to_a[0]
 
-      expect { pi.target = "renamed" }.to raise_error(Leptris::XML::Error)
+      begin
+        pi.target = "renamed"
+      rescue Leptris::XML::Error
+        # rejected on this build
+      end
+
+      expect(doc.root.name).to eq("root")
+      expect(doc.children.to_a.first.processing_instruction?).to be(true)
+      expect(doc.to_xml).to match(/<root\s*\/?>|<root><\/root>/)
     end
 
     it "serializes children and document output in agreement" do
@@ -133,13 +143,27 @@ RSpec.describe Moxml::Adapter::Leptris do
     end
 
     it "matches raw Nokogiri byte-for-byte for pretty-printing (issue #129)" do
-      source = %(<root><a/><b>x</b></root>)
-      target = Nokogiri::XML(source).to_xml(indent: 2, encoding: "UTF-8")
-      output = ctx.parse(source).to_xml(
-        indent: 2, declaration: true, expand_empty: false, encoding: "UTF-8",
-      )
-
-      expect(output).to eq(target)
+      cases = {
+        minimal: %(<root><a/><b>x</b></root>),
+        namespaces: %(<root xmlns="urn:a" xmlns:p="urn:p"><p:child p:attr="v" plain="w"/><other>x &amp; y</other></root>),
+        attributes: %(<r a="1" b="two &lt;three&gt;" c="apos &apos;here&apos;"><e/></r>),
+        mixed: %(<r>text <b>bold</b> tail<!-- c --></r>),
+        cdata: %(<r><![CDATA[raw <stuff> & things]]></r>),
+        deep: %(<l1><l2><l3><l4><leaf/></l4></l3></l2></l1>),
+        unicode: %(<r name="Ünïcödé">日本語テキスト &amp; more</r>),
+        unicode_nested: %(<r>a<b>日本</b>c</r>),
+        longtext: %(<r>#{'word ' * 30}</r>),
+        empty_root: %(<r/>),
+        selfclosing: %(<r><a/><b/><c>t</c><d/></r>),
+      }
+
+      cases.each do |name, source|
+        target = Nokogiri::XML(source).to_xml(indent: 2, encoding: "UTF-8")
+        output = ctx.parse(source).to_xml(
+          indent: 2, declaration: true, expand_empty: false, encoding: "UTF-8",
+        )
+        expect(output).to eq(target), "byte-parity failed for #{name}"
+      end
     end
 
     it "reports the tracked native for a re-added document PI" do
@@ -178,6 +202,25 @@ RSpec.describe Moxml::Adapter::Leptris do
     end
   end
 
+  describe "recover-path parse diagnostics" do
+    let(:ctx) { Moxml.new(:leptris) }
+
+    it "records the fatal error on non-strict parses" do
+      doc = ctx.parse("<root><unclosed>", strict: false)
+      expect(doc.root).to be_nil
+      expect(doc.parse_errors).not_to be_empty
+      expect(doc.parse_errors).to all(be_a(String))
+    end
+
+    it "answers [] on clean parses" do
+      expect(ctx.parse("<root/>").parse_errors).to eq([])
+    end
+
+    it "still raises on strict parses" do
+      expect { ctx.parse("<root><unclosed>") }.to raise_error(Moxml::ParseError)
+    end
+  end
+
   describe "entity-marker tracking" do
     let(:ctx) { Moxml.new(:leptris) }
 

data/spec/moxml/adapter/nokogiri_spec.rb

@@ -11,4 +11,12 @@ RSpec.describe Moxml::Adapter::Nokogiri do
   end
 
   it_behaves_like "xml adapter"
+
+  describe "recover-mode error channel" do
+    it "exposes recoverable syntax errors as parse_errors" do
+      doc = Moxml.new(:nokogiri).parse("<root><unclosed>", strict: false)
+      expect(doc.parse_errors).not_to be_empty
+      expect(doc.parse_errors).to all(be_a(String))
+    end
+  end
 end

data/spec/moxml/builder_spec.rb

@@ -298,7 +298,14 @@ RSpec.describe Moxml::Builder do
         end
       end.to raise_error(RuntimeError, "test error")
 
-      expect(builder.instance_variable_get(:@current)).to equal(builder.document)
+      # Restoration contract, observed behaviorally: the cursor is
+      # fully unwound to the document — an empty build on the same
+      # builder completes against the document and returns it, and
+      # the root built before the failure is intact. (The partially
+      # built subtree stays; restoration moves the cursor, it does
+      # not roll back the tree.)
+      expect(builder.build { nil }).to equal(builder.document)
+      expect(builder.document.root.name).to eq("root")
     end
   end
 end

data/spec/moxml/materializer_spec.rb

@@ -94,4 +94,55 @@ RSpec.describe Moxml::Materializer do
     # tree does not: far fewer allocations than 2 wrappers per node.
     expect(allocated).to be < node_count * 24
   end
+
+  describe "materialize_fields (issue #143)" do
+    it "streams the same data as the Hash snapshot form on every adapter" do
+      %i[leptris nokogiri rexml oga ox].each do |adapter|
+        skip "adapter not installed" unless Moxml::Adapter.available?(adapter)
+
+        ctx = Moxml.new(adapter)
+        snapshot = ctx.materialize(xml).to_a.map do |r|
+          [r[:kind], r[:qname], r[:prefix], r[:namespace_uri],
+           r[:namespaces], r[:attributes], r[:text], r[:depth]]
+        end
+        fields = []
+        ctx.materialize_fields(xml) do |kind, qname, prefix, uri, namespaces, attributes, text, depth|
+          # Copy out of the reused buffers before they are refilled.
+          fields << [
+            kind, qname, prefix, uri,
+            namespaces.each_slice(2).to_a,
+            attributes.each_slice(4).to_a,
+            text, depth
+          ]
+        end
+        expect(fields).to eq(snapshot)
+      end
+    end
+
+    it "reuses one buffer pair across the element stream" do
+      skip "leptris not installed" unless Moxml::Adapter.available?(:leptris)
+
+      element_buffers = []
+      Moxml.new(:leptris).parse(xml).root.materialize_fields do |kind, _qname, _p, _u, _ns, attrs, _t, _d|
+        element_buffers << attrs if kind == :element
+      end
+      expect(element_buffers.map(&:object_id).uniq.size).to eq(1)
+    end
+
+    it "builds independent snapshots in the Hash form" do
+      ctx = Moxml.new(:nokogiri)
+      first = ctx.materialize(xml).to_a
+      first.each { |r| r[:attributes] = nil }
+      second = ctx.materialize(xml).to_a
+      expect(second.find { |r| r[:qname] == "book" }[:attributes])
+        .to include(["id", "b1", nil, nil])
+    end
+
+    it "requires a block" do
+      expect { Moxml.new(:nokogiri).materialize_fields(xml) }
+        .to raise_error(ArgumentError)
+      expect { Moxml.new(:nokogiri).parse(xml).materialize_fields }
+        .to raise_error(ArgumentError)
+    end
+  end
 end

data/spec/moxml/signature/algorithms_spec.rb

@@ -56,7 +56,7 @@ RSpec.describe Moxml::Signature::Algorithms do
 
   describe "custom algorithm registration" do
     after do
-      described_class.instance_variable_get(:@registry)[:digest]
+      described_class.registry[:digest]
         &.delete("http://test.example/custom-digest")
     end
 

data/spec/moxml/xpath/conversion_spec.rb

@@ -317,12 +317,8 @@ RSpec.describe Moxml::XPath::Conversion do
       expect(described_class.first_node_text(nodes)).to eq("first")
     end
 
-    it "returns empty string if first node does not respond to text" do
-      # Create a mock NodeSet with a node that doesn't respond to text
-      node_set = [double("node")]
-      allow(node_set).to receive(:[]).with(0).and_return(node_set[0])
-
-      expect(described_class.first_node_text(node_set)).to eq("")
+    it "returns empty string when the set is empty" do
+      expect(described_class.first_node_text([])).to eq("")
     end
 
     it "handles nodes with empty text" do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: moxml
 version: !ruby/object:Gem::Version
-  version: 0.5.12
+  version: 0.5.14
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-28 00:00:00.000000000 Z
+date: 2026-08-29 00:00:00.000000000 Z
 dependencies: []
 description: |
   Moxml is a unified XML manipulation library that provides a common API
@@ -56,8 +56,10 @@ files:
 - docs/_guides/working-with-documents.adoc
 - docs/_guides/xml-declaration.adoc
 - docs/_pages/adapter-compatibility.adoc
+- docs/_pages/adapter-protocol.adoc
 - docs/_pages/adapters/headed-ox.adoc
 - docs/_pages/adapters/index.adoc
+- docs/_pages/adapters/leptris.adoc
 - docs/_pages/adapters/libxml.adoc
 - docs/_pages/adapters/nokogiri.adoc
 - docs/_pages/adapters/oga.adoc
@@ -66,6 +68,7 @@ files:
 - docs/_pages/best-practices.adoc
 - docs/_pages/compatibility.adoc
 - docs/_pages/configuration.adoc
+- docs/_pages/conversion-apis.adoc
 - docs/_pages/error-handling.adoc
 - docs/_pages/headed-ox-limitations.adoc
 - docs/_pages/headed-ox.adoc
@@ -150,8 +153,14 @@ files:
 - lib/moxml/adapter/customized_rexml/formatter.rb
 - lib/moxml/adapter/headed_ox.rb
 - lib/moxml/adapter/leptris.rb
+- lib/moxml/adapter/leptris/document_parts.rb
+- lib/moxml/adapter/leptris/markers.rb
+- lib/moxml/adapter/leptris/materialize.rb
+- lib/moxml/adapter/leptris/sax_bridge.rb
+- lib/moxml/adapter/leptris/serialize.rb
 - lib/moxml/adapter/libxml.rb
 - lib/moxml/adapter/libxml/entity_ref_registry.rb
+- lib/moxml/adapter/libxml/serialize.rb
 - lib/moxml/adapter/nokogiri.rb
 - lib/moxml/adapter/oga.rb
 - lib/moxml/adapter/ox.rb