moxml 0.5.9 → 0.5.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 011d9a8566b2697d8c01a17a1a4f702ace315361dae3b246f8ed5ad5fb79b3e8
-  data.tar.gz: 286839c9aca15e4027d4b01bcdfb432c2036f10234fb408cf10f88e5dcbeac0d
+  metadata.gz: 15a0dd834bc1c9637a8d2284173d4994b1717b1bd2d8d9461686a56c679942e6
+  data.tar.gz: 4635e66b998d8fa371dd1617d0f960fc31b8a886627095061f945aa8b29cae41
 SHA512:
-  metadata.gz: f53698ba5eee597fb6bda3355c1f7dfe0a33442cd3e67a6aedc73a155a23e80f049f2fc63aed6871b6cb2e85723719d7e7f318cc140ef178e5dde4bcd493a095
-  data.tar.gz: 44d1afe3880ebc55dd214a0a7f2b48c69151504b6c5a16646afd88cf4a885184132db9a590552c2531bfda8ea84a92e8fac50a7cfae75379e215582acf0f5bac
+  metadata.gz: 6eace14b6adb980bc4c14c6f628b231961f47fab55e05a0bf809591b4203a6581f0cb333dc358ec3bebeb1c239f7ecd65fc68ca34ee70fb1bf71fbf8c00f278c
+  data.tar.gz: f03e39569fd299ac6a7e8dc266d97a5499fea6f89b166f64e46944649286df8a6ceb4fd4732b6a67cac160f2318b0ed4c79fc8d782184b3a090b9c3feb65be1e

data/lib/moxml/adapter/base.rb

@@ -198,6 +198,14 @@ namespace_validation_mode: :strict)
           false
         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
+        # further access.
+        def free_document(_native)
+          nil
+        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

@@ -19,6 +19,15 @@ module Moxml
     # programmatic DOCTYPE, so those live in CustomizedLeptris value
     # objects stored through NativeAttachment.
     class Leptris < Base
+      # libleptris 1.9.7 (leptris-ruby 1.9.26): Document#node exposes
+      # the libxml2-model document node — prolog/epilog parts in
+      # document order. Older bindings keep the flat pre-root PI path.
+      DOC_NODE_SUPPORTED = ::Leptris::XML::Document.method_defined?(:node)
+      # libleptris 1.9.8 (leptris-ruby 1.9.30): plain parse excludes
+      # DTD ATTLIST defaults, matching libxml2/Nokogiri semantics;
+      # ParseOptions::DTDATTR opts in (leptris/leptris#606).
+      DTDATTR_SUPPORTED = ::Leptris::XML::ParseOptions.const_defined?(:DTDATTR)
+
       class << self
         def attachments
           @attachments ||= Moxml::NativeAttachment.new
@@ -37,8 +46,14 @@ module Moxml
           # readonly: true (issue #133): the binding memoizes reads and
           # refuses mutations — the parse-and-read lifecycle for
           # multi-pass consumers (comparison, diff, signature).
+          # dtdattr: true opts into DTD ATTLIST default materialization
+          # (off by default since libleptris 1.9.8, matching libxml2).
           native_doc = begin
-            ::Leptris::XML::Document.parse(processed, readonly: options[:readonly] == true)
+            ::Leptris::XML::Document.parse(
+              processed,
+              readonly: options[:readonly] == true,
+              options: dtdattr_parse_options(options),
+            )
           rescue ::Leptris::XML::ParseError => e
             # libleptris has no recovery mode that survives unclosed
             # tags; non-strict callers get an empty document, matching
@@ -56,6 +71,30 @@ module Moxml
           doc
         end
 
+        # nil when DTDATTR is unsupported or not requested — the
+        # binding treats a nil options hash as plain defaults.
+        def dtdattr_parse_options(options)
+          return nil unless DTDATTR_SUPPORTED && options[:dtdattr] == true
+
+          ::Leptris::XML::ParseOptions.dtdattr
+        end
+
+        # Issue #134: deterministic release of the C tree. The binding
+        # clears its wrapper cache and raises UseAfterFreeError on
+        # later access; moxml-side attachments for the document are
+        # swept too (the context wrapper identity map self-cleans via
+        # its size valve).
+        DOCUMENT_ATTACHMENT_KEYS = %i[
+          entity_markers doc_pi_nodes declaration doctype
+          had_source_declaration document_text
+        ].freeze
+
+        def free_document(native)
+          DOCUMENT_ATTACHMENT_KEYS.each { |key| attachments.delete(native, key) }
+          native.free
+          nil
+        end
+
         def create_document(_native_doc = nil)
           ::Leptris::XML::Document.create
         end
