moxml 0.5.78 → 0.5.80

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd28ba8e6db906efd5a53cf65b12b2eee71739b60ca5b318c4c2013235f5ec1d
-  data.tar.gz: 2e36bde35317ddebb0a90c3b831f0566aa4e7b120ac51b9aead532309d586b28
+  metadata.gz: 656e065f07ecc3aea2624682345254907cab3bee557d14a74e7a9a1e6d3e53f2
+  data.tar.gz: d3606b240493ed82eb131bb8dd37e7d011bcd4d7d12d8907407c5408fcecb970
 SHA512:
-  metadata.gz: a2042daf1ec389e25b0a2e8896389944e19414c36881deb40d82327dc9025a1962ae6475d73b4e9e412cd787257a7a19403826b5f76ffacbe6a95fb694702250
-  data.tar.gz: 8259b9003c8085ce46567f4f75dc34502c41ebf15bff9d66b55499e127be8b69ccdcdabf3a3b1d262802684e26f8f2740b032a2dffed32929f3f121bc749090c
+  metadata.gz: d956c3ff27cae1eedce7a4cc9cb53f57a7d12a58999b74ddebb7bc4a3c99661e2cea010a5a2cc9682315ed5d4bfe06b4122453127d6682ecb96fcfd4401202e2
+  data.tar.gz: 478679f5fc817ba910aa0adc927ca0e22009ec1cc787b1388cef9ed3ff570da51c83eaa5e5a99f9b4b9c21e2d6d0d8dbed280925035bc00b580ba242776e7766

data/README.adoc

@@ -103,9 +103,10 @@ entity references (`entity_mode: :keep`), 1.9.193.4+ native plan rows
 executor (`Moxml::StructPlan`; the floor is the varargs-mint fix),
 1.9.204+ native document-level parts (created DOCTYPEs as native
 nodes, document-PI removal, declaration clear). Current
-recommendation: 1.9.216+ (the plan-ABI train: bound plan rows,
-typed scalars, the #1242 iterparse fix; the engine's 1.9.217+
-borrowed-text-run wins ride in automatically).
+recommendation: 1.9.228+ (the #318 text-set fix train; carries
+the plan-ABI surface — bound plan rows, typed scalars, fused
+Descriptor#materialize — plus the 1.9.217+ borrowed-text-run and
+1.9.221+ memory wins).
 |===
 
 NOTE: moxml's dev Gemfile pins `leptris ~> 1.9.174`, `nokogiri ~> 1.18`,
@@ -644,6 +645,42 @@ root.add_child(title)
 puts doc.to_xml(indent: 2)
 ----
 
+=== Fast paths and diagnostics
+
+Read-only attribute listing without Attribute node objects — the
+walk-hot shape when only names and values are needed (leptris
+answers in one C crossing; document order, duplicates included):
+
+[source,ruby]
+----
+element.attribute_pairs.each do |name, value|
+  # names are shared frozen strings; dup before mutating
+end
+----
+
+Typed struct members on `Moxml::StructPlan` — the executor casts
+in C with no intermediate String (unparseable input degrades to
+the raw String):
+
+[source,ruby]
+----
+plan = Moxml::StructPlan.new do
+  element "item", Item,
+          attrs: { "price" => [:price, :float], "qty" => [:qty, :integer] },
+          text: [:label, :integer]
+end
+----
+
+Recover-class parse diagnostics (duplicate-attribute events and
+siblings) on adapters with the surface; `[]` elsewhere. Read
+while the document is alive:
+
+[source,ruby]
+----
+doc.parse_diagnostics
+# => [{ kind: :recover, message: "Attribute a redefined" }]
+----
+
 == Real-world examples
 
 Practical, runnable examples demonstrating Moxml usage in common scenarios are

data/lib/moxml/adapter/base.rb

@@ -358,6 +358,16 @@ namespace_validation_mode: :strict)
           nil
         end
 
