lutaml-model 0.8.5 → 0.8.6

data/lib/lutaml/xml/adapter/xml_parser.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Xml
+    module Adapter
+      # Class methods for parsing XML input.
+      #
+      # Extracted from BaseAdapter — parsing is a distinct lifecycle phase
+      # with no instance state dependency.
+      #
+      # Subclasses must define:
+      # - MOXML_ADAPTER — Moxml adapter class for parsing
+      # - PARSED_ELEMENT_CLASS — element wrapper class
+      # - PARSE_ERROR_CLASS — error class to rescue (nil to skip)
+      # - EMPTY_DOCUMENT_ERROR_MESSAGE — error message for empty docs
+      # - EMPTY_DOCUMENT_ERROR_TYPE — :invalid_format or :parse_exception
+      module XmlParser
+        def parse(xml, options = {})
+          parse_encoding = encoding(xml, options)
+          raw_xml = xml
+          xml = normalize_xml_for_parse(xml)
+          parsed = parse_with_moxml(xml, parse_encoding)
+          root_element = parsed.root
+
+          raise_empty_document_error if root_element.nil?
+
+          root = self::PARSED_ELEMENT_CLASS.new(root_element)
+          doc_pis = extract_document_processing_instructions(parsed)
+          root.processing_instructions = doc_pis unless doc_pis.empty?
+          new(root, parse_encoding, **parse_document_options(raw_xml))
+        end
+
+        private
+
+        def normalize_xml_for_parse(xml)
+          return xml unless xml.is_a?(String)
+          return xml if xml.encoding == Encoding::UTF_8 && xml.valid_encoding?
+
+          if xml.encoding == Encoding::ASCII_8BIT
+            normalized_xml = xml.dup
+            normalized_xml.force_encoding(Encoding::UTF_8)
+            return normalized_xml if normalized_xml.valid_encoding?
+          end
+
+          xml.encode(Encoding::UTF_8,
+                     invalid: :replace,
+                     undef: :replace,
+                     replace: "?")
+        end
+
+        def parse_with_moxml(xml, parse_encoding)
+          parse_error_class = self::PARSE_ERROR_CLASS
+          unless parse_error_class
+            return self::MOXML_ADAPTER.parse(xml,
+                                             encoding: parse_encoding)
+          end
+
+          begin
+            self::MOXML_ADAPTER.parse(xml, encoding: parse_encoding)
+          rescue parse_error_class => e
+            raise Lutaml::Model::InvalidFormatError.new(:xml, e.message)
+          end
+        end
+
+        def parse_document_options(xml)
+          {
+            doctype: extract_doctype_from_xml(xml),
+            xml_declaration: DeclarationHandler.extract_xml_declaration(xml),
+          }
+        end
+
+        def raise_empty_document_error
+          message = self::EMPTY_DOCUMENT_ERROR_MESSAGE
+
+          case self::EMPTY_DOCUMENT_ERROR_TYPE
+          when :parse_exception
+            require "rexml/document"
+            raise REXML::ParseException.new(message)
+          else
+            raise Lutaml::Model::InvalidFormatError.new(:xml, message)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/xml/adapter/xml_serializer.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Xml
+    module Adapter
+      # Handles the XML serialization pipeline.
+      #
+      # Responsible for converting model instances and XmlElement trees
+      # into XML output via builder objects. Includes the top-level
+      # `to_xml` entry point and supporting methods for rendering
+      # XmlElement structures with namespace declaration plans.
+      module XmlSerializer
+        # Add text content to XML builder
+        #
+        # @param xml [Builder] the XML builder
+        # @param value [Object] the value to add
+        # @param attribute [Attribute, nil] the attribute definition
+        # @param cdata [Boolean] whether to use CDATA
+        def add_value(xml, value, attribute, cdata: false)
+          if !value.nil?
+            if attribute.nil?
+              # For delegated attributes where attribute is nil, just use the raw value
+              xml.add_text(xml, value.to_s, cdata: cdata)
+            elsif attribute.transform.is_a?(Class) && attribute.transform < Lutaml::Model::ValueTransformer
+              # Value has already been transformed, use it directly
+              xml.add_text(xml, value.to_s, cdata: cdata)
+            else
+              # Normal serialization through attribute type system
+              serialized_value = attribute.serialize(value, :xml, register)
+              if attribute.raw?
+                xml.add_xml_fragment(xml, value)
+              elsif serialized_value.is_a?(Hash)
+                serialized_value.each do |key, val|
+                  xml.create_and_add_element(key) do |element|
+                    element.text(val)
+                  end
+                end
+              else
+                xml.add_text(xml, serialized_value, cdata: cdata)
+              end
+            end
+          end
+        end
+
+        def to_xml(options = {})
+          # Accept xml_declaration from options if present (for model serialization)
+          @xml_declaration = options[:xml_declaration] if options[:xml_declaration]
+
+          encoding = determine_encoding(options)
+          builder_options = {}
+          builder_options[:encoding] = encoding if encoding
+
+          builder = self.class::BUILDER_CLASS.build(builder_options) do |xml|
+            if root.is_a?(self.class::PARSED_ELEMENT_CLASS)
+              root.build_xml(xml)
+            else
+              build_serializable_xml(xml, options)
+            end
+          end
+
+          finalize_adapter_xml(builder.to_xml, encoding, options)
+        end
+
+        def build_serializable_xml(xml, options)
+          original_model = nil
+          xml_element = transformable_xml_element(options) do |model|
+            original_model = model
+          end
+
+          if xml_element
+            render_xml_element(xml, xml_element, original_model, options)
+          else
+            render_legacy_model(xml, options)
+          end
+        end
+
+        # Build XML from XmlDataModel::XmlElement structure with a declaration plan
+        #
+        # @param builder [Builder] XML builder
+        # @param xml_element [XmlDataModel::XmlElement] root element
+        # @param plan [DeclarationPlan] the declaration plan
+        # @param options [Hash] serialization options
+        def build_xml_element_with_plan(builder, xml_element, plan,
+    options = {})
+          # Add processing instructions before the root element
+          if xml_element.respond_to?(:processing_instructions)
+            xml_element.processing_instructions.each do |pi|
+              builder.add_processing_instruction(pi.target, pi.content)
+            end
+          end
+
+          build_plan_node(builder, xml_element, plan.root_node, plan: plan,
+                                                                options: options)
+        end
+
+        private
+
+        def transformable_xml_element(options)
+          return root if root.is_a?(Lutaml::Xml::DataModel::XmlElement)
+
+          mapper_class = options[:mapper_class] || root.class
+          xml_mapping = mapper_class.mappings_for(:xml)
+
+          return nil if xml_mapping.raw_mapping&.custom_methods&.[](:to)
+
+          yield(root)
+          mapper_class.transformation_for(:xml, register).transform(root,
+                                                                    options)
+        end
+
+        def render_xml_element(xml, xml_element, original_model, options)
+          mapper_class = options[:mapper_class] || xml_element.class
+          mapping = mapper_class.mappings_for(:xml)
+          plan = declaration_plan_for(
+            xml_element,
+            mapping,
+            options_with_original_namespace_data(options, original_model,
+                                                 xml_element),
+            mapper_class,
+          )
+
+          render_options = options.merge(is_root_element: true)
+          render_options[:original_model] = original_model if original_model
+          build_xml_element_with_plan(xml, xml_element, plan, render_options)
+        end
+
+        def render_legacy_model(xml, options)
+          mapper_class = options[:mapper_class] || root.class
+          xml_mapping = mapper_class.mappings_for(:xml)
+          plan = declaration_plan_for(root, xml_mapping, options, mapper_class)
+
+          build_element_with_plan(xml, root, plan, options)
+        end
+
+        def declaration_plan_for(element, mapping, options, mapper_class)
+          needs = NamespaceCollector.new(register).collect(
+            element, mapping, mapper_class: mapper_class
+          )
+          DeclarationPlanner.new(register).plan(element, mapping, needs,
+                                                options: options)
+        end
+
+        def options_with_original_namespace_data(options, original_model,
+    xml_element)
+          original_ns_uris = {}
+          stored_plan = nil
+
+          if original_model
+            mapping_for_original = options[:mapper_class]&.mappings_for(:xml) ||
+              original_model.class.mappings_for(:xml)
+            original_ns_uris = collect_original_namespace_uris(
+              original_model, mapping_for_original
+            )
+            if original_model.is_a?(Lutaml::Model::Serialize)
+              stored_plan = original_model.import_declaration_plan
+            end
+          elsif xml_element.is_a?(Lutaml::Xml::DataModel::XmlElement)
+            original_ns_uri = xml_element.original_namespace_uri
+            if original_ns_uri
+              mapper_class = options[:mapper_class] || xml_element.class
+              xml_mapping = begin
+                mapper_class.mappings_for(:xml)
+              rescue StandardError
+                nil
+              end
+              if xml_mapping&.namespace_class
+                canonical_uri = xml_mapping.namespace_class.uri
+                if canonical_uri != original_ns_uri
+                  original_ns_uris[canonical_uri] =
+                    original_ns_uri
+                end
+              end
+            end
+          end
+
+          options_with_original_ns = options.merge(
+            __original_namespace_uris: original_ns_uris,
+          )
+          if stored_plan
+            options_with_original_ns[:stored_xml_declaration_plan] =
+              stored_plan
+          end
+          options_with_original_ns
+        end
+
+        def finalize_adapter_xml(xml_data, encoding, options)
+          result = ""
+          if (options[:encoding] && !options[:encoding].nil?) ||
+              should_include_declaration?(options)
+            result += generate_declaration(options)
+          end
+
+          doctype_to_use = options[:doctype] || @doctype
+          if doctype_to_use && !options[:omit_doctype]
+            result += generate_doctype_declaration(doctype_to_use)
+          end
+
+          result += xml_data
+          if encoding && result.encoding.to_s.upcase != encoding.to_s.upcase
+            result = result.encode(encoding)
+          end
+          result
+        end
+
+        def text_content_for_xml(value)
+          ::Moxml::Adapter::Base.preprocess_entities(value.to_s)
+        end
+
+        def build_plan_node(xml, xml_element, element_node, plan: nil,
+    options: {}, previous_sibling_had_xmlns_blank: false)
+          qualified_name = element_node.qualified_name
+          attributes = {}
+
+          original_ns_uris = plan&.original_namespace_uris || {}
+          element_node.hoisted_declarations.each do |key, uri|
+            next if uri == "http://www.w3.org/XML/1998/namespace"
+
+            effective_uri = if self.class.fpi?(uri)
+                              self.class.fpi_to_urn(uri)
+                            else
+                              original_ns_uris[uri] || uri
+                            end
+
+            xmlns_name = key ? "xmlns:#{key}" : "xmlns"
+            attributes[xmlns_name] = effective_uri
+          end
+
+          xml_element.attributes.each_with_index do |xml_attr, idx|
+            attr_node = element_node.attribute_nodes[idx]
+            attributes[attr_node.qualified_name] = xml_attr.value.to_s
+          end
+
+          if xml_element.respond_to?(:xsi_nil) && xml_element.xsi_nil
+            attributes["xsi:nil"] = "true"
+          end
+
+          attributes.merge!(element_node.schema_location_attr) if element_node.schema_location_attr
+          needs_xmlns_blank = element_node.needs_xmlns_blank &&
+            (options[:pretty] ? !previous_sibling_had_xmlns_blank : true)
+          attributes["xmlns"] = "" if needs_xmlns_blank
+
+          xml.create_and_add_element(qualified_name, attributes: attributes) do
+            if xml_element.respond_to?(:raw_content)
+              raw_content = xml_element.raw_content
+              if raw_content && !raw_content.to_s.empty?
+                xml.add_xml_fragment(xml, raw_content.to_s)
+                return
+              end
+            end
+
+            child_element_index = 0
+            previous_child_had_xmlns_blank = false
+            xml_element.children.each do |xml_child|
+              case xml_child
+              when Lutaml::Xml::DataModel::XmlElement
+                child_node = element_node.element_nodes[child_element_index]
+                child_element_index += 1
+
+                build_plan_node(
+                  xml,
+                  xml_child,
+                  child_node,
+                  plan: plan,
+                  options: options,
+                  previous_sibling_had_xmlns_blank: previous_child_had_xmlns_blank,
+                )
+                previous_child_had_xmlns_blank ||= child_node.needs_xmlns_blank
+              when Lutaml::Xml::DataModel::XmlComment
+                xml.add_comment(xml_child.content)
+              when String
+                if xml_element.cdata
+                  xml.cdata(xml_child.to_s)
+                else
+                  xml.text(text_content_for_xml(xml_child))
+                end
+              end
+            end
+
+            if xml_element.text_content
+              if xml_element.cdata
+                xml.cdata(xml_element.text_content.to_s)
+              else
+                xml.text(text_content_for_xml(xml_element.text_content))
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/xml/adapter.rb