@@ -243,24 +282,33 @@ module Moxml
           # 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
+          # leptris 1.9.28+'s traverse follows the document chain; from
+          # an arbitrary element it can visit following siblings. Use
+          # the bulk path only for document materialization, and filter
+          # the stream to the document element's subtree (issue #140).
+          return nil unless native.is_a?(::Leptris::XML::Document)
+
+          root = doc.root
           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_memo)
+                       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, node, depth_memo)
+                       text_material_record(:cdata, node.content, depth)
                      when ::Leptris::XML::Text
-                       text_material_record(:text, node.content, node, depth_memo)
+                       text_material_record(:text, node.content, depth)
                      when ::Leptris::XML::Comment
-                       text_material_record(:comment, node.content, node, depth_memo)
+                       text_material_record(:comment, node.content, depth)
                      when ::Leptris::XML::ProcessingInstruction
-                       text_material_record(:processing_instruction, node.content, node, depth_memo)
+                       text_material_record(:processing_instruction, node.content, depth)
                          .merge(qname: node.target)
                      end
             yield(record) if record
@@ -268,7 +316,7 @@ module Moxml
           true
         end
 
-        def element_material_record(node, depth_memo)
+        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).
@@ -283,32 +331,51 @@ module Moxml
             qname: node.name,
             prefix: node.prefix,
             namespace_uri: ns&.href,
+            # Own declarations only — same shape as the generic
+            # path's Element#declared_namespaces (issue #138).
+            namespaces: begin
+              decls = node.namespace_definitions.map { |d| [d.prefix, d.href] }
+              decls.empty? ? Materializer::EMPTY_ATTRIBUTES : decls
+            end,
             attributes: attributes,
             text: nil,
-            depth: material_depth(node, depth_memo),
+            depth: depth,
           }
         end
 
-        def text_material_record(kind, text, node, depth_memo)
+        def text_material_record(kind, text, depth)
           {
             kind: kind,
             qname: nil,
             prefix: nil,
             namespace_uri: nil,
+            namespaces: Materializer::EMPTY_ATTRIBUTES,
             attributes: Materializer::EMPTY_ATTRIBUTES,
             text: text,
-            depth: material_depth(node, depth_memo),
+            depth: depth,
           }
         end
 
-        # Binding wrappers are address-stable and #parent is memoized,
-        # so each edge is fetched once; depths resolve through the
+        # 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(node, memo)
-          memo[node] ||= begin
-            parent = node.parent
-            parent.nil? || parent.is_a?(::Leptris::XML::Document) ? 0 : material_depth(parent, memo) + 1
-          end
+        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
         end
 
         def node_type(node)
@@ -971,9 +1038,22 @@ module Moxml
           native = native_doctype_xml(doc)
           parts << native << "\n" if native
 
-          document_pi_nodes(doc).each { |pi| parts << pi.to_xml << "\n" }
+          if DOC_NODE_SUPPORTED
+            # The libxml2-model document node: prolog PIs/comments,
+            # the root, epilog PIs/comments — in document order, so
+            # epilog parts serialize after the root (issue #130).
+            doc_children = document_node_children(doc)
+            if doc_children
+              doc_children.each { |child| parts << raw_serialize(child, options) << "\n" }
+            else
+              document_pi_nodes(doc).each { |pi| parts << pi.to_xml << "\n" }
+              parts << raw_serialize(doc.root, options) << "\n" if doc.root
+            end
+          else
+            document_pi_nodes(doc).each { |pi| parts << pi.to_xml << "\n" }
 
-          parts << raw_serialize(doc.root, options) << "\n" if doc.root
+            parts << raw_serialize(doc.root, options) << "\n" if doc.root
+          end
 
           texts = attachments.get(doc, :document_text)
           texts&.each { |text| parts << XmlEmitter.escape_text(text.content.to_s) }
@@ -1000,7 +1080,8 @@ module Moxml
           dt = doc.doctype
           return nil unless dt
 
