moxml 0.5.13 → 0.5.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f890c98078986e7be37d59762c08c6387cb173a7260212be428c705e043bd1a
-  data.tar.gz: 6a5dae862bb917c2906581412c33f0cd9f4506112ba5f24a146feed9f2dc0371
+  metadata.gz: 8302b1a98c08b34619df4a30d5b84733fa9125eebeeaf1b39b5ba82d0e8fa625
+  data.tar.gz: e96034377b072b1ee9058ced4a4dd0347e819f6354011810831b07a06e88e138
 SHA512:
-  metadata.gz: d8acaee20452b9d74ba026cc4fce32d6a8911af51afee523bf474e831786d9e71c31e089360d023c17a62c8610081a8ad4d55b774261279e56966942ab26b040
-  data.tar.gz: c9e1d227bca2d9f7f5771604de905b5efec5a61451e01b69919ec315484673cafadbe65345423fd65633fcdc1d8e8197de58d6822f5bc42a6fa6fe253ec4b7f3
+  metadata.gz: bbe5b80c8b6a656e14b45307bf9b41d1ba1a384c33906ed11fc7d861c2f8fbfad33fb08f2b091ea8b295608c025b5045bc6d0ff73927420e07a23635750fec38
+  data.tar.gz: 994ca51d9e27649ef6d70d2f225408dafdd73e35d5948903e33c978b75c5523d5c11ce889c361ded3c7af74473fe75b107168df5f6ab88ec4af5841f5f530ebf

data/.rubocop.yml

@@ -18,3 +18,12 @@ AllCops:
     - 'tmp/**/*'
     - 'spec/consistency/round_trip_spec.rb'
     - 'lib/compat/**/*'
+
+# materialize_fields yields the eight record fields positionally —
+# the zero-allocation streaming form (issue #143). One parameter per
+# record key is the interface; a shorter list would need a wrapper
+# object, which is the allocation the API exists to avoid.
+Metrics/ParameterLists:
+  Exclude:
+    - 'lib/moxml/materializer.rb'
+    - 'spec/moxml/materializer_spec.rb'

data/docs/_pages/adapter-protocol.adoc

@@ -23,7 +23,9 @@ Parse and document lifecycle::
 `create_native_comment`, `create_native_processing_instruction`,
 `create_native_declaration`, `create_native_doctype`,
 `create_native_entity_reference`, `create_native_namespace`),
