moxml 0.5.3 → 0.5.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6cadb7739071fa9a823f6a08fe5daa33c2313d22e4c4454aa491e975f62da5ee
-  data.tar.gz: b6682343586e2bf873c9067fccc68f03f2c67c8b10eafc418fcad6663320f2f2
+  metadata.gz: 0cc1ee5cd198e8016cd259e62eec132ef73863dbb91125cca55349c8847df01c
+  data.tar.gz: 9b3db2921b1acaebaaeccfa6dbba82c78184443c6338e79952e334da0a837b0c
 SHA512:
-  metadata.gz: 67da3161b095e47aafe6d7e7327c2125a4458a9ef557c41c5f9d6465fccb01374d29c409178910b39426cf0cf7a42140d6858d4177c3f63b529690f397303796
-  data.tar.gz: c88f55e02c026e18f4c1a25578d9e27094835288e6ccc0dccff40633ff31029975125d9fcfb51ae5353f00ad5fa54fd8bef135d9e44c64da794b45513f728903
+  metadata.gz: 4a4ccdd2949f15fedf7bee4bc2c41b9340250ec58d2d4583e7be7a0a14c397749e034f1ec3e15193c7a2ad93d43de7126338fecf2142ad1180ea50b3de25a97a
+  data.tar.gz: 9e4abee61c92cb0a3390804af398e6baaf593107e8bbc9b33b10d5bc40675f9f0b92ef5ded27f0b8948edd8c930b5188496c4c644529a277d8dd71b49f3bae57

data/lib/moxml/adapter/base.rb

@@ -5,16 +5,6 @@ module Moxml
     class Base
       # include XmlUtils
 
-      # Entity round-trip pipeline lives in Moxml::Entity; these
-      # constants and methods stay on the adapter protocol so
-      # adapters and wrappers keep their calling convention.
-      ENTITY_MARKER = Entity::MARKER
-      ENTITY_NAME_PATTERN = Entity::NAME_PATTERN
-      ENTITY_NAME_RE = Entity::NAME_RE
-      ENTITY_MARKER_RE = Entity::MARKER_RE
-      SERIALIZED_ENTITY_MARKER_RE = Entity::SERIALIZED_MARKER_RE
-      STANDARD_ENTITIES = Entity::STANDARD_ENTITIES
-
       class << self
         include XmlUtils
 
@@ -183,6 +173,22 @@ namespace_validation_mode: :strict)
           node
         end
 
+        # Whether children() results need per-child patch_node
+        # rewriting. Adapters whose natives arrive pre-wrapped (all but
+        # ox and libxml) answer false so the wrapper layer can skip
+        # the identity map over every child list.
+        def patches_children?
+          false
+        end
+
+        # Whether the subtree at native can contain entity markers.
+        # Marker-tracking adapters override this so the post-serialize
+        # restore can skip its full-output scans on marker-free
+        # documents; the default stays conservative.
+        def entity_bearing?(_native)
+          true
+        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

@@ -46,6 +46,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))
 
           doc
         end
@@ -207,6 +208,21 @@ module Moxml
           node.target
         end
 
+        # Marker presence is a document-level fact: parse records it,
+        # the ER builder path flips it, and the split/restore scans
+        # consult it. Customized natives only exist as split products
+        # of marker-bearing text, so they always report true.
+        def entity_bearing?(native)
+          case native
+          when CustomizedLeptris::Declaration, CustomizedLeptris::Doctype,
+               CustomizedLeptris::EntityReference, CustomizedLeptris::TextSegment
+            true
+          else
+            doc = native.document
+            doc.nil? || attachments.get(doc, :entity_markers) != false
+          end
+        end
+
         def node_type(node)
           case node
           when ::Leptris::XML::Document then :document
@@ -254,10 +270,25 @@ module Moxml
           when ::Leptris::XML::Document
             assemble_document_children(node)
           when CustomizedLeptris::Declaration, CustomizedLeptris::Doctype,