@@ -4,7 +4,6 @@ module Lutaml
   module Xml
     # Adapter namespace for XML adapter internal classes
     module Adapter
-      autoload :XmlSerialization, "#{__dir__}/adapter/xml_serialization"
       autoload :AdapterHelpers, "#{__dir__}/adapter/adapter_helpers"
       autoload :BaseAdapter, "#{__dir__}/adapter/base_adapter"
       autoload :NamespaceData, "#{__dir__}/adapter/namespace_data"

data/lib/lutaml/xml/adapter_element.rb

@@ -15,6 +15,7 @@ module Lutaml
                     when Moxml::Cdata then :cdata
                     when Moxml::Text then :text
                     when Moxml::Comment then :comment
+                    when Moxml::ProcessingInstruction then :processing_instruction
                     else :element
                     end
 
@@ -50,6 +51,10 @@ module Lutaml
                  EncodingNormalizer.normalize_to_utf8(node.content)
                when Moxml::Comment
                  EncodingNormalizer.normalize_to_utf8(node.content)
+               when Moxml::ProcessingInstruction
+                 EncodingNormalizer.normalize_to_utf8(
+                   node.content.to_s.sub(/\A\s+/, ""),
+                 )
                end
 
         name = adapter_class.name_of(node)
@@ -85,6 +90,8 @@ module Lutaml
           builder.add_text(builder.current_node, @text.to_s, cdata: true)
         elsif comment?
           builder.add_comment(builder.current_node, @text.to_s)