-`free_document` (#134; no-op on GC-managed engines).
+`free_document` (#134; no-op on GC-managed engines), `parse_errors`
+(#147; recover-mode diagnostics — `[]` on clean parses; engines with
+an error channel map it here, e.g. Nokogiri's `doc.errors`).
 
 Tree navigation::
 `children`, `parent`, `next_sibling`, `previous_sibling`, `root`,
@@ -79,11 +81,13 @@ post-serialize restore scan.
 
 `bulk_materialize?`::
 Whether the adapter offers a bulk path for `Moxml::Materializer`;
-`materialize_records` yields flattened records, returning nil falls
-back to the generic wrapper walk.
+`materialize_fields` fills the reused flat buffers and yields the
+eight record fields per node, returning nil falls back to the
+generic wrapper walk. Leptris walks raw C pointers with the batch
+`leptris_node_children` call — no wrappers, no per-node callback.
 
 Constants like `DOC_NODE_SUPPORTED` / `DTDATTR_SUPPORTED` /
-`TRAVERSE_SUBTREE_BOUNDED` (Leptris) follow the same idea: one probe
+`BULK_FIELD_READS` (Leptris) follow the same idea: one probe
 per engine capability, computed at load.
 
 == Return shapes

data/docs/_pages/adapters/leptris.adoc

@@ -61,6 +61,11 @@ implementation over one `leptris_node_traverse` call.
 
 * Tab indentation (`indent_text`) needs a serialize-time parameter in
   libleptris; post-hoc rewriting would corrupt mixed content.
+* Child PIs serialize inline (engine emits `<r>\n<?pi x?>  <e/>`
+  rather than libxml2's one-PI-per-indented-line layout); safe
+  post-hoc rewriting is impossible in mixed content.
+* DOCTYPE internal subsets serialize inline; libxml2 separates the
+  declarations with newlines.
 * Document-level PIs are read-only natives (`target=`/`data=`/
   `unlink` rejected); write-through and removal are pending C
   surface (leptris/leptris#612).

data/docs/_pages/conversion-apis.adoc

@@ -9,7 +9,9 @@ Scanned streaming (`materialize`), deterministic release (`Document#free`), and
 
 == Bulk materialization — `materialize` (issue #132)
 
-Flattened, post-order records for a subtree with no `Moxml::Node` allocation — the conversion path for consumers that build their own tree from a document:
+Flattened, post-order records for a subtree with no `Moxml::Node`
+allocation — the conversion path for consumers that build their own
+tree from a document:
 
 [source,ruby]
 ----
@@ -18,7 +20,7 @@ document.materialize.each                    # Enumerator, root subtree
 any_element.materialize                      # any subtree
 ----
 
-Record shape (all seven keys on every record):
+Record shape (all eight keys on every record):
 
 [source,ruby]
 ----
@@ -34,9 +36,32 @@ Record shape (all seven keys on every record):
 
 * Post-order: children arrive before their parent — build with a stack.
 * `Document#materialize` yields exactly the root subtree (issue #140); document-level parts (prolog/epilog PIs and comments, DOCTYPE) stay enumerable via `children`.
-* The leptris adapter has a bulk path (one `leptris_node_traverse` call); every other adapter uses the generic wrapper walk. Both emit identical streams — the parity is spec-pinned.
+* Every record is an independent Hash snapshot — safe to retain.
 * Entity-bearing documents fall back to the generic walk so entity references still split.
 
+=== The streaming form — `materialize_fields` (issue #143)
+
+The conversion hot path: the same walk with zero per-record
+allocation. The block receives the eight fields positionally, and the
+two list arguments are flat, reused buffers:
+
+[source,ruby]
+----
+context.materialize_fields(xml) do |kind, qname, prefix, uri,
+                                namespaces, attributes, text, depth|
+  # namespaces: flat [prefix, uri, ...]            (stride 2)
+  # attributes: flat [name, value, uri, prefix, ...] (stride 4)
+end
+----
+
+The buffers are refilled per element record — valid only inside the
+block. Copy what you keep, or use `materialize` (which layers a fresh
+Hash snapshot on this same stream). On CRuby + leptris the walk runs
+over raw C pointers with the batch `leptris_node_children` call — no
+wrapper objects, no per-node FFI callback, no depth bookkeeping;
+measured ~1.2x faster than an equivalent raw-Nokogiri DOM walk.
+Requires a block (raises `ArgumentError` otherwise).
+
 == Deterministic release — `Document#free` (issue #134)
 
 Adapters backed by C trees hold native memory until a GC finalizer runs. Batch workloads (parse → convert → discard, thousands of documents) release it deterministically:

data/lib/compat/opal/moxml_boot.rb

@@ -24,6 +24,7 @@ require "moxml/namespace"
 require "moxml/doctype"
 require "moxml/entity_reference"
 require "moxml/entity_registry"
+require "moxml/entity_registry_opal_data"
 require "moxml/entity"
 require "moxml/entity/restorer"
 require "moxml/entity/reference"

data/lib/moxml/adapter/base.rb

@@ -190,14 +190,19 @@ namespace_validation_mode: :strict)
         end
 
         # Whether the engine offers a bulk materialization path for
-        # Materializer (issue #132). When true, materialize_records
-        # yields flattened records for the subtree; returning nil
-        # (e.g. for document shapes the bulk path cannot express)
-        # falls back to the generic wrapper walk.
+        # Materializer (issue #132). When true, the adapter gets
+        # #materialize_fields(native, buffers, &block) — fill the
+        # reused flat buffers and yield the eight record fields per
+        # node. Returning nil (e.g. for document shapes the bulk path
+        # cannot express) falls back to the generic wrapper walk.
         def bulk_materialize?
           false
         end
 
+        def materialize_fields(_native, _buffers)
+          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
@@ -206,6 +211,15 @@ namespace_validation_mode: :strict)
           nil
         end
 
+        # Recover-mode parse diagnostics (issue #147): the error
+        # messages the engine recorded while parsing, [] when the
+        # parse was clean. Engines with a native recover channel
+        # (Nokogiri's `doc.errors`) or a non-strict path that loses
+        # the raised error (leptris) override this.
+        def parse_errors(_native_doc)
+          []
+        end
+
         # Check if the native document has an XML declaration
         # @param native_doc the native document object
         # @param wrapper [Moxml::Document] the wrapper with has_xml_declaration flag

data/lib/moxml/adapter/leptris/materialize.rb

@@ -4,105 +4,135 @@ module Moxml
   module Adapter
     class Leptris
       module Materialize
-        # Bulk materialization (issue #132): leptris_node_traverse
-        # walks the subtree with one FFI call; the only per-node cost
-        # is the C->Ruby callback and the property reads below. No
-        # Moxml::Node or Attribute wrapper is allocated.
+        BINDING_FFI = ::Leptris::XML::FFI
+        private_constant :BINDING_FFI
+
+        EMPTY_FIELDS = Materializer::EMPTY_ATTRIBUTES
+
+        NODE_ELEMENT = ::Leptris::XML::FFI::NODE_ELEMENT
+        NODE_TEXT = ::Leptris::XML::FFI::NODE_TEXT
+        NODE_COMMENT = ::Leptris::XML::FFI::NODE_COMMENT
+        NODE_CDATA = ::Leptris::XML::FFI::NODE_CDATA
+        NODE_PI = ::Leptris::XML::FFI::NODE_PI
+        private_constant :NODE_ELEMENT, :NODE_TEXT, :NODE_COMMENT, :NODE_CDATA,
+                         :NODE_PI
+
+        # Reused child-pointer staging buffer capacity for the raw
+        # pointer walk. Elements with more children grow the buffer
+        # geometrically for the rest of the stream.
+        CHILDREN_CAPACITY = 64
+        private_constant :CHILDREN_CAPACITY
+
+        # Bulk materialization (issues #132/#143): a Ruby-side
+        # post-order recursion over RAW C pointers — no binding
+        # wrapper per node, no per-node FFI callback, no depth memo
+        # (depth is a recursion parameter), no record allocation.
+        # Child lists arrive through the batch leptris_node_children
+        # call; element fields are read straight off the C handles
+        # (the binding's own first/next attribute iteration face),
+        # skipping the per-attribute wrapper its public API
+        # allocates. The unprefixed-attribute namespace read is
+        # skipped because the answer is nil by definition
+        # (no-namespace attributes).
         def bulk_materialize?
           true
         end
 
-        def materialize_records(native, &block)
+        def materialize_fields(native, buffers, &block)
+          return nil unless Leptris::BULK_FIELD_READS
+
           doc = native.is_a?(::Leptris::XML::Document) ? native : native.document
           # Marker-bearing text needs the split pipeline (children-level
           # ER expansion); the bulk path has no marker handling.
           return nil if doc.nil? || attachments.get(doc, :entity_markers)
 
-          # On bindings whose traverse follows the document chain
-          # (leptris 1.9.28–1.9.31), element materialize falls back to
-          # the generic wrapper walk — only document materialization
-          # can filter safely there (issue #140).
-          root = if native.is_a?(::Leptris::XML::Document)
-                   doc.root
-                 else
-                   return nil unless TRAVERSE_SUBTREE_BOUNDED
-
-                   native
-                 end
-          return nil if root.nil?
-
-          depth_memo = {}.compare_by_identity
-          root.traverse do |node|
-            depth = material_depth_in_subtree(node, root, depth_memo)
-            next if depth.nil?
-
-            record = case node
-                     when ::Leptris::XML::Element
-                       element_material_record(node, depth)
-                     when ::Leptris::XML::CDATA
-                       # CDATA < Text in the binding: this arm must come
-                       # first or CDATA content reports as text.
-                       text_material_record(:cdata, node.content, depth)
-                     when ::Leptris::XML::Text
-                       text_material_record(:text, node.content, depth)
-                     when ::Leptris::XML::Comment
-                       text_material_record(:comment, node.content, depth)
-                     when ::Leptris::XML::ProcessingInstruction
-                       text_material_record(:processing_instruction, node.content, depth)
-                         .merge(qname: node.target)
+          root_ptr = if native.is_a?(::Leptris::XML::Document)
+                       doc.root&.c_ptr
+                     else
+                       native.c_ptr
                      end
-            yield(record) if record
-          end
+          return nil unless root_ptr
+
+          walk_fields(root_ptr, 0, buffers,
+                      ::FFI::MemoryPointer.new(:pointer, CHILDREN_CAPACITY),
+                      &block)
           true
         end
 
-        def element_material_record(node, depth)
-          attributes = node.each_attribute.map do |attr|
-            # Local name + separate prefix, matching the generic
-            # path's resolver semantics (moxml's canonical shape).
-            name = attr.name
-            prefix = attr.prefix
-            name = name.split(":", 2)[1] || name if prefix
-            [name, attr.value, attr.namespace_uri, prefix]
+        def walk_fields(ptr, depth, buffers, child_buf, &block)
+          f = BINDING_FFI
+          capacity = CHILDREN_CAPACITY
+          count = f.leptris_node_children(ptr, child_buf, capacity)
+          while count == capacity
+            capacity *= 4
+            child_buf = ::FFI::MemoryPointer.new(:pointer, capacity)
+            count = f.leptris_node_children(ptr, child_buf, capacity)
           end
-          ns = node.namespace
-          # Own declarations only — same shape as the generic
-          # path's Element#declared_namespaces (issue #138).
-          decls = node.namespace_definitions.map { |d| [d.prefix, d.href] }
-          Materializer::Record.element(
-            qname: node.name,
-            prefix: node.prefix,
-            namespace_uri: ns&.href,
-            namespaces: decls.empty? ? Materializer::EMPTY_ATTRIBUTES : decls,
-            attributes: attributes,
-            depth: depth,
-          )
-        end
 
-        def text_material_record(kind, text, depth)
-          Materializer::Record.text(kind: kind, text: text, depth: depth)
+          # Snapshot before recursing — the recursion reuses this
+          # buffer for the next level's child list.
+          children = child_buf.read_array_of_pointer(count)
+
+          children.each do |child|
+            case f.leptris_node_get_type(child)
+            when NODE_ELEMENT
+              walk_fields(child, depth + 1, buffers, child_buf, &block)
+            when NODE_TEXT
+              yield(:text, nil, nil, nil, EMPTY_FIELDS, EMPTY_FIELDS, f.leptris_text_node_get_content(child), depth + 1)
+            when NODE_CDATA
+              yield(:cdata, nil, nil, nil, EMPTY_FIELDS, EMPTY_FIELDS, f.leptris_cdata_node_get_content(child), depth + 1)
+            when NODE_COMMENT
+              yield(:comment, nil, nil, nil, EMPTY_FIELDS, EMPTY_FIELDS, f.leptris_comment_node_get_content(child), depth + 1)
+            when NODE_PI
+              yield(:processing_instruction, f.leptris_pi_node_get_target(child), nil, nil, EMPTY_FIELDS, EMPTY_FIELDS, f.leptris_pi_node_get_data(child), depth + 1)
+            end
+          end
+
+          emit_element_fields(ptr, buffers, depth, &block)
         end
 
-        # Depth relative to the subtree root, or nil when the node
-        # lies outside it (traverse follows the document chain since
-        # leptris 1.9.28, so epilog siblings can appear in the
-        # stream). Binding wrappers are address-stable and #parent is
-        # memoized, so each edge resolves once through the
-        # identity-keyed memo.
-        def material_depth_in_subtree(node, root, memo)
-          memo[node] ||= if node.equal?(root)
-                           0
-                         else
-                           parent = node.parent
-                           if parent.nil? || parent.is_a?(::Leptris::XML::Document)
-                             nil
-                           else
-
-                             parent_depth = material_depth_in_subtree(parent, root, memo)
-                             parent_depth.nil? ? nil : parent_depth + 1
-
-                           end
-                         end
+        def emit_element_fields(ptr, buffers, depth, &block)
+          f = BINDING_FFI
+          ns_buf = buffers.namespaces
+          attrs_buf = buffers.attributes
+
+          name = f.leptris_element_name(ptr)
+          prefix = f.leptris_element_prefix(ptr)
+          uri = f.leptris_element_namespace(ptr)
+          uri = nil if uri && uri.empty?
+
+          # Own declarations only — same shape as the generic path's
+          # Element#declared_namespaces (issue #138).
+          ns_buf.clear
+          i = 0
+          ns_count = f.leptris_element_namespace_count(ptr)
+          while i < ns_count
+            ns_buf << f.leptris_element_namespace_decl_prefix(ptr, i)
+            ns_buf << f.leptris_element_namespace_decl_uri(ptr, i)
+            i += 1
+          end
+
+          attrs_buf.clear
+          attr = f.leptris_element_first_attribute(ptr)
+          until attr.nil? || attr.null?
+            attr_name = f.leptris_attribute_get_name(attr)
+            attr_value = f.leptris_attribute_get_value(ptr, attr)
+            colon = attr_name.index(":")
+            if colon
+              attr_prefix = attr_name[0, colon]
+              # Local name + separate prefix, matching the generic
+              # path's resolver semantics (moxml's canonical shape).
+              attr_name = attr_name[(colon + 1)..]
+              attr_uri = f.leptris_attribute_namespace_uri(attr)
+            else
+              attr_prefix = nil
+              attr_uri = nil
+            end
+            attrs_buf << attr_name << attr_value << attr_uri << attr_prefix
+            attr = f.leptris_attribute_next(attr)
+          end
+
+          yield(:element, name, prefix, uri, ns_buf, attrs_buf, nil, depth)
         end
       end
     end

data/lib/moxml/adapter/leptris/serialize.rb

@@ -33,7 +33,11 @@ module Moxml
           # Entity restoration belongs to the wrapper layer
           # (Node#to_xml runs adapter.restore_entities for every
           # adapter); doing it here scanned the output a second time.
-          normalize_serialization(raw_serialize(node, options), options)
+          xml = normalize_serialization(raw_serialize(node, options), options)
+          # The binding's FFI strings come back binary-tagged; the
+          # engine encoded the bytes per this option, so tag them.
+          xml.force_encoding(options[:encoding]) if options[:encoding]
+          xml
         end
 
         def raw_serialize(node, options)
@@ -59,11 +63,15 @@ module Moxml
           include_decl = options.fetch(:declaration) do
             options[:no_declaration] ? false : document_has_declaration?(node)
           end
-          node.to_xml(
+          xml = node.to_xml(
             indent: options.fetch(:indent, 0),
             no_decl: !include_decl,
             encoding: options[:encoding],
           )
+          # Element output always ends with the close tag — but the
+          # engine's serializer appends a stray trailing newline when
+          # the element's last text child is non-ASCII.
+          xml.sub(/\n+\z/, "")
         end
 
         def normalize_serialization(xml, options)

data/lib/moxml/adapter/leptris.rb

@@ -27,12 +27,24 @@ module Moxml
       # DTD ATTLIST defaults, matching libxml2/Nokogiri semantics;
       # ParseOptions::DTDATTR opts in (leptris/leptris#606).
       DTDATTR_SUPPORTED = ::Leptris::XML::ParseOptions.const_defined?(:DTDATTR)
-      # leptris-ruby 1.9.32 (#89): traverse is subtree-bounded again —
-      # earlier 1.9.x walks followed the document chain and swept
-      # following siblings, so element materialize had to fall back
-      # to the generic wrapper walk.
-      TRAVERSE_SUBTREE_BOUNDED =
-        Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.32")
+
+      # The raw field-read surface for the bulk materializer (issue
+      # #143). Bindings without the full set fall back to the generic
+      # wrapper walk.
+      BULK_FIELD_READS = %i[
+        leptris_node_children leptris_node_get_type
+        leptris_element_name leptris_element_prefix leptris_element_namespace
+        leptris_element_namespace_count leptris_element_namespace_decl_prefix
+        leptris_element_namespace_decl_uri leptris_element_first_attribute
+        leptris_attribute_get_name leptris_attribute_get_value
+        leptris_attribute_next leptris_attribute_namespace_uri
+        leptris_text_node_get_content leptris_cdata_node_get_content
+        leptris_comment_node_get_content leptris_pi_node_get_target
+        leptris_pi_node_get_data
+      ].all? { |fn| ::Leptris::XML::FFI.respond_to?(fn) }
+
+      NO_PARSE_ERRORS = [].freeze
+      private_constant :NO_PARSE_ERRORS
 
       # Cohesive clusters extracted from this class — the adapter
       # protocol surface is unchanged; the modules hold the document
@@ -77,9 +89,12 @@ module Moxml
           rescue ::Leptris::XML::ParseError => e
             # libleptris has no recovery mode that survives unclosed
             # tags; non-strict callers get an empty document, matching
-            # the Libxml adapter's non-strict behavior.
+            # the Libxml adapter's non-strict behavior. The fatal
+            # error rides the document as parse diagnostics (issue
+            # #147) — otherwise nothing says why it came back empty.
             raise Moxml::ParseError.new(e.message) if options[:strict]
 
+            recover_errors = [e.message]
             create_document
           end
           ctx = _context || Context.new(:leptris)
@@ -87,6 +102,7 @@ module Moxml
 
           record_source_declaration(native_doc, processed)
           attachments.set(native_doc, :entity_markers, entity_markers)
+          attachments.set(native_doc, :parse_errors, recover_errors) if recover_errors
 
           doc
         end
@@ -99,6 +115,10 @@ module Moxml
           ::Leptris::XML::ParseOptions.dtdattr
         end
 
+        def parse_errors(native_doc)
+          attachments.get(native_doc, :parse_errors) || NO_PARSE_ERRORS
+        end
+
         def create_document(_native_doc = nil)
           ::Leptris::XML::Document.create
         end
@@ -685,6 +705,7 @@ module Moxml
             ast = XPath::Parser.parse_with_cache(expression)
             next false if ast_contains_type?(ast, :variable)
             next false if uses_xmlns_prefix?(ast)
+            next false if prefixed_attribute_test?(ast)
 
             !selects_attribute_results?(ast)
           end
@@ -724,6 +745,24 @@ module Moxml
           end
         end
 
+        # Some released native engines do not match prefixed attribute
+        # tests inside predicates (@p:kind='a'); the Ruby engine does.
+        # An attribute test is a :test whose parent axis is
+        # "attribute"; bare ones (namespace nil) stay native.
+        def prefixed_attribute_test?(ast, parent_axis = nil)
+          if ast.type == :test && parent_axis == "attribute"
+            ns = ast.value[:namespace]
+            return true if ns && !ns.empty? && ns != "xmlns"
+          end
+
+          axis = ast.children.first if ast.type == :axis
+
+          ast.children.any? do |child|
+            child.is_a?(XPath::AST::Node) &&
+              prefixed_attribute_test?(child, axis || (child.type == :axis ? nil : parent_axis))
+          end
+        end
+
         def engine_xpath(node, expression, namespaces = {})
           unless node.is_a?(Moxml::Node)
             node = Moxml::Node.wrap(node, Context.new(:leptris))

data/lib/moxml/adapter/nokogiri.rb

@@ -43,6 +43,13 @@ module Moxml
           Document.new(native_doc, ctx)
         end
 
+        # Nokogiri parses with `config.recover` unless strict, so
+        # recoverable syntax errors land on `doc.errors` instead of
+        # raising (issue #147).
+        def parse_errors(native_doc)
+          native_doc.errors.map(&:message)
+        end
+
         # SAX parsing implementation for Nokogiri
         #
         # @param xml [String, IO] XML to parse

data/lib/moxml/context.rb

@@ -81,6 +81,14 @@ module Moxml
       parse(xml, options).materialize(&block)
     end
 
+    # Parse then stream the zero-allocation field form (issue #143) —
+    # see Moxml::Materializer.
+    def materialize_fields(xml, options = {}, &block)
+      raise ArgumentError, "materialize_fields requires a block" unless block
+
+      parse(xml, options).materialize_fields(&block)
+    end
+
     # Parse XML using SAX (event-driven) parsing
     #
     # SAX parsing is memory-efficient and suitable for large XML files.

data/lib/moxml/document.rb

@@ -31,6 +31,14 @@ module Moxml
       root&.materialize(&block)
     end
 
+    # Zero-allocation streaming form over the root subtree (issue
+    # #143) — see Moxml::Materializer.
+    def materialize_fields(&block)
+      raise ArgumentError, "materialize_fields requires a block" unless block
+
+      root&.materialize_fields(&block)
+    end
+
     # Deterministically release the adapter's native memory for this
     # document (issue #134) — batch workloads parsing thousands of
     # documents otherwise hold C trees until GC finalizers run.
@@ -42,6 +50,16 @@ module Moxml
       nil
     end
 
+    # Parse diagnostics from the engine's recover path (issue #147):
+    # [] when the parse was clean, otherwise the recorded error
+    # messages. A non-strict leptris parse that came back empty
+    # reports the fatal error that emptied it; Nokogiri reports its
+    # recover-mode syntax errors; engines without an error channel
+    # answer [].
+    def parse_errors
+      adapter.parse_errors(@native)
+    end
+
     def create_element(name)
       Element.new(adapter.create_element(name, owner_doc: @native), context)
     end

data/lib/moxml/entity_registry.rb

@@ -2,7 +2,6 @@
 
 require "json" unless RUBY_ENGINE == "opal"
 require "set"
-require_relative "entity_registry_opal_data" if RUBY_ENGINE == "opal"
 
 module Moxml
   # EntityRegistry maintains a knowledge base of XML entity definitions.

data/lib/moxml/materializer.rb

@@ -7,111 +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 one constructor for the record shape — both the generic
-    # walk and adapter bulk paths build records through it, so the
-    # seven-key contract lives in exactly one place.
+    # 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 element(qname:, prefix:, namespace_uri:, namespaces:, attributes:, depth:)
+      def from_fields(kind, qname, prefix, namespace_uri, namespaces,
+                      attributes, text, depth)
         {
-          kind: :element,
+          kind: kind,
           qname: qname,
           prefix: prefix,
           namespace_uri: namespace_uri,
-          namespaces: namespaces,
-          attributes: attributes,
-          text: nil,
+          namespaces: group_flat(namespaces, 2),
+          attributes: group_flat(attributes, 4),
+          text: text,
           depth: depth,
         }
       end
 
-      def text(kind:, text:, depth:)
-        {
-          kind: kind,
-          qname: nil,
-          prefix: nil,
-          namespace_uri: nil,
-          namespaces: EMPTY_ATTRIBUTES,
-          attributes: EMPTY_ATTRIBUTES,
-          text: text,
-          depth: depth,
-        }
+      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
+
+      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).
-      Record.element(
-        qname: element.name,
-        prefix: element.namespace_prefix,
-        namespace_uri: ns&.uri,
-        namespaces: element.declared_namespaces,
-        attributes: attributes,
-        depth: depth,
-      )
-    end
-
-    def text_record(kind, text, depth)
-      Record.text(kind: kind, text: text, depth: depth)
+      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.13"
+  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

@@ -143,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
@@ -188,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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: moxml
 version: !ruby/object:Gem::Version
-  version: 0.5.13
+  version: 0.5.14
 platform: ruby
 authors:
 - Ribose Inc.