-               CustomizedLeptris::EntityReference, CustomizedLeptris::TextSegment
+               CustomizedLeptris::EntityReference, CustomizedLeptris::TextSegment,
+               # Terminal node kinds pay an FFI round trip for an empty
+               # list; unfiltered recursions visit every text node.
+               ::Leptris::XML::Text, ::Leptris::XML::Comment,
+               ::Leptris::XML::CDATA, ::Leptris::XML::ProcessingInstruction,
+               ::Leptris::XML::Attr
             []
           else
-            split_entity_markers(node.children.to_a, node)
+            natives = node.children.to_a
+            # Parse records whether the preprocessed source held any
+            # entity markers, and the ER builder path flips the flag
+            # when it mints one. A false flag lets traversal skip the
+            # marker split — including the per-text content fetch that
+            # dominates cold children cost. Cross-document moves of
+            # marker-bearing text into an entity-free document degrade
+            # to literal text.
+            return natives if attachments.get(node.document, :entity_markers) == false
+
+            split_entity_markers(natives, node)
           end
         end
 
@@ -385,6 +416,7 @@ module Moxml
             if child.is_a?(CustomizedLeptris::EntityReference)
               marker = parent.document.create_text_node("#{Entity::MARKER}#{child.name};")
               parent.add_child(marker)
+              attachments.set(parent.document, :entity_markers, true)
               return child
             end
             child = parent.document.create_text_node(child) if child.is_a?(String)
@@ -698,9 +730,10 @@ module Moxml
         end
 
         def serialize(node, options = {})
-          xml = raw_serialize(node, options)
-          xml = restore_entities(xml)
-          normalize_serialization(xml, options)
+          # 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)
         end
 
         def raw_serialize(node, options)

data/lib/moxml/adapter/libxml.rb

@@ -1134,6 +1134,10 @@ module Moxml
           end
         end
 
+        def patches_children?
+          true
+        end
+
         def patch_node(node, _parent = nil)
           # Wrap native LibXML nodes in our wrapper classes
           return node if node.nil?

data/lib/moxml/adapter/oga.rb

@@ -105,7 +105,7 @@ module Moxml
 
         def create_native_entity_reference(name)
           text = ::Oga::XML::Text.new
-          text.text = "#{self::ENTITY_MARKER}#{name};"
+          text.text = "#{Entity::MARKER}#{name};"
           attachments.set(text, :entity_name, name)
           text
         end

data/lib/moxml/adapter/ox.rb

@@ -243,6 +243,10 @@ module Moxml
           Marshal.load(Marshal.dump(node))
         end
 
+        def patches_children?
+          true
+        end
+
         def patch_node(node, parent = nil)
           new_node =
             case node

data/lib/moxml/config.rb

@@ -11,10 +11,13 @@ module Moxml
     # when the installed leptris supports programmatic document
     # construction (Leptris::XML::Document.create); otherwise moxml
     # falls back to FALLBACK_ADAPTER so released-gem environments keep
-    # working. Oga remains the Opal default (pure Ruby).
+    # working. Under Opal the default is oga only when the vendored
+    # pure-Ruby fork was compiled into the bundle — stock oga requires
+    # its C extension and cannot load there; otherwise rexml.
     PREFERRED_ADAPTER = :leptris
     FALLBACK_ADAPTER = :nokogiri
     OPAL_DEFAULT_ADAPTER = :oga
+    OPAL_FALLBACK_ADAPTER = :rexml
 
     # Entity loading modes:
     # - :required - Must load entities, raise error if unavailable (default)
@@ -35,13 +38,26 @@ module Moxml
       end
 
       def runtime_default_adapter
-        return OPAL_DEFAULT_ADAPTER if RUBY_ENGINE == "opal"
+        return opal_runtime_adapter if RUBY_ENGINE == "opal"
 
         return PREFERRED_ADAPTER if leptris_preferred_available?
 
         detect_loaded_adapter || FALLBACK_ADAPTER
       end
 
