lutaml-model 0.8.24 → 0.8.28

data/lib/lutaml/xml/plan_hydrator.rb

@@ -4,76 +4,337 @@ module Lutaml
   module Xml
     # Hydrates model instances from a Descriptor#walk PlanValue tree,
     # keyed by each value's producing row name (never position — rows
-    # for missing elements are simply absent). Builds constructor
-    # kwargs recursively and instantiates through .new, so typing,
-    # defaults, and collection semantics all ride the constructor.
+    # for missing elements are simply absent). Native rows build
+    # constructor kwargs; deferred rows (custom methods, polymorphism,
+    # unions) capture their subtree verbatim and interpret it
+    # post-walk — the fragment parse runs the existing interpretive
+    # machinery on just that island. Delegate rules hydrate
+    # post-instance onto their target object. Collection rows route
+    # natively when a single one exists, else through callback rows
+    # (their values echo name and type_tag; native collection values
+    # echo neither — leptris-ruby#220).
     module PlanHydrator
       class << self
         # plan: the compiler's entry for model_class
         # value: the walk root PlanValue (element)
-        def call(model_class, plan, value)
-          kwargs = attributes_kwargs(plan, value)
-          kwargs.merge!(children_kwargs(model_class, plan, value))
-          model_class.new(**kwargs)
+        # node: the parsed source element (leptris); ordered/mixed
+        #   plans rebuild element_order from it and ordered children
+        #   hydrate natively against their own nodes
+        def call(model_class, plan, value, parent: nil, node: nil)
+          buckets = node && plan[:needs_nodes] ? element_buckets(node) : nil
+          attr_kwargs = attributes_kwargs(plan, value)
+          child_kwargs, children, delegates =
+            children_kwargs(model_class, plan, value, buckets)
+          plan[:collection_defaults].each do |name|
+            next if attr_kwargs.key?(name) || child_kwargs.key?(name)
+
+            child_kwargs[name] = []
+          end
+          instance = model_class.new(**attr_kwargs, **child_kwargs)
+          instance.lutaml_parent = parent if parent
+          instance.lutaml_root ||= parent&.lutaml_root || parent
+          instance.element_order = PlanOrder.build(node) if node && plan[:ordered]
+          children.each do |child|
+            child.lutaml_parent = instance
+            child.lutaml_root ||= instance.lutaml_root || instance
+          end
+          interpret_deferred(model_class, plan, value, instance, node, buckets)
+          route_delegates(delegates, instance)
+          instance
         end
 
         private
 
+        def register
+          Lutaml::Model::Config.default_register
+        end
+
         def attributes_kwargs(plan, value)
           kwargs = {}
           plan[:attr_rows].each do |rule, attr|
             v = value.attribute(rule.name.to_s)
-            kwargs[attr.name.to_sym] = v unless v.nil?
+            next if v.nil?
+
+            v = v.split(rule.delimiter) if rule.delimiter
+            if rule.as_list && rule.as_list[:import]
+              v = rule.as_list[:import].call(v)
+            end
+            kwargs[attr.name.to_sym] = v
           end
           kwargs
         end
 
-        def children_kwargs(_model_class, plan, value)
-          register = Lutaml::Model::Config.default_register
-          grouped = group_children_by_name(value)
-
+        # Returns [kwargs, hydrated_child_instances, delegate_values]
+        # — child instances come back so the caller can decorate
+        # parent/root links once the parent exists; delegate values
+        # wait for the instance (their target object must exist).
+        def children_kwargs(_model_class, plan, value, buckets = nil)
+          grouped = group_children(value)
+          buckets = nil unless buckets && plan[:needs_nodes]
           kwargs = {}
