lutaml-model 0.8.56 → 0.8.106

data/lib/lutaml/xml/plan_hydrator.rb

@@ -1,367 +0,0 @@
-# frozen_string_literal: true
-
-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). 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)
-        # 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
-          # TODO.max-perf/33: the bulk constructor — allocate +
-          # compiled writers, from_hash semantics — measured ~30x on
-          # hydration-heavy corpora versus the generic constructor.
-          instance = model_class.instantiate(attr_kwargs.merge(child_kwargs),
-                                             register)
-          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)
-            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
-
-        # 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, tagged = group_children(value, plan[:row_tags])
-          buckets = nil unless buckets && plan[:needs_nodes]
-          kwargs = {}
-          children = []
-          delegates = []
-          spellings = Hash.new { |h, k| h[k] = [] }
-          row_tags = plan[:row_tags]
-          plan[:rows].each_with_index do |(rule, attr, kind, spelling, delegate), idx|
-            tag = row_tags&.[](idx)
-            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.
-              if tag && (vals = tagged[tag]) && vals.size > 1
-                # Interpretive parity: several captures into a
-                # non-collection attribute arrive as the full array.
-                v = vals.map(&:string_value)
-              else
-                first = if tag
-                          tagged[tag]&.first
-                        else
-                          grouped.dig(rule.name.to_s, 0)
-                        end
-                v = first&.string_value
-              end
-              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
-                unless items.empty?
-                  children.concat(items)
-                  assign(kwargs, delegates, delegate, rule, attr,
-                         attr.collection? ? items : items.first)
-                end
-              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 = if tag
-                         tagged[tag].to_a.map(&:string_value)
-                       else
-                         native_collection(value, rule.name.to_s)
-                       end
-              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
-          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
-
-        # 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, row_tags = nil)
-          grouped = {}
-          tagged = {}
-          want_tags = !row_tags.nil?
-          value.count.times do |i|
-            child = value.at(i)
-            next if child.name.nil? # content runs, read separately
-
-            (grouped[child.name] ||= []) << child
-            if want_tags && child.type_tag != 0
-              (tagged[child.type_tag] ||= []) << child
-            end
-          end
-          [grouped, tagged]
-        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
-end

data/lib/lutaml/xml/plan_order.rb

@@ -1,53 +0,0 @@
-# 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
-            # Leptris::XML::Namespace is a single object (href/prefix),
-            # not the Nokogiri-style prefix hash — hash accessors blow
-            # up ordered+namespaced plan parses.
-            Element.new("Element", child.name,
-                        node_type: :element,
-                        namespace_uri: ns&.href,
-                        namespace_prefix: ns&.prefix)
-          end
-        end
-      end
-    end
-  end
-end

data/lib/lutaml/xml/plan_serializer.rb

@@ -1,252 +0,0 @@
-# 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
-              # Multi-capture parity: an attribute that collected
-              # several occurrences serializes one element per item,
-              # as the interpretive writer does.
-              Array(value).each do |item|
-                add_leaf(element, row_name(rule, spelling),
-                         attr.serialize(item, :xml, register), doc,
-                         attrs: rule.when_attribute)
-              end
-            when :collection_native, :collection_cb
-              Array(value).each do |item|
-                add_leaf(element, rule.name.to_s,
-                         attr.serialize(item, :xml, register), doc,
-                         attrs: rule.when_attribute)
-              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
-
-        # Partition rows (#88) re-emit their discriminator: the wire
-        # element carries the when_attribute pairs so the round trip
-        # re-routes to the same attribute on reparse.
-        def add_leaf(element, name, value, doc, attrs: nil)
-          child = element.create_child(name)
-          attrs&.each { |k, v| child[k.to_s] = v.to_s }
-          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