+      # Stock oga requires its C extension, so under Opal the oga
+      # adapter can only come from the vendored pure-Ruby fork — a
+      # repo-only artifact the released gem does not ship. Bundles
+      # that compiled it in (moxml's own harness) keep oga; everyone
+      # else gets the rexml adapter, whose Opal compat ships in-gem.
+      # `defined?` is safe here: this branch never runs under MRI,
+      # where it would trigger autoload resolution.
+      def opal_runtime_adapter
+        return OPAL_DEFAULT_ADAPTER if defined?(Moxml::Adapter::Oga)
+
+        OPAL_FALLBACK_ADAPTER
+      end
+
       # True when the leptris gem is installed AND new enough for the
       # adapter (it needs programmatic document construction, which
       # released 1.1.x lacks). Memoized: the require probe runs once.

data/lib/moxml/context.rb

@@ -60,7 +60,9 @@ module Moxml
                        xml.rewind if xml.is_a?(IO) || xml.is_a?(StringIO)
                      end
                    end
-      has_declaration = xml_string.strip.start_with?("<?xml")
+      # Allocation-free declaration sniff: String#strip would copy the
+      # whole buffer just to test its prefix.
+      has_declaration = xml_string.match?(/\A[ \t\r\n\f\v\0]*<\?xml/)
 
       # Parse with adapter, passing self (context) so adapter can use our config
       parsed_options = default_options.merge(options)

data/lib/moxml/document_builder.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Moxml
+  # Deprecated compatibility facade retained for 0.2-era callers.
+  #
+  # DocumentBuilder was the parse entry point before 0.3.0 retired it
+  # in favor of Context#parse; deleting the constant broke downstream
+  # gems that referenced it directly (issue #124). It now delegates to
+  # Context#parse, so `build(xml_string)` returns a parsed document —
+  # unlike the 0.2-era behavior of silently returning an empty one.
+  class DocumentBuilder
+    attr_reader :context
+
+    def initialize(context)
+      @context = context
+    end
+
+    def build(xml)
+      context.parse(xml)
+    end
+  end
+end

data/lib/moxml/node.rb

@@ -38,11 +38,11 @@ module Moxml
     end
 
     def children
-      @children ||= NodeSet.new(
-        adapter.children(@native).map { adapter.patch_node(_1, @native) },
-        context,
-        self,
-      )
+      @children ||= begin
+        natives = adapter.children(@native)
+        natives = natives.map { adapter.patch_node(_1, @native) } if adapter.patches_children?
+        NodeSet.new(natives, context, self)
+      end
     end
 
     def next_sibling
@@ -111,8 +111,10 @@ module Moxml
       result = adapter.serialize(@native, serialize_options)
       result = apply_line_ending(result, serialize_options[:line_ending])
 
-      # Restore entity markers to named entity references
-      adapter.restore_entities(result)
+      # Restore entity markers to named entity references; skipped
+      # when the adapter knows the document carries no markers.
+      result = adapter.restore_entities(result) if adapter.entity_bearing?(@native)
+      result
     end
 
     def xpath(expression, namespaces = {})

data/lib/moxml/version.rb

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

data/lib/moxml.rb

@@ -80,6 +80,7 @@ module Moxml
   autoload :Namespace, "moxml/namespace"
   autoload :Doctype, "moxml/doctype"
   autoload :EntityReference, "moxml/entity_reference"
+  autoload :DocumentBuilder, "moxml/document_builder"
   autoload :Builder, "moxml/builder"
   autoload :Entity, "moxml/entity"
   autoload :EntityRegistry, "moxml/entity_registry"

data/spec/moxml/adapter/leptris_spec.rb

@@ -80,4 +80,39 @@ RSpec.describe Moxml::Adapter::Leptris do
       expect { doc.xpath("//item[") }.to raise_error(Moxml::XPathError)
     end
   end
