moxml 0.5.7 → 0.5.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c0d0117dfa9a9f81f628f2200d09b21d93d148a1dd4d0614c98749c90cdb569e
-  data.tar.gz: 85de05e0fe6d7d596b8e39508adbcd98c312b63d16d10eb146caab8f147cdb08
+  metadata.gz: 011d9a8566b2697d8c01a17a1a4f702ace315361dae3b246f8ed5ad5fb79b3e8
+  data.tar.gz: 286839c9aca15e4027d4b01bcdfb432c2036f10234fb408cf10f88e5dcbeac0d
 SHA512:
-  metadata.gz: a57ef921cc44f3706e541abce2bef21b5b9f91066d9bc3528be802a373d57a488fb36825bf13dcf083aa88572fe1d2618ddbbb0d4ebec9a3de93515006698974
-  data.tar.gz: db325b0220a05b14bc2e037250c75319a60be30e652d05a1519ea0d26b5ff3afa55031d467312e81388442cb4f172513ef64cfb42be37ddca4c9da4d46704e97
+  metadata.gz: f53698ba5eee597fb6bda3355c1f7dfe0a33442cd3e67a6aedc73a155a23e80f049f2fc63aed6871b6cb2e85723719d7e7f318cc140ef178e5dde4bcd493a095
+  data.tar.gz: 44d1afe3880ebc55dd214a0a7f2b48c69151504b6c5a16646afd88cf4a885184132db9a590552c2531bfda8ea84a92e8fac50a7cfae75379e215582acf0f5bac

data/lib/moxml/adapter/base.rb

@@ -189,6 +189,15 @@ namespace_validation_mode: :strict)
           true
         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.
+        def bulk_materialize?
+          false
+        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.rb

@@ -30,10 +30,15 @@ module Moxml
 
         def parse(xml, options = {}, _context = nil)
           xml_string = xml.is_a?(IO) || xml.is_a?(StringIO) ? xml.read : xml.to_s
-          processed = preprocess_entities(xml_string)
+          # The marker flag rides preprocess's own `&` scan — no
+          # second full-buffer probe (issue #132 parse-side note).
+          processed, entity_markers = Entity.preprocess_with_marker_flag(xml_string)
 
+          # readonly: true (issue #133): the binding memoizes reads and
+          # refuses mutations — the parse-and-read lifecycle for
+          # multi-pass consumers (comparison, diff, signature).
           native_doc = begin
-            ::Leptris::XML::Document.parse(processed)
+            ::Leptris::XML::Document.parse(processed, readonly: options[:readonly] == true)
           rescue ::Leptris::XML::ParseError => e
             # libleptris has no recovery mode that survives unclosed
             # tags; non-strict callers get an empty document, matching
@@ -46,7 +51,7 @@ module Moxml
           doc = Document.new(native_doc, ctx)
 
           record_source_declaration(native_doc, processed)
-          attachments.set(native_doc, :entity_markers, processed.include?(Entity::MARKER))
+          attachments.set(native_doc, :entity_markers, entity_markers)
 
           doc
         end
@@ -224,18 +229,104 @@ module Moxml
           end
         end
 
+        # 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.
+        def bulk_materialize?
+          true
+        end
+
+        def materialize_records(native, &block)
+          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)
+
+          root = native.is_a?(::Leptris::XML::Document) ? native.root : native
+          return nil if root.nil?
+
+          depth_memo = {}.compare_by_identity
+          root.traverse do |node|
+            record = case node
+                     when ::Leptris::XML::Element
+                       element_material_record(node, depth_memo)
+                     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, node, depth_memo)
+                     when ::Leptris::XML::Text
+                       text_material_record(:text, node.content, node, depth_memo)
+                     when ::Leptris::XML::Comment
+                       text_material_record(:comment, node.content, node, depth_memo)
+                     when ::Leptris::XML::ProcessingInstruction
+                       text_material_record(:processing_instruction, node.content, node, depth_memo)
+                         .merge(qname: node.target)
+                     end
+            yield(record) if record
+          end
+          true
+        end
+
+        def element_material_record(node, depth_memo)
+          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]
+          end
+          ns = node.namespace
+          {
+            kind: :element,
+            qname: node.name,
+            prefix: node.prefix,
+            namespace_uri: ns&.href,
+            attributes: attributes,
+            text: nil,
+            depth: material_depth(node, depth_memo),
+          }
+        end
+
+        def text_material_record(kind, text, node, depth_memo)
+          {
+            kind: kind,
+            qname: nil,
+            prefix: nil,
+            namespace_uri: nil,
+            attributes: Materializer::EMPTY_ATTRIBUTES,
+            text: text,
+            depth: material_depth(node, depth_memo),
+          }
+        end
+
+        # Binding wrappers are address-stable and #parent is memoized,
+        # so each edge is fetched once; depths resolve through the
+        # identity-keyed memo.
+        def material_depth(node, memo)
+          memo[node] ||= begin
+            parent = node.parent
+            parent.nil? || parent.is_a?(::Leptris::XML::Document) ? 0 : material_depth(parent, memo) + 1
+          end
+        end
+
         def node_type(node)