-          plan[:rows].each do |rule, attr, kind|
-            values = grouped[kind == :collection ? :__collection : rule.name.to_s]
-            next if values.nil? || values.empty?
-
-            kwargs[attr.name.to_sym] =
-              case kind
-              when :scalar
-                values.first.string_value
-              when :collection
-                # One collection-row value per element; its items are
-                # the individual scalar matches.
-                values.flat_map do |cv|
-                  Array.new(cv.count) { |i| cv.at(i).string_value }
+          children = []
+          delegates = []
+          spellings = Hash.new { |h, k| h[k] = [] }
+          plan[:rows].each do |rule, attr, kind, spelling, delegate|
+            case kind
+            when :scalar
+              # Raw passthrough: the model constructor is the single
+              # cast authority — pre-casting here doubled every cast.
+              # Class transforms still apply before assignment.
+              v = grouped.dig(rule.name.to_s, 0)&.string_value
+              unless v.nil?
+                v = rule.transform_value(attr, v, :from, :xml) if rule.transform.is_a?(Class)
+                assign(kwargs, delegates, delegate, rule, attr, v)
+              end
+            when :raw, :custom_method, :polymorphic, :content_deferred
+              # interpreted post-instance (interpret_deferred)
+            when :content
+              assign(kwargs, delegates, delegate, rule, attr,
+                     content_runs(value))
+            when :ordered_deferred
+              # With a source node the child hydrates natively: one
+              # walk against its own node + element_order from the
+              # node's children. Without one (direct PlanHydrator
+              # use), the subtree fragment-parses interpretively.
+              if buckets
+                child_type = attr.type(register)
+                child_plan = PlanCompiler.compile(child_type, register)
+                items = buckets.fetch(rule.name.to_s, []).map do |n|
+                  call(child_type, child_plan,
+                       child_plan[:descriptor].walk(n), node: n)
                 end
-              when :nested
-                child_plan = PlanCompiler.compile(attr.type(register),
-                                                  register)
-                items = values.map do |v|
-                  call(attr.type(register), child_plan, v)
+                unless items.empty?
+                  children.concat(items)
+                  assign(kwargs, delegates, delegate, rule, attr,
+                         attr.collection? ? items : items.first)
                 end
-                attr.collection? ? items : items.first
               end
+            when :collection_cb
+              values = grouped[rule.name.to_s].to_a.map(&:string_value)
+              if rule.transform.is_a?(Class)
+                values = values.map { |v| rule.transform_value(attr, v, :from, :xml) }
+              end
+              unless values.empty?
+                assign(kwargs, delegates, delegate, rule, attr, values)
+              end
+            when :collection_native
+              values = native_collection(value, rule.name.to_s)
+              unless values.nil?
+                assign(kwargs, delegates, delegate, rule, attr, values)
+              end
+            when :spelling
+              spellings[[rule, attr]] << grouped[spelling.to_s].to_a
+            when :nested
+              child_type = attr.type(register)
+              child_plan = PlanCompiler.compile(child_type, register)
+              cursor = if child_plan[:needs_nodes] && buckets
+                         buckets.fetch(rule.name.to_s, [])
+                       end
+              items = grouped.fetch(rule.name.to_s, []).each_with_index
+                .map do |v, i|
+                  call(child_type, child_plan, v,
+                       node: cursor && cursor[i])
+                end
+              next if items.empty?
+
+              children.concat(items)
+              assign(kwargs, delegates, delegate, rule, attr,
+                     attr.collection? ? items : items.first)
+            end
           end
-          kwargs
+          unless spellings.empty?
+            spellings.each do |(rule, attr), groups|
+              # Interpretive order for shared-attribute groups is
+              # spelling-group order (first spelling's matches, then
+              # the next's), not interleaved document order.
+              values = groups.compact.flatten.map(&:string_value)
+              next if values.empty?
+
+              delegate = delegate_of(plan, rule)
+              assign(kwargs, delegates, delegate, rule, attr,
+                     attr.collection? ? values : values.first)
+            end
+          end
+          [kwargs, children, delegates]
         end
 