+
+  describe "entity-marker tracking" do
+    let(:ctx) { Moxml.new(:leptris) }
+
+    it "skips the marker split for entity-free documents" do
+      doc = ctx.parse("<root>\n  <a>text</a>\n  <b/>\n</root>")
+      kids = doc.root.children.to_a
+      expect(kids.map(&:class)).to eq([Moxml::Text, Moxml::Element, Moxml::Text, Moxml::Element, Moxml::Text])
+      expect(described_class.entity_bearing?(doc.root.native)).to be(false)
+    end
+
+    it "splits markers when the source carries entities" do
+      doc = ctx.parse("<root><a>pre&nbsp;post</a></root>")
+      kids = doc.at_xpath("//a").children.to_a
+      expect(kids.map(&:class)).to include(Moxml::EntityReference)
+      expect(described_class.entity_bearing?(doc.root.native)).to be(true)
+    end
+
+    it "returns serialized markup for entity-free documents" do
+      # to_xml must not return nil when the restore scan is skipped
+      doc = ctx.parse("<root><a>text</a></root>")
+      expect(doc.to_xml).to include("<root>")
+      expect(doc.at_xpath("//a").to_xml).to eq("<a>text</a>")
+    end
+
+    it "flips the flag when the builder mints an entity reference" do
+      doc = ctx.parse("<root><a/></root>")
+      expect(described_class.entity_bearing?(doc.root.native)).to be(false)
+
+      er = doc.create_entity_reference("nbsp")
+      doc.at_xpath("//a").add_child(er)
+      expect(described_class.entity_bearing?(doc.root.native)).to be(true)
+      expect(doc.at_xpath("//a").children.to_a.map(&:class)).to include(Moxml::EntityReference)
+    end
+  end
 end

data/spec/moxml/document_builder_spec.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe Moxml::DocumentBuilder do
+  # Issue #124: 0.3.0 deleted the class and NameError'd downstream
+  # callers (lutaml-xsd parses XML through this constructor shape).
+  describe ".new with a context" do
+    it "builds a document from XML content" do
+      context = Moxml::Context.new
+      builder = described_class.new(context)
+      doc = builder.build(<<~XML)
+        <person xmlns="http://example.com/test" id="123">
+          <name>John Doe</name>
+        </person>
+      XML
+
+      expect(doc).to be_a(Moxml::Document)
+      expect(doc.root.name).to eq("person")
+      expect(doc.root["id"]).to eq("123")
+      expect(doc.root.children.select(&:element?).map(&:name)).to eq(["name"])
+    end
+
+    it "exposes the context it was created with" do
+      context = Moxml::Context.new
+      builder = described_class.new(context)
+
+      expect(builder.context).to equal(context)
+    end
+
+    it "accepts an explicit adapter, matching Context.new(adapter)" do
+      context = Moxml::Context.new(:nokogiri)
+      doc = described_class.new(context).build("<root><child/></root>")
+
+      expect(doc.context.config.adapter_name).to eq(:nokogiri)
+      expect(doc.root.children.select(&:element?).map(&:name)).to eq(["child"])
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: moxml
 version: !ruby/object:Gem::Version
-  version: 0.5.3
+  version: 0.5.5
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-26 00:00:00.000000000 Z
+date: 2026-08-27 00:00:00.000000000 Z
 dependencies: []
 description: |
   Moxml is a unified XML manipulation library that provides a common API
@@ -186,6 +186,7 @@ files:
 - lib/moxml/declaration.rb
 - lib/moxml/doctype.rb
 - lib/moxml/document.rb
+- lib/moxml/document_builder.rb
 - lib/moxml/element.rb
 - lib/moxml/entity.rb
 - lib/moxml/entity/reference.rb
@@ -443,6 +444,7 @@ files:
 - spec/moxml/declaration_preservation_spec.rb
 - spec/moxml/declaration_spec.rb
 - spec/moxml/doctype_spec.rb
+- spec/moxml/document_builder_spec.rb
 - spec/moxml/document_spec.rb
 - spec/moxml/element_spec.rb
 - spec/moxml/entity_preservation_spec.rb