+          # Frequency-ordered: elements and text dominate every real
+          # document, and Node.wrap dispatches here once per cold
+          # wrap. CDATA must precede Text (CDATA < Text in the
+          # binding).
           case node
+          when ::Leptris::XML::Element then :element
+          when ::Leptris::XML::CDATA then :cdata
+          when ::Leptris::XML::Text, CustomizedLeptris::TextSegment then :text
+          when ::Leptris::XML::Attr then :attribute
+          when ::Leptris::XML::Comment then :comment
+          when ::Leptris::XML::ProcessingInstruction, CustomizedLeptris::DocumentPI then :processing_instruction
           when ::Leptris::XML::Document then :document
           when ::Leptris::XML::DocType, CustomizedLeptris::Doctype then :doctype
           when CustomizedLeptris::Declaration then :declaration
           when CustomizedLeptris::EntityReference then :entity_reference
-          when ::Leptris::XML::CDATA then :cdata
-          when ::Leptris::XML::Comment then :comment
-          when ::Leptris::XML::ProcessingInstruction, CustomizedLeptris::DocumentPI then :processing_instruction
-          when ::Leptris::XML::Text, CustomizedLeptris::TextSegment then :text
-          when ::Leptris::XML::Element then :element
-          when ::Leptris::XML::Attr then :attribute
           else :unknown
           end
         end

data/lib/moxml/context.rb

@@ -74,6 +74,13 @@ module Moxml
       doc
     end
 