-          XmlEmitter.doctype_xml(dt.root_name, dt.public_id, dt.system_id)
+          subset = dt.internal_subset if dt.class.method_defined?(:internal_subset)
+          XmlEmitter.doctype_xml(dt.root_name, dt.public_id, dt.system_id, subset)
         end
 
         def sax_parse(xml, handler)
@@ -1046,6 +1127,20 @@ module Moxml
         # the same objects, so wrapper mutations round-trip. Build the
         # cache BEFORE appending a PI with add_pi, or the C-side
         # addition would be double-counted.
+        # The document node's children, or nil when the node does not
+        # reflect reality: parsed documents always list the root
+        # element among their children, but programmatically built
+        # ones do not (binding gap) — those keep the legacy parts
+        # path.
+        def document_node_children(doc)
+          doc_children = doc.children.to_a
+          has_root = doc_children.any?(::Leptris::XML::Element)
+          return doc_children if has_root
+          return doc_children if doc.root.nil?
+
+          nil
+        end
+
         def document_pi_nodes(doc)
           attachments.get(doc, :doc_pi_nodes) || begin
             nodes = doc.processing_instructions.map do |(target, data)|
@@ -1065,16 +1160,29 @@ module Moxml
           doctype_wrapper = attachments.get(doc, :doctype)
           children << doctype_wrapper if doctype_wrapper
 
-          # Document-level PIs live outside the element tree in
-          # libleptris (a flat list; its serializer emits them before
-          # the root). Listed after the DOCTYPE to match the order
-          # serialize_document emits, so children and serialization
-          # agree. Epilog anchoring is not representable in the C
-          # model — a known divergence from the Nokogiri-shaped
-          # contract the other adapters expose.
-          children.concat(document_pi_nodes(doc))
+          if DOC_NODE_SUPPORTED
+            # The libxml2-model document node lists prolog PIs/comments,
+            # the root, and epilog PIs/comments in document order —
+            # the Nokogiri-shaped contract, epilog anchoring included
+            # (issue #130). Built (programmatic) documents are not yet
+            # fully reflected by the node (binding gap: an attached
+            # root does not appear); document_node_children answers
+            # nil there for the legacy parts path.
+            doc_children = document_node_children(doc)
+            if doc_children
+              children.concat(doc_children)
+            else
+              children.concat(document_pi_nodes(doc))
+              children << doc.root if doc.root
+            end
+          else
+            # Legacy path: document-level PIs live outside the element
+            # tree in a flat pre-root list (libleptris < 1.9.7 C
+            # model); epilog anchoring is not representable there.
+            children.concat(document_pi_nodes(doc))
 
-          children << doc.root if doc.root
+            children << doc.root if doc.root
+          end
 
           texts = attachments.get(doc, :document_text)
           children.concat(texts) if texts

data/lib/moxml/document.rb

