lutaml-model 0.8.5 → 0.8.7

data/lib/lutaml/xml/serialization/instance_methods.rb

@@ -19,15 +19,24 @@ module Lutaml
         attr_accessor :element_order, :attribute_order, :schema_location,
                       :encoding, :doctype
 
-        # Store pre-collected namespace data for lazy plan building.
-        # This is a plain Hash (no adapter objects) collected during from_xml.
-        attr_accessor :pending_namespace_data
-
         # Store root element reference for truly lazy plan building.
         # Set in :lazy mode during deserialization; consumed on first to_xml.
         # Released after plan is built to allow GC of the DOM tree.
         attr_accessor :pending_plan_root_element
 
+        # Clear all internal XML parse state on this instance.
+        #
+        # Call before re-serializing a previously-parsed instance when the
+        # serialization context has changed (e.g. different namespace config,
+        # different XML document structure).
+        #
+        # @return [self]
+        def clear_xml_parse_state!
+          @import_declaration_plan = nil
+          @pending_plan_root_element = nil
+          self
+        end
+
         # XML namespace metadata for doubly-defined and alias support.
         # These carry information from deserialization to serialization.
         # Accessor methods use the @__ prefixed ivars for backward compatibility.
@@ -74,8 +83,8 @@ module Lutaml
         # Build or return the cached declaration plan.
         #
         # When import_declaration_plan: :lazy (default), builds the plan from
-        # pre-collected namespace data on first call. No-op when no pending
-        # data exists (:eager already set, :skip, or programmatic creation).
+        # the stored element reference on first call. No-op when no pending
+        # element exists (:eager already set, :skip, or programmatic creation).
         #
         # @return [DeclarationPlan, nil] The plan or nil
         def import_declaration_plan
@@ -178,8 +187,7 @@ module Lutaml
 
         # Extend INTERNAL_ATTRIBUTES with XML-specific ones
         def pretty_print_instance_variables