+    # Parse then flatten in one call — see Moxml::Materializer
+    # (issue #132). Yields records; returns an Enumerator when no
+    # block is given.
+    def materialize(xml, options = {}, &block)
+      parse(xml, options).materialize(&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

@@ -24,6 +24,13 @@ module Moxml
       root_element ? Moxml::Node.wrap(root_element, context) : nil
     end
 
+    # Materialize the root subtree — see Moxml::Materializer.
+    def materialize(&block)
+      return to_enum(:materialize) unless block
+
+      root&.materialize(&block)
+    end
+
     def create_element(name)
       Element.new(adapter.create_element(name, owner_doc: @native), context)
     end

data/lib/moxml/entity.rb

@@ -55,9 +55,12 @@ module Moxml
     module_function
 
     # Replace non-standard entity references with markers before
-    # parsing. Always returns a UTF-8 encoded string.
-    def preprocess_entities(xml)
-      return "" if xml.nil?
+    # parsing. Always returns a UTF-8 encoded string, and reports
+    # whether the result can contain markers: the flag rides the
+    # same `&` scan, so callers needing it (leptris parse) avoid a
+    # second full-buffer multibyte probe.
+    def preprocess_with_marker_flag(xml)
+      return ["", false] if xml.nil?
 
       str = if xml.encoding == Encoding::BINARY
               # Binary strings are assumed to be UTF-8. If the bytes are
@@ -78,11 +81,23 @@ module Moxml
       # Fast path: no `&` means no entity references to mark — skip
       # the regex scan and string allocation entirely. The vast
       # majority of XML payloads contain no entity references.
-      return str unless str.include?("&")
+      return [str, false] unless str.include?("&")
 
-      str.gsub(NAME_RE) do |match|
-        STANDARD_ENTITIES.include?(::Regexp.last_match(1)) ? match : "#{MARKER}#{::Regexp.last_match(1)};"
+      marked = false
+      processed = str.gsub(NAME_RE) do |match|
+        name = ::Regexp.last_match(1)
+        if STANDARD_ENTITIES.include?(name)
+          match
+        else
+          marked = true
+          "#{MARKER}#{name};"
+        end
       end
+      [processed, marked]
+    end
+
+    def preprocess_entities(xml)
+      preprocess_with_marker_flag(xml)[0]
     end
 
     # Resolve numeric (&#NN; / &#xNN;) and the five standard named

data/lib/moxml/materializer.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Moxml
+  # Flattened subtree records for conversion-style consumers
+  # (issue #132): one record per node, emitted in post-order (children
+  # before parents — build with a stack), carrying everything a
+  # consumer tree needs without allocating Moxml::Node or
+  # Moxml::Attribute wrappers.
+  #
+  #   context.materialize(xml) { |r| ... }
+  #   document.materialize.each { |r| ... }   # Enumerator
+  #
+  # 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 }
+  #
+  # 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.
+  module Materializer
+    # Shared frozen empty attribute list for non-element records;
+    # adapters' bulk paths reference it too.
+    EMPTY_ATTRIBUTES = [].freeze
+
+    module_function
+
+    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)
+        return
+      end
+
+      walk(node, 0, &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)
+      case node
+      when Element
+        node.children.each { |child| walk(child, depth + 1, &block) }
+        yield(element_record(node, depth))
+      when Text
+        yield(text_record(:text, node.content, depth))
+      when Cdata
+        yield(text_record(:cdata, node.content, depth))
+      when Comment
+        yield(text_record(:comment, node.content, depth))
+      when ProcessingInstruction
+        yield(text_record(:processing_instruction, node.content, depth).merge(qname: node.target))
+      when EntityReference
+        yield(text_record(:entity_reference, "&#{node.name};", depth).merge(qname: node.name))
+      end
+    end
+
+    def element_record(element, depth)
+      attributes = element.attributes.map do |attr|
+        ns = attr.namespace
+        [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,
+        attributes: attributes,
+        text: nil,
+        depth: depth,
+      }
+    end
+
+    def text_record(kind, text, depth)
+      {
+        kind: kind,
+        qname: nil,
+        prefix: nil,
+        namespace_uri: nil,
+        attributes: EMPTY_ATTRIBUTES,
+        text: text,
+        depth: depth,
+      }
+    end
+  end
+end

data/lib/moxml/node.rb

@@ -124,6 +124,13 @@ module Moxml
       result.is_a?(Array) ? NodeSet.new(result, context) : result
     end
 