@@ -31,6 +31,17 @@ module Moxml
       root&.materialize(&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.
+    # GC-managed engines no-op. Further access raises the engine's
+    # use-after-free error; ordinary garbage-collected documents keep
+    # working via the finalizer either way.
+    def free
+      adapter.free_document(@native)
+      nil
+    end
+
     def create_element(name)
       Element.new(adapter.create_element(name, owner_doc: @native), context)
     end

data/lib/moxml/element.rb

@@ -119,6 +119,16 @@ module Moxml
     end
     alias namespace_definitions namespaces
 
+    # The element's OWN namespace declarations as [prefix, uri]
+    # pairs (nil prefix = default namespace) — not the inherited
+    # scope. The shape materialize records carry (issue #138).
+    def declared_namespaces
+      adapter.namespace_definitions(@native).map do |ns|
+        wrapper = Namespace.new(ns, context)
+        [wrapper.prefix, wrapper.uri]
+      end
+    end
+
     # Returns all namespaces in scope for this element,
     # including those inherited from ancestor elements.
     def in_scope_namespaces

data/lib/moxml/materializer.rb

@@ -69,6 +69,10 @@ module Moxml
         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,
@@ -81,6 +85,7 @@ module Moxml
         qname: nil,
         prefix: nil,
         namespace_uri: nil,
+        namespaces: EMPTY_ATTRIBUTES,
         attributes: EMPTY_ATTRIBUTES,
         text: text,
         depth: depth,

data/lib/moxml/version.rb

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

data/lib/moxml/xml_emitter.rb

@@ -56,8 +56,9 @@ module Moxml
       output << "?>"
     end
 
-    # @return [String] a DOCTYPE with its external identifier
-    def doctype_xml(name, public_id, system_id)
+    # @return [String] a DOCTYPE with its external identifier and
+    #   optional internal subset
+    def doctype_xml(name, public_id, system_id, internal_subset = nil)
       output = "<!DOCTYPE #{name}"
       if public_id && !public_id.to_s.empty?
         output << %( PUBLIC "#{public_id}")
@@ -65,6 +66,9 @@ module Moxml
       elsif system_id && !system_id.to_s.empty?
         output << %( SYSTEM "#{system_id}")
       end
+      if internal_subset && !internal_subset.empty?
+        output << " [" << internal_subset << "]"
+      end
       output << ">"
     end
   end

data/spec/moxml/adapter/leptris_spec.rb

@@ -85,37 +85,51 @@ RSpec.describe Moxml::Adapter::Leptris do
     let(:ctx) { Moxml.new(:leptris) }
 
     it "lists document PIs as children with the root" do
-      doc = ctx.parse('<?xml version="1.0"?><?pi-prolog before?><root/><?pi-epilog after?>')
+      doc = ctx.parse('<?xml version="1.0"?><?pi-prolog before?><root/><?pi-epilog after?><!-- tail -->')
       kids = doc.children.to_a
 
       expect(kids.map(&:class)).to eq(
-        [Moxml::ProcessingInstruction, Moxml::ProcessingInstruction, Moxml::Element],
+        [Moxml::ProcessingInstruction, Moxml::Element,
+         Moxml::ProcessingInstruction, Moxml::Comment],
       )
       expect(kids.select(&:processing_instruction?).map(&:target)).to eq(%w[pi-prolog pi-epilog])
       expect(kids[0].content).to eq("before")
+      expect(doc.to_xml.index("pi-epilog")).to be > doc.to_xml.index("</root>")
+      expect(doc.to_xml.index("<!-- tail -->")).to be > doc.to_xml.index("</root>")
     end
 
-    it "round-trips mutations and additions through serialization" do
-      doc = ctx.parse("<?pi-original x?><root/>")
-      pi = doc.children.to_a[0]
+    it "round-trips tree-level PI mutations through serialization" do
+      doc = ctx.parse("<root><a><?pi-original x?></a></root>")
+      pi = doc.at_xpath("//a").children.to_a.find(&:processing_instruction?)
       pi.target = "renamed"
       pi.content = "changed"
       expect(doc.to_xml).to include("<?renamed changed?>")
+    end
 
+    it "adds document PIs and lists them as children" do
+      doc = ctx.parse("<root/>")
       doc.add_child(doc.create_processing_instruction("added", "now"))
       expect(doc.to_xml).to include("<?added now?>")
-      expect(doc.children.to_a.select(&:processing_instruction?).map(&:target)).to eq(%w[renamed added])
+      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.
+      doc = ctx.parse("<?pi x?><root/>")
+      pi = doc.children.to_a[0]
+
+      expect { pi.target = "renamed" }.to raise_error(Leptris::XML::Error)
     end
 
     it "serializes children and document output in agreement" do
       # libleptris stores document PIs as one flat pre-root list (no
       # epilog anchoring); children and to_xml must at least agree.
       doc = ctx.parse('<?xml version="1.0"?><?pi-a 1?><root/><?pi-b 2?>')
-      from_children = doc.children.to_a.select(&:processing_instruction?)
-        .map(&:to_xml).join("\n")
+      parts = doc.children.to_a.map { |c| "#{c.to_xml}\n" }.join
       from_document = doc.to_xml.sub(%r{\A<\?xml[^>]*\?>\n}, "")
 
-      expect(from_document).to start_with(from_children)
+      expect(from_document).to eq(parts)
     end
 
     it "matches raw Nokogiri byte-for-byte for pretty-printing (issue #129)" do
@@ -139,6 +153,31 @@ RSpec.describe Moxml::Adapter::Leptris do
     end
   end
 
+  describe "DTD ATTLIST defaults" do
+    # libleptris 1.9.8: plain parse excludes ATTLIST defaults,
+    # matching libxml2/Nokogiri/REXML; dtdattr: true opts in.
+    let(:ctx) { Moxml.new(:leptris) }
+    let(:dtd_xml) do
+      %(<?xml version="1.0"?><!DOCTYPE doc [<!ATTLIST e9 attr CDATA "default">]><doc><e9/></doc>)
+    end
+
+    it "excludes ATTLIST defaults on plain parse" do
+      skip "requires leptris with no-DTDATTR semantics" unless Moxml::Adapter::Leptris::DTDATTR_SUPPORTED
+
+      doc = ctx.parse(dtd_xml)
+      expect(doc.at_xpath("//e9")["attr"]).to be_nil
+      expect(doc.to_xml).not_to include("attr=")
+    end
+
+    it "materializes ATTLIST defaults with dtdattr: true" do
+      skip "requires leptris with ParseOptions::DTDATTR" unless Moxml::Adapter::Leptris::DTDATTR_SUPPORTED
+
+      doc = ctx.parse(dtd_xml, dtdattr: true)
+      expect(doc.at_xpath("//e9")["attr"]).to eq("default")
+      expect(doc.to_xml).to include(%(attr="default"))
+    end
+  end
+
   describe "entity-marker tracking" do
     let(:ctx) { Moxml.new(:leptris) }
 

data/spec/moxml/document_free_spec.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "Document#free" do
+  let(:xml) { '<r><a x="1">t</a></r>' }
+
+  it "frees native memory deterministically (issue #134)" do
+    doc = Moxml.new(:leptris).parse(xml)
+    expect(doc.root.name).to eq("r")
+
+    expect(doc.free).to be_nil
+    expect { doc.root }.to raise_error(Leptris::XML::UseAfterFreeError)
+  end
+
+  it "is a no-op on GC-managed engines" do
+    doc = Moxml.new(:nokogiri).parse(xml)
+
+    expect(doc.free).to be_nil
+    expect(doc.root.name).to eq("r")
+  end
+end

data/spec/moxml/materializer_spec.rb

@@ -36,6 +36,10 @@ RSpec.describe Moxml::Materializer do
     expect(book[:namespace_uri]).to eq("urn:c")
     expect(book[:text]).to be_nil
 
+    catalog = records.last
+    expect(catalog[:namespaces]).to eq([[nil, "urn:c"], ["p", "urn:p"]])
+    expect(book[:namespaces]).to eq([])
+
     title_text = records.find { |r| r[:kind] == :text && r[:text] == "T" }
     expect(title_text[:attributes]).to eq([])
   end
@@ -56,6 +60,17 @@ RSpec.describe Moxml::Materializer do
     )
   end
 