-        # Scalar and nested values echo their producing row's name;
-        # collection values echo neither name nor type_tag, so with the
-        # compiler's single-collection-row guard they are attributed by
-        # kind.
-        def group_children_by_name(value)
+        # Deferred islands: raw subtrees become wrapper elements via a
+        # fragment parse, then the interpretive machinery runs on just
+        # that island — custom method invocation with an
+        # element-shaped argument, or the polymorphic/union cast.
+        # With the source node available the island wraps the ORIGINAL
+        # node (no fragment parse — the reparse dominated deferred
+        # hydration). Ordered children only land here without a node.
+        def interpret_deferred(model_class, plan, value, instance, node = nil,
+                               buckets = nil)
+          plan[:rows].each do |rule, attr, kind, _spelling, _delegate|
+            case kind
+            when :content_deferred
+              runs = content_runs(value)
+              next if runs.empty?
+
+              # Non-collection content attrs hold the joined text
+              # (the interpretive path assigns element text, the runs
+              # concatenated).
+              instance.public_send(:"#{attr.name}=", runs.join)
+            when :raw
+              raws = raw_strings(value, rule)
+              next if raws.empty?
+
+              instance.public_send(:"#{attr.name}=",
+                                   attr.collection? ? raws : raws.first)
+            when :custom_method
+              elements = deferred_elements(value, rule, buckets)
+              next if elements.empty?
+
+              args = attr.collection? ? elements : elements.first
+              rule.deserialize(instance, args,
+                               model_class.attributes(register),
+                               model_class)
+            when :ordered_deferred
+              next if node # hydrated natively in children_kwargs
+
+              results = deferred_elements(value, rule, buckets).map do |element|
+                attr.cast(element, :xml, register,
+                          lutaml_parent: instance,
+                          lutaml_root: instance.lutaml_root || instance)
+              end
+              next if results.empty?
+
+              instance.public_send(:"#{attr.name}=",
+                                   attr.collection? ? results : results.first)
+            when :polymorphic
+              results = deferred_elements(value, rule, buckets).map do |element|
+                attr.cast(element, :xml, register,
+                          polymorphic: rule.polymorphic,
+                          lutaml_parent: instance,
+                          lutaml_root: instance.lutaml_root || instance)
+              end
+              next if results.empty?
+
+              instance.public_send(:"#{attr.name}=",
+                                   attr.collection? ? results : results.first)
+            end
+          end
+        end
+
+        # Wrapper elements for deferred rows: the ORIGINAL source
+        # nodes bridged through moxml's wrapper cache (wrapper
+        # construction only, no parse), falling back to a fragment
+        # parse of the captured subtree when no node is available.
+        # Both lists are document-ordered for the row's name.
+        def deferred_elements(value, rule, buckets)
+          nodes = buckets && buckets[rule.name.to_s]
+          return nodes.map { |n| bridge_element(n) } if nodes
+
+          raw_strings(value, rule).map { |raw| fragment_element(raw) }
+        end
+
+        def bridge_element(node)
+          Lutaml::Xml::LeptrisElement.new(
+            Moxml::Node.wrap(node, bridge_context),
+          )
+        end
+
+        def bridge_context
+          @bridge_context ||= Moxml::Context.new(:leptris)
+        end
+
+        def route_delegates(delegates, instance)
+          delegates.each do |rule, delegate_attr, attr, v|
+            target = instance.public_send(rule.delegate)
+            unless target
+              # the interpretive path instantiates absent delegate
+              # targets; mirror it
+              target = delegate_attr.type(register).new
+              instance.public_send(:"#{rule.delegate}=", target)
+            end
+            target.public_send(:"#{attr.name}=", v)
+          end
+        end
+
+        def delegate_of(plan, rule)
+          entry = plan[:rows].find { |r, _, _k, _| r.equal?(rule) }
+          entry && entry[4]
+        end
+
+        # Delegate rules hold their values for post-instance routing
+        # (the target object must exist first); plain rules land in
+        # kwargs directly.
+        def assign(kwargs, delegates, delegate, rule, attr, value)
+          if delegate
+            delegates << [rule, delegate, attr, value]
+          else
+            kwargs[attr.name.to_sym] = value
+          end
+        end
+
+        def content_runs(value)
+          out = []
+          value.count.times do |i|
+            c = value.at(i)
+            next unless c.name.nil? && c.kind == :collection
+
+            out.concat(Array.new(c.count) { |j| c.at(j).string_value })
+          end
+          out
+        end
+
+        # Native collection rows echo their producing row's name
+        # (leptris 1.9.178).
+        def native_collection(value, name)
+          value.count.times do |i|
+            c = value.at(i)
+            next unless c.kind == :collection && c.name == name
+
+            return Array.new(c.count) { |j| c.at(j).string_value }
+          end
+          nil
+        end
+
+        def raw_strings(value, rule)
+          out = []
+          value.count.times do |idx|
+            child = value.at(idx)
+            if child.name == rule.name.to_s && child.kind == :raw
+              out << child.string_value
+            end
+          end
+          out
+        end
+
+        # Fragment deferral: parse the captured subtree back into a
+        # wrapper element. Ancestor namespace context is absent (the
+        # compiler only defers on namespace-free model chains).
+        def fragment_element(raw)
+          Lutaml::Xml::Adapter::LeptrisAdapter.parse(raw).root
+        end
+
+        def group_children(value)
           grouped = {}
           value.count.times do |i|
             child = value.at(i)