+        # Single-crossing construction contract
+        # (Moxml::Element#add_element): create + attach under parent
+        # + all attributes in one call, returning the new native
+        # element. This default has no bulk face — nil sends the
+        # caller down the portable create_element + add_child path;
+        # adapters with the face override (leptris — #312/#1344).
+        def create_element_with_attrs(_parent, _name, _attrs)
+          nil
+        end
+
         # Read-only attribute listing as [name, value] pairs
         # (Moxml::Element#attribute_pairs) — document order,
         # duplicates included, no Attribute node wrappers. The

data/lib/moxml/adapter/leptris.rb

@@ -353,10 +353,8 @@ module Moxml
           }.freeze
 
           def wrap_binding_node(node, context)
-            if node.instance_variable_defined?(:@moxml_wrapper)
-              cached = node.instance_variable_get(:@moxml_wrapper)
-              return cached if cached
-            end
+            cached = node.instance_variable_get(:@moxml_wrapper)
+            return cached if cached
 
             entry = BINDING_FAST_WRAP[node.class]
             return nil unless entry
@@ -1490,6 +1488,31 @@ module Moxml
           line.zero? ? nil : line
         end
 
+        # Single-crossing construction (#312/#1344 consumer face):
+        # create + attach under parent + all attributes in ONE
+        # Ruby->C call (create_child is create+attach; the attr
+        # loop is C->C dlsym). Requires parent binding + the face;
+        # callers fall back to create_element + set_attribute +
+        # add_child when absent.
+        def create_element_with_attrs(parent, name, attrs)
+          binding_parent = to_binding(parent)
+          doc = binding_parent.document or return nil
+          return nil unless ::Leptris::XML::Native.respond_to?(:create_element_with_attrs)
+
+          flat = attrs.flatten
+          addr = ::Leptris::XML::Native.create_element_with_attrs(
+            doc.c_address, binding_parent.c_address, name.to_s, flat)
+          return nil if addr.nil? || addr.zero?
+
+          # The binding's own wrap produces the proper binding
+          # Element (kind class, @c_address, @document); canonical
+          # convergence (#219) hands every accessor — children
+          # included — the SAME native, so the wrapper identity
+          # holds across later traversals.
+          canonical_native(doc,
+            ::Leptris::XML::Node.wrap(::FFI::Pointer.new(addr), doc))
+        end
+
         def attributes(element)
           element = to_binding(element)
           element.attribute_nodes

data/lib/moxml/adapter/nokogiri.rb

@@ -294,6 +294,18 @@ module Moxml
           element[name.to_s] = value.to_s
         end
 
+        # Cross-adapter parity for Document#parse_diagnostics
+        # (#271): Nokogiri's doc.errors already carries recover-
+        # mode entries; mapped into the same { kind:, message: }
+        # shape. Kind is :error — Nokogiri does not classify.
+        def parse_diagnostics(native_doc)
+          return [] unless native_doc.respond_to?(:errors)
+
+          native_doc.errors.map do |e|
+            { kind: :error, message: e.message.to_s }
+          end
+        end
+
         def attributes(element)
           # attribute_nodes, not attributes.values: the attributes Hash
           # is keyed by local name, so xmi:type and type collide and

data/lib/moxml/element.rb

@@ -126,6 +126,29 @@ module Moxml
       adapter.attribute_pairs(@native)
     end
 
+    # Create an element with attributes and attach it under this
+    # element — ONE construction on adapters with the bulk face
+    # (leptris, #312/#1344 consumer face): create + attach + all
+    # attributes in a single Ruby->C crossing. Returns the child
+    # wrapper. Equivalent to create_element + attribute writes +
+    # add_child, minus two crossings and the intermediate churn.
+    def add_element(name, attrs = {})
+      native_child = adapter.create_element_with_attrs(
+        @native, name, attrs
+      )
+      if native_child
+        adapter.node_type(native_child)
+        Moxml::Node.wrap_with(native_child, context, adapter)
+      else
+        fallback = Moxml::Node.wrap_with(
+          adapter.create_element(name), context, adapter
+        )
+        attrs.each { |k, v| fallback[k] = v.to_s }
+        add_child(fallback)
+        fallback
+      end
+    end
+
     def attributes
       # Primed like Node.wrap: the adapter and type are known at
       # mint, so the first name/value/attribute? access skips the