+  it "scopes the document stream to the root subtree (issue #140)" do
+    scoped = %(<?xml version="1.0"?><!-- prolog c --><?pi b?><root>t</root><!-- epilog c --><?pi2 a?>)
+    leptris = Moxml.new(:leptris).materialize(scoped).to_a
+    nokogiri = Moxml.new(:nokogiri).materialize(scoped).to_a
+
+    expect(leptris).to eq(nokogiri)
+    expect(leptris.map { |r| [r[:kind], r[:depth]] }).to eq(
+      [[:text, 1], [:element, 0]],
+    )
+  end
+
   it "materializes from any element subtree" do
     doc = Moxml.new(:nokogiri).parse(xml)
     title = doc.at_xpath("//*[local-name()='title']")
@@ -77,6 +92,6 @@ RSpec.describe Moxml::Materializer do
 
     # 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
+    expect(allocated).to be < node_count * 24
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: moxml
 version: !ruby/object:Gem::Version
-  version: 0.5.9
+  version: 0.5.11
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-27 00:00:00.000000000 Z
+date: 2026-08-28 00:00:00.000000000 Z
 dependencies: []
 description: |
   Moxml is a unified XML manipulation library that provides a common API
@@ -447,6 +447,7 @@ files:
 - spec/moxml/declaration_spec.rb
 - spec/moxml/doctype_spec.rb
 - spec/moxml/document_builder_spec.rb
+- spec/moxml/document_free_spec.rb
 - spec/moxml/document_spec.rb
 - spec/moxml/element_spec.rb
 - spec/moxml/entity_preservation_spec.rb