+    # Flattened post-order records for this subtree without
+    # allocating wrappers — see Moxml::Materializer (issue #132).
+    # Returns an Enumerator when no block is given.
+    def materialize(&block)
+      Materializer.materialize(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.7"
+  VERSION = "0.5.9"
 end

data/lib/moxml.rb

@@ -87,6 +87,7 @@ module Moxml
   autoload :NativeAttachment, "moxml/native_attachment"
   autoload :XmlUtils, "moxml/xml_utils"
   autoload :XmlEmitter, "moxml/xml_emitter"
+  autoload :Materializer, "moxml/materializer"
   autoload :Adapter, "moxml/adapter"
   autoload :XPath, "moxml/xpath"
   autoload :SAX, "moxml/sax"

data/spec/moxml/materializer_spec.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe Moxml::Materializer do
+  let(:xml) do
+    <<~XML
+      <catalog xmlns="urn:c" xmlns:p="urn:p">
+        <book id="b1" p:lang="en"><title>T</title><!--n--><?pi x?><![CDATA[raw]]></book>
+      </catalog>
+    XML
+  end
+
+  def records_for(adapter)
+    Moxml.new(adapter).materialize(xml).to_a
+  end
+
+  it "emits one record per node in post-order with depth, names, and attributes" do
+    records = records_for(:leptris)
+
+    expect(records.map { |r| [r[:kind], r[:depth]] }).to eq(
+      [
+        # post-order: whitespace before <book>, then the book subtree,
+        # then the trailing whitespace, then the catalog itself
+        [:text, 1],
+        [:text, 3], [:element, 2], [:comment, 2],
+        [:processing_instruction, 2], [:cdata, 2],
+        [:element, 1],
+        [:text, 1],
+        [:element, 0]
+      ],
+    )
+
+    book = records.find { |r| r[:qname] == "book" }
+    expect(book[:attributes]).to include(["id", "b1", nil, nil], ["lang", "en", "urn:p", "p"])
+    expect(book[:namespace_uri]).to eq("urn:c")
+    expect(book[:text]).to be_nil
+
+    title_text = records.find { |r| r[:kind] == :text && r[:text] == "T" }
+    expect(title_text[:attributes]).to eq([])
+  end
+
+  it "uses the same record stream on the bulk path and the generic walk" do
+    skip "leptris not installed" unless Moxml::Adapter.available?(:leptris)
+
+    expect(records_for(:leptris)).to eq(records_for(:nokogiri))
+  end
+
+  it "falls back to the generic walk for marker-bearing documents" do
+    entity_xml = "<r><a>pre&nbsp;post</a></r>"
+    records = Moxml.new(:leptris).materialize(entity_xml).to_a
+
+    expect(records.map { |r| [r[:kind], r[:text]] }).to eq(
+      [[:text, "pre"], [:entity_reference, "&nbsp;"], [:text, "post"],
+       [:element, nil], [:element, nil]],
+    )
+  end
+
+  it "materializes from any element subtree" do
+    doc = Moxml.new(:nokogiri).parse(xml)
+    title = doc.at_xpath("//*[local-name()='title']")
+    records = title.materialize.to_a
+
+    expect(records.map { |r| [r[:kind], r[:depth]] }).to eq([[:text, 1], [:element, 0]])
+  end
+
+  it "allocates no wrappers on the bulk path" do
+    skip "leptris not installed" unless Moxml::Adapter.available?(:leptris)
+
+    ctx = Moxml.new(:leptris)
+    ctx.materialize(xml).to_a # warm
+    GC.start
+    before = GC.stat(:total_allocated_objects)
+    ctx.materialize(xml).to_a
+    allocated = GC.stat(:total_allocated_objects) - before
+    node_count = ctx.parse(xml).materialize.count
+
+    # Records themselves allocate (hash + FFI strings); the wrapper
+    # tree does not: far fewer allocations than 2 wrappers per node.
+    expect(allocated).to be < node_count * 20
+  end
+end

data/spec/moxml/readonly_parse_spec.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "readonly parsing" do
+  let(:xml) { '<r><a x="1">t</a></r>' }
+
+  it "parses and reads normally" do
+    doc = Moxml.new(:leptris).parse(xml, readonly: true)
+
+    expect(doc.root.name).to eq("r")
+    expect(doc.at_xpath("//a")["x"]).to eq("1")
+    expect(doc.at_xpath("//a").text).to eq("t")
+  end
+
+  it "refuses mutations" do
+    doc = Moxml.new(:leptris).parse(xml, readonly: true)
+
+    expect { doc.root["y"] = "2" }.to raise_error(/ReadOnly/i)
+  end
+
+  it "is a no-op concept on other adapters" do
+    doc = Moxml.new(:nokogiri).parse(xml, readonly: true)
+
+    expect(doc.root.name).to eq("r")
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: moxml
 version: !ruby/object:Gem::Version
-  version: 0.5.7
+  version: 0.5.9
 platform: ruby
 authors:
 - Ribose Inc.
@@ -196,6 +196,7 @@ files:
 - lib/moxml/entity_registry.rb
 - lib/moxml/entity_registry_opal_data.rb
 - lib/moxml/error.rb
+- lib/moxml/materializer.rb
 - lib/moxml/namespace.rb
 - lib/moxml/native_attachment.rb
 - lib/moxml/native_attachment/native.rb
@@ -454,6 +455,7 @@ files:
 - spec/moxml/entity_spec.rb
 - spec/moxml/error_spec.rb
 - spec/moxml/lazy_parse_spec.rb
+- spec/moxml/materializer_spec.rb
 - spec/moxml/moxml_spec.rb
 - spec/moxml/namespace_spec.rb
 - spec/moxml/namespace_uri_validation_spec.rb
@@ -472,6 +474,7 @@ files:
 - spec/moxml/opal_rexml_adapter_spec.rb
 - spec/moxml/opal_smoke_spec.rb
 - spec/moxml/processing_instruction_spec.rb
+- spec/moxml/readonly_parse_spec.rb
 - spec/moxml/sax/namespace_splitter_spec.rb
 - spec/moxml/sax_entity_parity_spec.rb
 - spec/moxml/sax_spec.rb