-            key = child.name || (child.kind == :collection ? :__collection : nil)
-            next if key.nil?
+            next if child.name.nil? # content runs, read separately
 
-            (grouped[key] ||= []) << child
+            (grouped[child.name] ||= []) << child
           end
           grouped
         end
+
+        # Element children bucketed by local name, document order
+        # preserved — the node-side mirror of group_children for
+        # ordered-child hydration. Only built when the plan's subtree
+        # needs source nodes; namespace-qualified models never get
+        # here (the compiler keeps them interpretive).
+        def element_buckets(node)
+          buckets = {}
+          node.children.each do |child|
+            next unless child.is_a?(::Leptris::XML::Element)
+
+            (buckets[child.name] ||= []) << child
+          end
+          buckets
+        end
       end
     end
   end

data/lib/lutaml/xml/plan_order.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Xml
+    # Reconstructs element_order for ordered/mixed models from the
+    # leptris node surface in one native pass, mirroring the
+    # interpretive AdapterElement#order contract: text runs, CDATA,
+    # comments, PIs, and element entries (local name + namespace
+    # uri/prefix) in document order, frozen like the interpretive
+    # product.
+    module PlanOrder
+      TEXT_MARKER = "text"
+      CDATA_MARKER = "#cdata-section"
+      COMMENT_MARKER = "comment"
+
+      class << self
+        def build(node)
+          node.children.filter_map { |child| entry_for(child) }
+            .each(&:freeze).freeze
+        end
+
+        private
+
+        def entry_for(child)
+          case child
+          when ::Leptris::XML::CDATA
+            Element.new("Text", CDATA_MARKER,
+                        text_content: child.content, node_type: :cdata)
+          when ::Leptris::XML::Text
+            Element.new("Text", TEXT_MARKER,
+                        text_content: child.text, node_type: :text)
+          when ::Leptris::XML::Comment
+            Element.new("Comment", COMMENT_MARKER,
+                        text_content: child.content, node_type: :comment)
+          when ::Leptris::XML::ProcessingInstruction
+            Element.new("ProcessingInstruction", child.name,
+                        text_content: child.content.to_s.sub(/\A\s+/, ""),
+                        node_type: :processing_instruction)
+          when ::Leptris::XML::Element
+            ns = child.namespace
+            Element.new("Element", child.name,
+                        node_type: :element,
+                        namespace_uri: ns&.values&.first,
+                        namespace_prefix: ns&.keys&.first)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/xml/plan_serializer.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Xml
+    # Serialize-side mirror of the plan fast path: builds the output
+    # tree directly through leptris's fused create_child chain — no
+    # XmlElement tree, no DeclarationPlanner pass, no builder context
+    # stack, no moxml wrapper minting. Serialized shapes must be the
+    # plain ones (attributes, scalars, collections, nested models,
+    # raw fragments, content runs); custom-method, polymorphic,
+    # union, and multi-spelling rows keep the interpretive serializer
+    # (their output flows through hash-shaped custom APIs).
+    #
+    # Ordered/mixed models serialize from element_order when the
+    # instance carries one (parsed models): text runs, comments, and
+    # element entries in document order, mirroring the interpretive
+    # order applier — including its content-attr-first text reads
+    # (mutations to the model show up) and CDATA flattening. Models
+    # without element_order fall back interpretively (return nil).
+    module PlanSerializer
+      SERIALIZABLE_KINDS = %i[scalar collection_native collection_cb
+                              nested ordered_deferred raw content
+                              content_deferred].freeze
+      CONTENT_KINDS = %i[content content_deferred].freeze
+
+      class << self
+        # plan: the compiler's entry for instance's class
+        def call(instance, plan)
+          return nil if plan[:ordered] && instance.element_order.nil?
+
+          doc = ::Leptris::XML::Document.create
+          root = doc.create_element(plan[:tree][:name])
+          doc.root = root
+          if plan[:ordered]
+            build_ordered(root, instance, plan, doc)
+          else
+            build(root, instance, plan, doc)
+          end
+          doc.to_xml(indent: 2, no_decl: true)
+        end
+
+        # Whether the compiled plan is serialize-shaped. Ordered/mixed
+        # models serialize through build_ordered from element_order;
+        # plain models through plan rows.
+        def serializable?(plan)
+          plan[:rows].all? do |_rule, _attr, kind, _sp, _del|
+            SERIALIZABLE_KINDS.include?(kind)
+          end
+        end
+
+        private
+
+        def register
+          Lutaml::Model::Config.default_register
+        end
+
+        def build(element, instance, plan, doc)
+          write_attributes(element, instance, plan)
+          plan[:rows].each do |rule, attr, kind, spelling, delegate|
+            value = value_of(instance, attr, delegate)
+            next unless rule.render?(value, instance)
+
+            case kind
+            when :scalar
+              add_leaf(element, row_name(rule, spelling),
+                       attr.serialize(value, :xml, register), doc)
+            when :collection_native, :collection_cb
+              Array(value).each do |item|
+                add_leaf(element, rule.name.to_s,
+                         attr.serialize(item, :xml, register), doc)
+              end
+            when :nested, :ordered_deferred
+              Array(value).each do |item|
+                child_plan = PlanCompiler.compile(item.class, register)
+                child = element.create_child(child_plan[:tree][:name])
+                if child_plan[:ordered]
+                  return nil unless build_ordered(child, item, child_plan, doc)
+
+                else
+                  build(child, item, child_plan, doc)
+                end
+              end
+            when :raw
+              Array(value).each { |raw| element.add_child(raw.to_s) }
+            when :content, :content_deferred
+              Array(value).each { |run| element.add_child(doc.create_text_node(run.to_s)) }
+            end
+          end
+        end
+
+        # Element_order-driven emission (the interpretive order
+        # applier's contract): text runs and comments verbatim, each
+        # element entry consuming the next item of its collection
+        # (document order). Text reads prefer the content attribute
+        # when it lines up with the text-node count, so mutations to
+        # the model are reflected; element_order text is the fallback.
+        # PIs drop (interpretive parity). Returns nil when a nested
+        # ordered child lacks element_order (caller falls back).
+        def build_ordered(element, instance, plan, doc)
+          write_attributes(element, instance, plan)
+          rows_by_name = {}
+          plan[:rows].each do |rule, attr, kind, spelling, delegate|
+            next unless rule.name
+
+            rows_by_name[rule.name.to_s] ||= [rule, attr, kind, spelling,
+                                              delegate]
+          end
+          content_entry = plan[:rows].find do |rule, _attr, kind, _sp, _del|
+            CONTENT_KINDS.include?(kind) && rule.name.nil?
+          end
+          order = instance.element_order
+          element_indices = ::Hash.new(0)
+          content_attr = content_entry && content_entry[1]
+          content_value = content_attr &&
+            value_of(instance, content_attr, content_entry[4])
+          text_node_count = order.count { |o| o.type == "Text" }
+          use_content_index = content_value.is_a?(Array) &&
+            content_value.length == text_node_count
+          content_cdata = content_entry && content_entry[0].cdata
+          text_node_index = 0
+
+          order.each do |object|
+            case object.type
+            when "Text"
+              text = if content_attr && !content_value.nil?
+                       if use_content_index
+                         content_value[text_node_index].to_s
+                       elsif !content_value.is_a?(Array) && text_node_count <= 1
+                         content_value.to_s
+                       else
+                         object.text_content || object.name
+                       end
+                     else
+                       object.text_content || object.name
+                     end
+              text_node_index += 1
+              next if text.nil?
+              # Mixed content keeps whitespace; ordered-only skips it
+              next if content_attr.nil? && text.strip.empty?
+
+              element.add_child(content_cdata ? doc.create_cdata(text) : doc.create_text_node(text))
+            when "Comment"
+              element.add_child(doc.create_comment(object.text_content))
+            when "Element"
+              entry = rows_by_name[object.name]
+              next unless entry
+
+              _, attr, kind, _spelling, delegate = entry
+              value = value_of(instance, attr, delegate)
+              case kind
+              when :collection_native, :collection_cb
+                index = element_indices[object.name]
+                items = Array(value)
+                next unless index < items.length
+
+                element_indices[object.name] += 1
+                add_leaf(element, object.name,
+                         attr.serialize(items[index], :xml, register), doc)
+              when :nested, :ordered_deferred
+                item = if attr.collection?
+                         index = element_indices[object.name]
+                         element_indices[object.name] += 1
+                         Array(value)[index]
+                       else
+                         value
+                       end
+                next unless item
+
+                child_plan = PlanCompiler.compile(item.class, register)
+                child = element.create_child(child_plan[:tree][:name])
+                if child_plan[:ordered]
+                  return nil unless build_ordered(child, item, child_plan, doc)
+                else
+                  build(child, item, child_plan, doc)
+                end
+              when :raw
+                element.add_child(value.to_s) unless value.nil?
+              when :scalar
+                add_leaf(element, object.name,
+                         attr.serialize(value, :xml, register), doc)
+              end
+            end
+          end
+          true
+        end
+
+        # Attributes in document order when the instance recorded it
+        # (parsed models), else plan row order.
+        def write_attributes(element, instance, plan)
+          recorded = instance.attribute_order
+          if recorded && !recorded.empty?
+            by_name = {}
+            plan[:attr_rows].each do |rule, attr, _sp, delegate|
+              by_name[rule.name.to_s] = [rule, attr, delegate]
+            end
+            names = recorded |
+              plan[:attr_rows].map { |rule, _a, _s, _d| rule.name.to_s }
+            names.each do |name|
+              write_attribute(element, instance, name, by_name[name])
+            end
+          else
+            plan[:attr_rows].each do |rule, attr, _sp, delegate|
+              write_attribute(element, instance, rule.name.to_s,
+                              [rule, attr, delegate])
+            end
+          end
+        end
+
+        def write_attribute(element, instance, name, entry)
+          return unless entry
+
+          _rule, attr, delegate = entry
+          value = value_of(instance, attr, delegate)
+          return if value.nil?
+
+          element.set_attribute(name,
+                                attr.serialize(value, :xml, register).to_s)
+        end
+
+        def add_leaf(element, name, value, doc)
+          child = element.create_child(name)
+          child.add_child(doc.create_text_node(value.to_s)) unless value.nil?
+          child
+        end
+
+        def value_of(instance, attr, delegate)
+          if delegate
+            target = instance.public_send(delegate)
+            target&.public_send(attr.name)
+          else
+            instance.public_send(attr.name)
+          end
+        end
+
+        def row_name(rule, spelling)
+          (spelling || rule.name).to_s
+        end
+      end
+    end
+  end
+end