-          xml_internals = %i[@import_declaration_plan @xml_input_namespaces
-                             @pending_namespace_data @pending_plan_root_element
+          xml_internals = %i[@import_declaration_plan @pending_plan_root_element
                              @__xml_namespace_prefix
                              @__xml_ns_prefixes @__xml_original_namespace_uri
                              @xml_declaration @raw_schema_location]
@@ -232,11 +240,6 @@ module Lutaml
             options[:xml_declaration] = @xml_declaration
           end
 
-          # Pass input namespaces for Namespace Preservation
-          if instance_variable_defined?(:@xml_input_namespaces) && @xml_input_namespaces&.any?
-            options[:input_namespaces] = @xml_input_namespaces
-          end
-
           # Pass stored DeclarationPlan for format preservation.
           if import_declaration_plan
             options[:stored_xml_declaration_plan] = import_declaration_plan
@@ -253,39 +256,27 @@ module Lutaml
 
         private
 
-        # Build declaration plan from pre-collected namespace data or stored
-        # element reference (lazy mode). Called by xml_declaration_plan getter
-        # on first access.
+        # Build declaration plan from stored element reference (lazy mode).
+        # Called by import_declaration_plan getter on first access.
         # @return [DeclarationPlan, nil]
         def build_pending_declaration_plan
-          # Truly lazy: build namespace data from stored element reference
-          if @pending_plan_root_element
-            element = @pending_plan_root_element
-            @pending_plan_root_element = nil # Release reference (allows GC of DOM)
-            ns_data = Lutaml::Xml::ModelTransform.collect_element_namespaces(element)
-            if ns_data && !ns_data.empty?
-              xml_mapping = self.class.mappings_for(:xml)
-              return Lutaml::Xml::DeclarationPlan.from_input_with_locations(ns_data,
-                                                                            xml_mapping)
-            end
-            return nil
-          end
+          return nil unless @pending_plan_root_element
 
-          # Fallback: use pre-collected namespace data (eager-lazy hybrid)
-          ns = @pending_namespace_data
-          return nil unless ns
+          element = @pending_plan_root_element
+          @pending_plan_root_element = nil
+          ns_data = Lutaml::Xml::ModelTransform.collect_element_namespaces(element)
+          return nil unless ns_data && !ns_data.empty?
 
-          @pending_namespace_data = nil
           xml_mapping = self.class.mappings_for(:xml)
-          Lutaml::Xml::DeclarationPlan.from_input_with_locations(ns,
+          Lutaml::Xml::DeclarationPlan.from_input_with_locations(ns_data,
                                                                  xml_mapping)
         end
 
         def set_ordering(attrs)
-          return unless attrs.respond_to?(:item_order)
+          return unless attrs.is_a?(Lutaml::Xml::XmlElement)
 
           @element_order = attrs.item_order
-          @attribute_order = attrs.attribute_order if attrs.respond_to?(:attribute_order)
+          @attribute_order = attrs.attribute_order
         end
 
         def set_schema_location(attrs)

data/lib/lutaml/xml/transformation/custom_method_wrapper.rb

@@ -13,14 +13,10 @@ module Lutaml
     # is called with a block, the new element becomes the context for the duration
     # of the block, allowing nested element creation.
     class CustomMethodWrapper
-      # Initialize the wrapper
-      #
       # @param parent [XmlDataModel::XmlElement] Parent element to add children to
-      # @param rule [CompiledRule] The transformation rule
-      def initialize(parent, rule)
+      def initialize(parent)
         @parent = parent
-        @rule = rule
-        @context_stack = [parent] # Stack of context elements for nested creation
+        @context_stack = [parent]
       end
 
       # Get the current context element (top of stack)
@@ -70,9 +66,12 @@ module Lutaml
 
         if element_or_string.is_a?(String)
           add_xml_fragment_or_raw_content(parent, element_or_string)
-        else
-          # Add as child element
+        elsif element_or_string.is_a?(::Lutaml::Xml::DataModel::XmlElement)
           parent.add_child(element_or_string)
+        else
+          raise TypeError,
+                "add_element expects a String or XmlElement, got " \
+                "#{element_or_string.class}. Call .to_xml on the element first."
         end
         element_or_string
       end
@@ -81,7 +80,7 @@ module Lutaml
         require "moxml" unless defined?(Moxml)
         fragment_doc = Moxml.new.parse(fragment_string, fragment: true)
         add_fragment_children_to_parent(fragment_doc, parent)
-      rescue LoadError, StandardError
+      rescue LoadError
         append_raw_content(parent, fragment_string)
       end
 
@@ -135,12 +134,12 @@ module Lutaml
 
       # Add text to element (mimics old adapter API)
       #
-      # @param element [XmlDataModel::XmlElement, CustomMethodWrapper, nil] Element to add text to
+      # @param element [XmlDataModel::XmlElement, CustomMethodWrapper, nil]
+      #   Element to add text to. When the wrapper itself or nil is passed,
+      #   text is added to the current context element.
       # @param text [String] Text content
       def add_text(element, text)
-        # Handle case where element is the wrapper itself (for content mapping)
-        # or when element is nil (add to current context)
-        target = if element.is_a?(CustomMethodWrapper) || element.nil?
+        target = if element == self || element.nil?
                    current_context
                  else
                    element
@@ -169,32 +168,14 @@ module Lutaml
       # @yield [ElementWrapper] The created element for customization
       # @return [XmlElement] The created element
       def create_and_add_element(name, attributes: {})
-        # Create XmlDataModel element
-        element = Lutaml::Xml::DataModel::XmlElement.new(name)
-
-        # Add attributes if provided
-        attributes&.each do |attr_name, attr_value|
-          attr = Lutaml::Xml::DataModel::XmlAttribute.new(
-            attr_name.to_s, attr_value.to_s
-          )
-          element.add_attribute(attr)
-        end
-
-        # Add to current context
+        element = self.class.build_element(name, attributes)
         current_context.add_child(element)
 
         if block_given?
-          # Push this element as the new context for nested operations
           push_context(element)
-
           begin
-            # Create wrapper for the element
-            wrapped_element = ElementWrapper.new(element, self)
-
-            # Yield for customization (e.g., adding text, more nested elements)
-            yield wrapped_element
+            yield ElementWrapper.new(element, self)
           ensure
-            # Restore previous context
             pop_context
           end
         end
@@ -216,13 +197,7 @@ module Lutaml
         # @param text [String] Text content
         # @param cdata [Boolean, Hash] Whether to use CDATA (true or {cdata: true})
         def add_text(_self, text, cdata: false)
-          # Handle both cdata: true and cdata: {cdata: true} formats
-          use_cdata = if cdata.is_a?(Hash)
-                        cdata[:cdata] || false
-                      else
-                        cdata
-                      end
-
+          use_cdata = cdata.is_a?(Hash) ? cdata[:cdata] || false : cdata
           @element.text_content = text
           @element.cdata = use_cdata
         end
@@ -234,29 +209,33 @@ module Lutaml
         # @yield [ElementWrapper] The created element for customization
         # @return [XmlElement] The created element
         def create_and_add_element(name, attributes: {})
-          # Create XmlDataModel element
-          child = Lutaml::Xml::DataModel::XmlElement.new(name)
-
-          # Add attributes if provided
-          attributes&.each do |attr_name, attr_value|
-            attr = Lutaml::Xml::DataModel::XmlAttribute.new(
-              attr_name.to_s, attr_value.to_s
-            )
-            child.add_attribute(attr)
-          end
-
-          # Add to this element
+          child = CustomMethodWrapper.build_element(name, attributes)
           @element.add_child(child)
 
           if block_given?
-            # Wrap the child and yield
-            wrapped_child = ElementWrapper.new(child, @parent_wrapper)
-            yield wrapped_child
+            yield ElementWrapper.new(child, @parent_wrapper)
           end
 
           child
         end
       end
+
+      # Shared factory: create an XmlElement with optional attributes.
+      # Public so ElementWrapper can call it without an instance.
+      #
+      # @param name [String] Element name
+      # @param attributes [Hash] Optional attributes
+      # @return [DataModel::XmlElement]
+      def self.build_element(name, attributes)
+        element = Lutaml::Xml::DataModel::XmlElement.new(name)
+        attributes&.each do |attr_name, attr_value|
+          attr = Lutaml::Xml::DataModel::XmlAttribute.new(
+            attr_name.to_s, attr_value.to_s
+          )
+          element.add_attribute(attr)
+        end
+        element
+      end
     end
   end
 end

data/lib/lutaml/xml/transformation/rule_applier.rb

@@ -239,7 +239,7 @@ register_id)
         # @param model_class [Class] The model class
         # @param model_instance [Object] The model instance
         def apply_custom_method(parent, rule, model_class, model_instance)
-          wrapper = ::Lutaml::Xml::CustomMethodWrapper.new(parent, rule)
+          wrapper = ::Lutaml::Xml::CustomMethodWrapper.new(parent)
           mapper_instance = model_class.new
           mapper_instance.send(rule.custom_methods[:to], model_instance,
                                parent, wrapper)

data/lib/lutaml/xml/xml_element.rb

@@ -257,33 +257,26 @@ module Lutaml
         return @order_cache if @order_cache
 
         @order_cache = children.filter_map do |child|
-          if child.text?
+          if child.cdata?
+            Lutaml::Xml::Element.new("Text", "#cdata-section",
+                                     text_content: child.text,
+                                     node_type: :cdata)
+          elsif child.text?
             next if child.text.nil?
 
-            # For text nodes:
-            # - name is "text" for backward compatibility with tests
-            # - text_content contains the actual text for round-trip serialization
-            # - node_type explicitly marks this as a text node
             Lutaml::Xml::Element.new("Text", "text",
                                      text_content: child.text,
                                      node_type: :text)
-          elsif child.cdata?
-            # For CDATA sections:
-            # - name is "#cdata-section" for backward compatibility
-            # - text_content contains the actual CDATA content
-            # - node_type explicitly marks this as CDATA
-            Lutaml::Xml::Element.new("Text", "#cdata-section",
-                                     text_content: child.text,
-                                     node_type: :cdata)
           elsif child.comment?
             Lutaml::Xml::Element.new("Comment", "comment",
                                      text_content: child.text,
                                      node_type: :comment)
+          elsif child.processing_instruction?
+            Lutaml::Xml::Element.new("ProcessingInstruction",
+                                     child.unprefixed_name,
+                                     text_content: child.text,
+                                     node_type: :processing_instruction)
           else
-            # For regular elements:
-            # - name is the actual element name
-            # - node_type explicitly marks this as an element
-            # - namespace_uri and namespace_prefix preserve namespace info for rule matching
             Lutaml::Xml::Element.new("Element", child.unprefixed_name,
                                      node_type: :element,
                                      namespace_uri: child.namespace_uri,
@@ -303,14 +296,14 @@ module Lutaml
 
       def text
         return @text if children.empty?
-        return text_children.map(&:text) if children.count > 1
+        return text_children.map(&:text) if content_bearing_children_count > 1
 
         text_children.map(&:text).join
       end
 
       def cdata
         return @text if children.empty?
-        return cdata_children.map(&:text) if children.count > 1
+        return cdata_children.map(&:text) if content_bearing_children_count > 1
 
         cdata_children.map(&:text).join
       end
@@ -330,7 +323,8 @@ module Lutaml
 
         @element_children = children.reject do |child|
           child.is_a?(String) || child.is_a?(Symbol) ||
-            (child.is_a?(XmlElement) && child.text?)
+            (child.is_a?(XmlElement) &&
+              (child.text? || child.processing_instruction?))
         end
       end
 
@@ -389,6 +383,8 @@ module Lutaml
 
         @children_index = {}
         @children.each do |child|
+          next if child.is_a?(XmlElement) && child.processing_instruction?
+
           key = child.namespaced_name
           @children_index[key] ||= []
           @children_index[key] << child
@@ -432,6 +428,14 @@ module Lutaml
 
       private
 
+      # Count children that bear content (excludes processing instructions).
+      # Used to determine if content is mixed (multiple content nodes).
+      def content_bearing_children_count
+        children.count do |child|
+          !child.is_a?(XmlElement) || !child.processing_instruction?
+        end
+      end
+
       # Backward compatibility: infer node_type from name
       # This allows old code that doesn't pass node_type to still work
       def infer_node_type_from_name(name)

data/spec/lutaml/xml/adapter/base_adapter_regression_spec.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "lutaml/model"
+require "lutaml/xml"
+require "lutaml/xml/adapter/nokogiri_adapter"
+require "lutaml/xml/adapter/ox_adapter"
+require "lutaml/xml/adapter/oga_adapter"
+require "lutaml/xml/adapter/rexml_adapter"
+
+# Regression tests for BaseAdapter refactoring.
+# Each test guards a specific bug fix to prevent re-introduction.
+# Run against all 4 adapters to ensure consistent behavior.
+RSpec.shared_examples "base adapter regressions" do |adapter_class|
+  let(:adapter) { adapter_class }
+
+  describe "CDATA preservation in mixed content" do
+    let(:xml_with_cdata) do
+      "<root><![CDATA[Hello]]><b>world</b><![CDATA[!]]></root>"
+    end
+
+    it "preserves CDATA wrapping for mixed content string nodes" do
+      doc = adapter.parse(xml_with_cdata)
+      output = doc.to_xml
+
+      expect(output).to include("<![CDATA[Hello]]>")
+      expect(output).to include("<![CDATA[!]]>")
+    end
+  end
+
+  describe "XML comment preservation in serialization" do
+    let(:xml_with_comment) do
+      "<root><a/><!--middle comment--><b/></root>"
+    end
+
+    it "preserves comments during round-trip" do
+      doc = adapter.parse(xml_with_comment)
+      output = doc.to_xml
+
+      expect(output).to include("<!--middle comment-->")
+    end
+  end
+
+  describe "processing instructions do not affect text shape" do
+    let(:xml_with_pi_and_text) do
+      "<root>hello<?pi data?></root>"
+    end
+
+    let(:xml_with_only_pi) do
+      "<root><?pi data?></root>"
+    end
+
+    it "returns text as a string when PI is alongside text" do
+      doc = adapter.parse(xml_with_pi_and_text)
+
+      # text should be a string, not an array —
+      # PIs should not make plain text look like mixed content
+      expect(doc.text).to be_a(String)
+      expect(doc.text).to eq("hello")
+    end
+
+    it "returns empty string for text when element has only PI" do
+      doc = adapter.parse(xml_with_only_pi)
+
+      expect(doc.text).to be_a(String)
+      expect(doc.text).to eq("")
+    end
+  end
+
+  describe "processing instructions excluded from parse_element" do
+    let(:xml_with_pi) do
+      "<root><?foo ignored?><bar>content</bar></root>"
+    end
+
+    it "does not include PI in elements hash" do
+      doc = adapter.parse(xml_with_pi)
+      hash = doc.to_h
+
+      elements = hash["elements"]
+      expect(elements).to have_key("bar")
+      # PI should not appear as an element key
+      expect(elements.keys).not_to include("foo")
+    end
+  end
+
+  describe "ASCII-8BIT encoding round-trip" do
+    let(:binary_xml) { "<root>\xC2\xB5</root>".b }
+
+    it "round-trips binary-tagged UTF-8 content without encoding error" do
+      doc = adapter.parse(binary_xml)
+
+      expect { doc.to_xml }.not_to raise_error
+      expect(doc.to_xml).to include("\u00B5") # micro sign
+    end
+
+    it "does not use ASCII-8BIT as output encoding" do
+      doc = adapter.parse(binary_xml)
+      output = doc.to_xml
+
+      expect(output.encoding).not_to eq(Encoding::ASCII_8BIT)
+    end
+  end
+
+  describe "namespaced_attr_name helper arity" do
+    it "resolves single-arg namespaced_attr_name from AdapterHelpers" do
+      # This verifies the AdapterHelpers version (single Moxml attribute arg)
+      # is accessible and not shadowed by a 2-arg def self. method
+      expect(adapter).to respond_to(:namespaced_attr_name)
+
+      # The method should accept 1 argument (a Moxml attribute object)
+      method = adapter.method(:namespaced_attr_name)
+      expect(method.arity).to eq(1)
+    end
+  end
+
+  describe "XmlParser helper methods are private" do
+    it "does not expose normalize_xml_for_parse as a public class method" do
+      expect(adapter.public_methods).not_to include(:normalize_xml_for_parse)
+    end
+
+    it "does not expose parse_with_moxml as a public class method" do
+      expect(adapter.public_methods).not_to include(:parse_with_moxml)
+    end
+
+    it "does not expose raise_empty_document_error as a public class method" do
+      expect(adapter.public_methods).not_to include(:raise_empty_document_error)
+    end
+
+    it "exposes parse as a public class method" do
+      expect(adapter.public_methods).to include(:parse)
+    end
+  end
+end
+
+RSpec.describe Lutaml::Xml::Adapter::BaseAdapter do
+  context "with NokogiriAdapter" do
+    it_behaves_like "base adapter regressions", Lutaml::Xml::Adapter::NokogiriAdapter
+  end
+
+  context "with OxAdapter" do
+    it_behaves_like "base adapter regressions", Lutaml::Xml::Adapter::OxAdapter
+  end
+
+  context "with OgaAdapter" do
+    it_behaves_like "base adapter regressions", Lutaml::Xml::Adapter::OgaAdapter
+  end
+
+  context "with RexmlAdapter" do
+    it_behaves_like "base adapter regressions", Lutaml::Xml::Adapter::RexmlAdapter
+  end
+end

data/spec/lutaml/xml/adapter/order_spec.rb

@@ -0,0 +1,150 @@
+require "spec_helper"
+require "lutaml/model"
+require "lutaml/xml"
+require "lutaml/xml/adapter/nokogiri_adapter"
+require "lutaml/xml/adapter/ox_adapter"
+require "lutaml/xml/adapter/oga_adapter"
+require "lutaml/xml/adapter/rexml_adapter"
+
+module XmlAdapterSharedFeaturesSpec
+  class ProcessingInstructionLookupElement < Lutaml::Model::Serializable
+    attribute :foo, :string
+
+    xml do
+      root "root"
+      map_element "foo", to: :foo
+    end
+  end
+end
+
+RSpec.describe "XML adapter order metadata" do
+  shared_examples "consistent order metadata" do |adapter_class|
+    let(:xml) do
+      "<root>before<![CDATA[cdata text]]><?pi data?><child/>after</root>"
+    end
+
+    let(:document) { adapter_class.parse(xml) }
+
+    let(:expected_order) do
+      [
+        ["Text", "text", :text, "before"],
+        ["Text", "#cdata-section", :cdata, "cdata text"],
+        ["ProcessingInstruction", "pi", :processing_instruction, "data"],
+        ["Element", "child", :element, nil],
+        ["Text", "text", :text, "after"],
+      ]
+    end
+
+    def order_data(order)
+      order.map do |item|
+        [item.type, item.name, item.node_type, item.text_content]
+      end
+    end
+
+    it "uses the same order representation for root, document, and class order" do
+      expect(order_data(document.root.order)).to eq(expected_order)
+      expect(order_data(document.order)).to eq(expected_order)
+      expect(order_data(adapter_class.order_of(document.root))).to eq(expected_order)
+    end
+
+    it "parses processing instructions as first-class XML nodes" do
+      instruction = document.root.children.find(&:processing_instruction?)
+
+      expect(instruction).not_to be_nil
+      expect(instruction.name).to eq("pi")
+      expect(instruction.text).to eq("data")
+      expect(instruction.node_type).to eq(:processing_instruction)
+    end
+
+    it "preserves processing instructions and CDATA when serializing parsed XML" do
+      output = document.to_xml
+
+      expect(output).to include("<?pi data?>")
+      expect(output).to include("<![CDATA[cdata text]]>")
+    end
+
+    it "uses the same order representation through to_h item_order" do
+      parsed_hash = nil
+
+      expect { parsed_hash = document.to_h }.not_to raise_error
+      expect(order_data(parsed_hash.item_order)).to eq(expected_order)
+    end
+  end
+
+  shared_examples "consistent shared adapter features" do |adapter_class|
+    around do |example|
+      old_adapter = Lutaml::Model::Config.xml_adapter
+      Lutaml::Model::Config.xml_adapter = adapter_class
+      example.run
+    ensure
+      Lutaml::Model::Config.xml_adapter = old_adapter
+    end
+
+    it "uses shared parse metadata preservation" do
+      xml = <<~XML
+        <?xml version="1.0"?>
+        <!DOCTYPE root SYSTEM "root.dtd">
+        <root><child/></root>
+      XML
+
+      document = adapter_class.parse(xml)
+
+      expect(document.xml_declaration[:had_declaration]).to be true
+      expect(document.doctype).to include(name: "root",
+                                          public_id: nil,
+                                          system_id: "root.dtd")
+      expect(document.to_xml(declaration: true)).to include(
+        '<!DOCTYPE root SYSTEM "root.dtd">',
+      )
+    end
+
+    it "parses binary UTF-8 XML input through shared normalization" do
+      document = adapter_class.parse("<root><name>μ</name></root>".b)
+
+      expect(document.root.name).to eq("root")
+      expect(document.root.element_children.first.text).to eq("μ")
+    end
+
+    it "transcodes non-UTF-8 strings from their declared encoding" do
+      xml = "<root><name>\xC2\xA3</name></root>".b
+      xml.force_encoding("ISO-8859-1")
+      document = adapter_class.parse(xml)
+
+      expect(document.root.element_children.first.text).to eq("£")
+    end
+
+    it "preserves processing instructions without matching them as elements" do
+      xml = "<root><?foo ignored?><foo>bar</foo></root>"
+      document = adapter_class.parse(xml)
+
+      expect(document.root.children.any?(&:processing_instruction?)).to be true
+      expect(document.root.element_children.map(&:text)).to eq(["bar"])
+      expect(document.root.find_children_by_name("foo").map(&:text)).to eq(["bar"])
+      expect(
+        XmlAdapterSharedFeaturesSpec::ProcessingInstructionLookupElement
+          .from_xml(xml)
+          .foo,
+      ).to eq("bar")
+    end
+  end
+
+  describe Lutaml::Xml::Adapter::NokogiriAdapter do
+    it_behaves_like "consistent order metadata", described_class
+    it_behaves_like "consistent shared adapter features", described_class
+  end
+
+  describe Lutaml::Xml::Adapter::OxAdapter do
+    it_behaves_like "consistent order metadata", described_class
+    it_behaves_like "consistent shared adapter features", described_class
+  end
+
+  describe Lutaml::Xml::Adapter::OgaAdapter do
+    it_behaves_like "consistent order metadata", described_class
+    it_behaves_like "consistent shared adapter features", described_class
+  end
+
+  describe Lutaml::Xml::Adapter::RexmlAdapter do
+    it_behaves_like "consistent order metadata", described_class
+    it_behaves_like "consistent shared adapter features", described_class
+  end
+end