+        elsif processing_instruction?
+          builder.add_processing_instruction(name, @text.to_s)
         elsif text? && !element?
           builder.add_text(builder.current_node, build_text_for_xml.to_s)
         else
@@ -166,7 +173,6 @@ module Lutaml
         return [] unless node.children
 
         node.children.filter_map do |child|
-          next if child.is_a?(Moxml::ProcessingInstruction)
           next if (child.is_a?(Moxml::Text) || child.is_a?(Moxml::Cdata)) && child.content.empty?
 
           self.class.new(child, parent: self,

data/lib/lutaml/xml/builder/base.rb

@@ -96,7 +96,6 @@ module Lutaml
         def add_processing_instruction(target, content)
           pi = @doc.create_processing_instruction(target.to_s, content.to_s)
           if current_element.is_a?(Moxml::Document)
-            # Add before root element or at end if no root
             root_node = current_element.root
             if root_node
               root_node.add_previous_sibling(pi)

data/lib/lutaml/xml/data_model.rb

@@ -82,9 +82,17 @@ module Lutaml
 
         # Add a child element or text node
         #
-        # @param child [XmlElement, String] Child to add
+        # @param child [XmlElement, String, XmlComment] Child to add
         # @return [self]
+        # @raise [TypeError] if child is not a supported type
         def add_child(child)
+          unless child.is_a?(XmlElement) || child.is_a?(String) ||
+              child.is_a?(XmlComment)
+            raise TypeError,
+                  "XmlElement#add_child expects XmlElement, String, or " \
+                  "XmlComment, got #{child.class}"
+          end
+
           @children << child
           self
         end

data/lib/lutaml/xml/document.rb

@@ -98,6 +98,7 @@ module Lutaml
 
         element.children.each do |child|
           next if child.respond_to?(:comment?) && child.comment?
+          next if child.respond_to?(:processing_instruction?) && child.processing_instruction?
 
           if klass&.<= Serialize
             attr = klass.attribute_for_child(self.class.name_of(child),
@@ -252,7 +253,8 @@ module Lutaml
         # EntityReference nodes are text-like and should not trigger Array return.
         # For text + entity without elements, return joined String.
         has_element_children = @root.children.any? do |child|
-          !child.text? && !entity_reference_node?(child)
+          !child.text? && !entity_reference_node?(child) &&
+            !(child.respond_to?(:processing_instruction?) && child.processing_instruction?)
         end
         return @root.text_children.map(&:text) if has_element_children
 

data/lib/lutaml/xml/element.rb

@@ -11,7 +11,7 @@ module Lutaml
       # @param type [String] "Text" or "Element" (deprecated, use node_type)
       # @param name [String] The element name or text marker
       # @param text_content [String, nil] Actual text content for text nodes
-      # @param node_type [Symbol, nil] The node type (:text, :cdata, :element, :comment)
+      # @param node_type [Symbol, nil] The node type (:text, :cdata, :element, :comment, :processing_instruction)
       # @param namespace_uri [String, nil] The namespace URI of this element
       # @param namespace_prefix [String, nil] The namespace prefix of this element
       def initialize(type, name, text_content: nil, node_type: nil,
@@ -38,18 +38,21 @@ module Lutaml
         @node_type == :cdata
       end
 
-      # Check if this is a comment node
-      def comment?
-        @node_type == :comment
-      end
-
       # Check if this is a regular element
       def element?
         @node_type == :element
       end
 
+      def processing_instruction?
+        @node_type == :processing_instruction
+      end
+
+      def comment?
+        @node_type == :comment
+      end
+
       def element_tag
-        @name unless text? || cdata? || comment?
+        @name unless text? || cdata? || comment? || processing_instruction?
       end
 
       def eql?(other)
@@ -76,14 +79,14 @@ module Lutaml
       def infer_node_type(type, name)
         return :text if type == "Text" && name != "#cdata-section"
         return :cdata if name == "#cdata-section" || (type == "Text" && name == "#cdata-section")
-        return :comment if type == "Comment"
+        return :processing_instruction if type == "ProcessingInstruction"
 
         :element
       end
 
       def register_liquid_methods
-        %i[text? comment? element_tag type name text_content node_type
-           cdata? namespace_uri namespace_prefix].each do |attr_name|
+        %i[text? element_tag type name text_content node_type
+           cdata? processing_instruction? namespace_uri namespace_prefix].each do |attr_name|
           self.class.register_drop_method(attr_name)
         end
 

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

@@ -262,7 +262,7 @@ module Lutaml
           parent = klass.superclass
           return nil unless parent < Lutaml::Model::Serializable
 
-          parent_mapping = parent.mappings[:xml] if parent.respond_to?(:mappings)
+          parent_mapping = parent.mappings[:xml]
           return parent if parent_mapping
 
           superclass_with_xml_mapping(parent)
@@ -274,7 +274,7 @@ module Lutaml
           all_ns = (existing_ns + parent_ns).uniq
           @xml_mapping.namespace_scope(all_ns) if all_ns.any?
 
-          if parent_mapping.respond_to?(:namespace_scope_config) &&
+          if parent_mapping.is_a?(Lutaml::Xml::Mapping) &&
               (parent_ns_config = parent_mapping.namespace_scope_config) &&
               parent_ns_config.any?
             existing_ns_config = @xml_mapping.namespace_scope_config || []
@@ -284,59 +284,36 @@ module Lutaml
         end
 
         def inherit_xml_elements(parent_mapping)
-          parent_mapping.mapping_elements_hash.each do |key, rule|
-            existing = @xml_mapping.elements_hash[key]
-            if existing.nil?
-              @xml_mapping.elements_hash[key] =
-                rule.deep_dup
-            elsif existing.is_a?(Array) && rule.is_a?(Array)
-              merged = existing + rule.reject do |r|
-                existing.any? do |e|
-                  e.eql?(r)
-                end
-              end
-              @xml_mapping.elements_hash[key] = merged
-            elsif existing.is_a?(Array)
-              existing << rule.deep_dup unless existing.any? do |e|
-                e.eql?(rule)
-              end
-            elsif rule.is_a?(Array)
-              unless rule.any? { |r| r.eql?(existing) }
-                @xml_mapping.elements_hash[key] =
-                  [existing, *rule]
-              end
-            elsif !existing.eql?(rule)
-              @xml_mapping.elements_hash[key] =
-                [existing, rule.deep_dup]
-            end
-          end
+          inherit_xml_mapping_hash(parent_mapping,
+                                   :mapping_elements_hash,
+                                   @xml_mapping.elements_hash)
         end
 
         def inherit_xml_attributes(parent_mapping)
-          parent_mapping.mapping_attributes_hash.each do |key, rule|
-            existing = @xml_mapping.attributes_hash[key]
+          inherit_xml_mapping_hash(parent_mapping,
+                                   :mapping_attributes_hash,
+                                   @xml_mapping.attributes_hash)
+        end
+
+        def inherit_xml_mapping_hash(parent_mapping, source_method, target_hash)
+          parent_mapping.public_send(source_method).each do |key, rule|
+            existing = target_hash[key]
             if existing.nil?
-              @xml_mapping.attributes_hash[key] =
-                rule.deep_dup
+              target_hash[key] = rule.deep_dup
             elsif existing.is_a?(Array) && rule.is_a?(Array)
-              merged = existing + rule.reject do |r|
-                existing.any? do |e|
-                  e.eql?(r)
-                end
+              target_hash[key] = existing + rule.reject do |r|
+                existing.any? { |e| e.eql?(r) }
               end
-              @xml_mapping.attributes_hash[key] = merged
             elsif existing.is_a?(Array)
               existing << rule.deep_dup unless existing.any? do |e|
                 e.eql?(rule)
               end
             elsif rule.is_a?(Array)
-              unless rule.any? { |r| r.eql?(existing) }
-                @xml_mapping.attributes_hash[key] =
-                  [existing, *rule]
+              target_hash[key] = [existing, *rule] unless rule.any? do |r|
+                r.eql?(existing)
               end
             elsif !existing.eql?(rule)
-              @xml_mapping.attributes_hash[key] =
-                [existing, rule.deep_dup]
+              target_hash[key] = [existing, rule.deep_dup]
             end
           end
         end