data/lib/moxml/version.rb

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

data/spec/moxml/document_parse_diagnostics_spec.rb

@@ -40,4 +40,16 @@ RSpec.describe Moxml::Document do
   rescue StandardError, LoadError
     skip "rexml adapter unavailable"
   end
+
+  it "maps nokogiri doc.errors into the same shape" do
+    ctx = Moxml.new(:nokogiri)
+    doc = ctx.parse(%(<r a="1" a="2"/>), recover: true) ||
+      ctx.parse(%(<r a="1" a="2"/>))
+    diags = doc.parse_diagnostics
+    expect(diags).not_to be_empty
+    expect(diags.first[:kind]).to eq(:error)
+    expect(diags.first[:message]).to be_a(String)
+  rescue StandardError, LoadError
+    skip "nokogiri adapter unavailable"
+  end
 end

data/spec/moxml/element_add_element_spec.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# Element#add_element adapter-contract conformance (#312): the
+# child must land attached with ALL attributes in one call —
+# through the bulk face (leptris) or the portable create_element +
+# add_child fallback (every other adapter). Guards both halves of
+# the contract: a missing base default NoMethodErrors on non-face
+# adapters, a broken fallback loses attributes or the attach.
+RSpec.describe Moxml::Element do
+  ADAPTERS = %i[leptris nokogiri ox oga rexml libxml].freeze # rubocop:disable Lint/ConstantDefinitionInBlock, RSpec/LeakyConstantDeclaration
+
+  def with_adapter(name)
+    ctx = Moxml.new(name)
+    yield ctx
+  rescue StandardError, LoadError
+    skip "adapter #{name} unavailable"
+  end
+
+  it "attaches a child with all attributes on every available adapter" do
+    ADAPTERS.each do |name|
+      with_adapter(name) do |ctx|
+        doc = ctx.parse("<catalog/>")
+        root = doc.root
+        child = root.add_element("record", "id" => "r1", "kind" => "k1")
+
+        expect(child.name).to eq("record"), "#{name}: name"
+        expect(child["id"]).to eq("r1"), "#{name}: id attr"
+        expect(child["kind"]).to eq("k1"), "#{name}: kind attr"
+        expect(child.parent.name).to eq("catalog"), "#{name}: attach"
+        expect(root.children.map(&:name)).to include("record"), "#{name}: visible in children"
+      end
+    end
+  end
+
+  it "nests under a non-root element with empty attrs" do
+    ADAPTERS.each do |name|
+      with_adapter(name) do |ctx|
+        doc = ctx.parse("<catalog><record/></catalog>")
+        record = doc.root.children.first
+        field = record.add_element("field")
+
+        expect(field.name).to eq("field"), "#{name}: name"
+        expect(field.attributes).to be_empty, "#{name}: no attrs"
+        expect(field.parent.name).to eq("record"), "#{name}: attach"
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: moxml
 version: !ruby/object:Gem::Version
-  version: 0.5.78
+  version: 0.5.80
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-23 00:00:00.000000000 Z
+date: 2026-09-24 00:00:00.000000000 Z
 dependencies: []
 description: |
   Moxml is a unified XML manipulation library that provides a common API
@@ -468,6 +468,7 @@ files:
 - spec/moxml/document_free_spec.rb
 - spec/moxml/document_parse_diagnostics_spec.rb
 - spec/moxml/document_spec.rb
+- spec/moxml/element_add_element_spec.rb
 - spec/moxml/element_attribute_pairs_spec.rb
 - spec/moxml/element_spec.rb
 - spec/moxml/entity_preservation_spec.rb