lutaml-model 0.8.18 → 0.8.22

data/lib/lutaml/model/schema/xml_compiler.rb

@@ -9,10 +9,12 @@ module Lutaml
       module XmlCompiler
         extend self
 
-        autoload :SpecBuilder,        "#{__dir__}/xml_compiler/spec_builder"
-        autoload :RegistryGenerator,  "#{__dir__}/xml_compiler/registry_generator"
-        autoload :SupportedDataTypes, "#{__dir__}/xml_compiler/supported_data_types"
-        autoload :ElementOrder,       "#{__dir__}/xml_compiler/element_order"
+        autoload :SpecBuilder, "#{__dir__}/xml_compiler/spec_builder"
+        autoload :RegistryGenerator,
+                 "#{__dir__}/xml_compiler/registry_generator"
+        autoload :SupportedDataTypes,
+                 "#{__dir__}/xml_compiler/supported_data_types"
+        autoload :ElementOrder, "#{__dir__}/xml_compiler/element_order"
 
         ELEMENT_ORDER_IGNORABLE = %w[import include].freeze
 
@@ -60,7 +62,10 @@ module Lutaml
             FileWriter.write(output, dir, registry_generator: RegistryGenerator)
             true
           else
-            ClassLoader.load(output, registry_generator: RegistryGenerator) if options[:load_classes]
+            if options[:load_classes]
+              ClassLoader.load(output,
+                               registry_generator: RegistryGenerator)
+            end
             output.sources
           end
         end

data/lib/lutaml/model/sequence.rb

@@ -27,12 +27,12 @@ module Lutaml
         @model.attribute(name, type, options)
       end
 
-      def sequence(&)
-        instance_eval(&)
+      def sequence(&block)
+        instance_eval(&block)
       end
 
-      def map_element(name, **)
-        @attributes << @model.map_element(name, **)
+      def map_element(name, **options)
+        @attributes << @model.map_element(name, **options)
       end
 
       def import_model_mappings(model, register = nil)

data/lib/lutaml/model/serialize/attribute_definition.rb

@@ -108,24 +108,20 @@ module Lutaml
                 current = instance_variable_get(:"@#{name}") || []
                 new_value = current.is_a?(Array) ? current + [value] : value
                 instance_variable_set(:"@#{name}", new_value)
-                # Track order for mixed_content serialization
-                track_order(name, value, nil) if @__order_tracking__
+                record_mutation(name, value)
                 value
               end
             end
           else
             # For non-collection attributes, getter accepts optional argument
-            # for builder-style syntax: g.description(value) sets the value
+            # for builder-style syntax: g.description(value) sets the value.
+            # Tracking happens inside the setter, so no duplicate call here.
             define_method(name) do |*args|
               if args.empty?
                 instance_variable_get(:"@#{name}")
               else
-                # Builder-style: g.description(value) sets the value
-                value = args.first
-                public_send(:"#{name}=", value)
-                # Track order for mixed_content serialization
-                track_order(name, value, nil) if @__order_tracking__
-                value
+                public_send(:"#{name}=", args.first)
+                args.first
               end
             end
           end
@@ -156,12 +152,16 @@ module Lutaml
                 else
                   instance_variable_set(:"@#{name}", value)
                 end
+                # Track one entry per item so element_order reflects the
+                # number of <name> elements that will be emitted.
+                record_mutation_collection(name, value)
               end
             else
               define_method(:"#{name}=") do |value|
                 value_set_for(name)
                 value = attr.cast_value(value, lutaml_register)
                 instance_variable_set(:"@#{name}", value)
+                record_mutation(name, value)
               end
             end
           end
@@ -188,6 +188,7 @@ module Lutaml
 
           attr = Attribute.new(name, type, options)
           @attributes[name] = attr
+          @merged_attributes_cache = nil
           define_attribute_methods(attr)
 
           attr

data/lib/lutaml/model/serialize/builder.rb

@@ -75,6 +75,61 @@ module Lutaml
           mapping&.ordered? || false
         end
 
+        # Whether this instance was constructed via a builder block and
+        # therefore records mutations into element_order. Parsed models
+        # and instances constructed without a block do not track; their
+        # element_order (if any) comes from the parser and is treated as
+        # the complete source of truth by the serializer.
+        # @return [Boolean]
+        def order_tracking_enabled?
+          @__order_tracking__ ? true : false
+        end
+
+        # Record a singular attribute mutation in element_order.
+        #
+        # No-op unless order tracking is enabled (i.e. the instance was
+        # constructed via a builder block on an ordered/mixed_content
+        # model). This is the single entry point for singular mutations
+        # and is called from generated setters and getter-with-arg paths
+        # so that direct setters (`x.foo = v`) and appender calls
+        # (`x.foo(v)`) behave identically.
+        #
+        # Returns `value` so generated setters preserve Ruby's setter
+        # contract: `obj.foo = v` evaluates to `v`. Callers like
+        # `obj.foo || (obj.foo = [])` depend on this.
+        #
+        # @param attribute_name [Symbol] The attribute being mutated
+        # @param value [Object, nil] The value being set; stored as text
+        #   content for content-mapped attributes, ignored otherwise
+        # @return [Object] the passed value
+        def record_mutation(attribute_name, value = nil)
+          return value unless @__order_tracking__
+
+          track_order(attribute_name, value, nil)
+          value
+        end
+
+        # Record a collection-attribute mutation in element_order.
+        #
+        # Emits one entry per item so that element_order length matches
+        # the number of serialized child elements. No-op when tracking
+        # is disabled, when the value is nil/empty, or when the
+        # collection's frozen sentinel is preserved (no real data).
+        #
+        # Returns `value` so generated setters preserve Ruby's setter
+        # contract (see {record_mutation}).
+        #
+        # @param attribute_name [Symbol] The collection attribute
+        # @param value [Object, nil] The value assigned to the collection
+        # @return [Object] the passed value
+        def record_mutation_collection(attribute_name, value)
+          return value unless @__order_tracking__
+          return value if value.nil? || Lutaml::Model::Utils.uninitialized?(value)
+
+          Array(value).each { |item| track_order(attribute_name, item, nil) }
+          value
+        end
+
         private
 
         # Intercept method calls to track order for mixed_content

data/lib/lutaml/model/serialize/format_conversion.rb

@@ -13,7 +13,7 @@ module Lutaml
         # @param format [Symbol] The format (:xml, :json, etc.)
         # @param args [Array] Additional arguments (e.g., mapping class for XML)
         # @param block [Proc] The DSL block to evaluate
-        def process_mapping(format, *_args, &)
+        def process_mapping(format, *_args, &block)
           klass = ::Lutaml::Model::Config.mappings_class_for(format)
           existing = mappings[format]
           mappings[format] = if existing.nil? || !existing.is_a?(klass)
@@ -21,7 +21,7 @@ module Lutaml
                              else
                                existing
                              end
-          mappings[format].instance_eval(&)
+          mappings[format].instance_eval(&block)
 
           if mappings[format].is_a?(Lutaml::Xml::Mapping)
             mappings[format].finalize(self)

data/lib/lutaml/model/serialize/initialization.rb

@@ -115,13 +115,18 @@ module Lutaml
         # Get all attributes for this model
         #
         # Merges class-level attributes with register-specific attributes.
+        # Memoized per register: this is on the per-element deserialization
+        # hot path, and the merged hash is stable until an attribute, import
+        # or register record mutates (those clear @merged_attributes_cache).
         #
         # @param register [Symbol, nil] The register context
         # @return [Hash] The attributes hash
         def attributes(register = nil)
           ensure_imports!(register) if finalized?
           if @register_records&.any?
-            @attributes.merge(@register_records[extract_register_id(register)][:attributes])
+            register_id = extract_register_id(register)
+            (@merged_attributes_cache ||= {})[register_id] ||=
+              @attributes.merge(@register_records[register_id][:attributes])
           else
             @attributes
           end
@@ -183,6 +188,9 @@ module Lutaml
             GlobalContext.resolver.clear_cache(register_id)
           end
 
+          # Clear memoized attribute merge (see .attributes)
+          @merged_attributes_cache = nil
+
           # Clear per-Attribute type caches (stale entries from GC'd TypeContext objects)
           class_attributes.each_value(&:clear_type_cache)
           @register_records&.each_value do |record|
@@ -370,7 +378,6 @@ module Lutaml
               instance_variable_get(:"@#{name}")
             else
               public_send(:"#{name}=", args.first)
-              track_order(name, args.first, nil) if @__order_tracking__
               args.first
             end
           end
@@ -380,6 +387,7 @@ module Lutaml
             reg_attr = resolve_register_attr(name)
             value = reg_attr.cast_value(value, lutaml_register)
             instance_variable_set(:"@#{name}", value)
+            record_mutation(name, value)
           end
         end
 
@@ -395,7 +403,7 @@ module Lutaml
               current = [] if current.equal?(LAZY_EMPTY_COLLECTION)
               new_value = current.is_a?(Array) ? current + [value] : value
               instance_variable_set(:"@#{name}", new_value)
-              track_order(name, value, nil) if @__order_tracking__
+              record_mutation(name, value)
               value
             end
           end
@@ -411,6 +419,7 @@ module Lutaml
             else
               instance_variable_set(:"@#{name}", value)
             end
+            record_mutation_collection(name, value)
           end
         end
 

data/lib/lutaml/model/serialize/model_import.rb

@@ -121,6 +121,7 @@ module Lutaml
           @register_records[register_id][:choice_attributes].concat(
             deep_duplicate_choice_attributes(model, register_id),
           )
+          @merged_attributes_cache = nil
         end
         private :register_only_import_model_attributes
 

data/lib/lutaml/model/serialize.rb

@@ -175,18 +175,19 @@ module Lutaml
         @using_default[attribute_name]
       end
 
-      # rubocop:disable Style/ArgumentsForwarding -- anonymous * requires Ruby 3.2+, but required_ruby_version >= 3.0
-      def method_missing(method_name, *args)
+      def method_missing(method_name, *args, &block)
         if method_name.to_s.end_with?("=") && attribute_exist?(method_name)
           define_singleton_method(method_name) do |value|
             instance_variable_set(:"@#{method_name.to_s.chomp('=')}", value)
           end
           send(method_name, *args)
+        elsif ::Lutaml::Model::Attribute.default_evaluation? &&
+            self.class.respond_to?(method_name)
+          self.class.public_send(method_name, *args, &block)
         else
           super
         end
       end
-      # rubocop:enable Style/ArgumentsForwarding
 
       def respond_to_missing?(method_name, include_private = false)
         (method_name.to_s.end_with?("=") && attribute_exist?(method_name)) ||

data/lib/lutaml/model/type/uninitialized_class_guard.rb

@@ -17,7 +17,7 @@ module Lutaml
         #
         # The prepend ensures this method runs BEFORE the subclass's
         # cast implementation, even if the subclass doesn't call super.
-        def cast(value, *args, **kwargs, &)
+        def cast(value, *args, **kwargs, &block)
           # Return UninitializedClass unchanged - don't transform it
           return value if Utils.uninitialized?(value)
 

data/lib/lutaml/model/type.rb

@@ -55,7 +55,16 @@ module Lutaml
         hex_binary: "Lutaml::Model::Type::HexBinary",
       }.freeze
 
+      BUILTIN_CLASSES =
+        TYPE_CODES.each_value.map { |type_class_name| const_get(type_class_name) }.freeze
+
       class << self
+        # @param type [Class] a candidate type class
+        # @return [Boolean] whether the class is one of the built-ins
+        def builtin?(type)
+          BUILTIN_CLASSES.include?(type)
+        end
+
         # Register all built-in types into any TypeRegistry.
         #
         # This method is used by the new type resolution architecture.

data/lib/lutaml/model/type_registry.rb

@@ -127,8 +127,8 @@ module Lutaml
       #
       # @example
       #   registry.each { |name, klass| puts "#{name}: #{klass}" }
-      def each(&)
-        @types.each(&)
+      def each(&block)
+        @types.each(&block)
       end
 
       # Create a copy of this registry

data/lib/lutaml/model/uninitialized_class.rb

@@ -48,7 +48,7 @@ module Lutaml
         "".encoding
       end
 
-      def method_missing(method, *_args, &)
+      def method_missing(method, *_args)
         return false if method.end_with?("?")
 
         nil

data/lib/lutaml/model/union.rb

@@ -131,7 +131,8 @@ module Lutaml
 
           def validate_members!(members)
             unless members.is_a?(::Array) && !members.empty?
-              raise ArgumentError, "union type must be a non-empty array of types"
+              raise ArgumentError,
+                    "union type must be a non-empty array of types"
             end
 
             resolved = members.map { |member| resolve_member!(member) }
@@ -166,7 +167,9 @@ module Lutaml
             return :no_match if keys.nil? || keys.empty?
 
             field_names = member_field_names(member, format, register)
-            return :no_match unless keys.all? { |key| field_names.include?(key) }
+            return :no_match unless keys.all? do |key|
+              field_names.include?(key)
+            end
 
             # Plain-Ruby assignment (format nil) builds straight from the
             # attribute hash, mirroring how non-union model attributes accept

data/lib/lutaml/model/utils.rb

@@ -201,10 +201,10 @@ module Lutaml
           end
         end
 
-        def add_singleton_method_if_not_defined(instance, method_name, &)
+        def add_singleton_method_if_not_defined(instance, method_name, &block)
           return if instance.singleton_class.method_defined?(method_name, false)
 
-          instance.define_singleton_method(method_name, &)
+          instance.define_singleton_method(method_name, &block)
         end
 
         # Determines the appropriate register for a child model during deserialization.

data/lib/lutaml/model/value_policy.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Model
+    # Decides how an attribute shapes incoming raw values: whether an
+    # Array is split element-wise (collection semantics) or handed whole
+    # to the declared type (value-owning semantics).
+    #
+    # A user-defined Type::Value subclass may legitimately wrap lists or
+    # maps in a singular slot (#752); built-in scalar types keep the
+    # "collection: true is missing" guidance error.
+    class ValuePolicy
+      def initialize(collection:, union:, reference:)
+        @collection = collection
+        @union = union
+        @reference = reference
+      end
+
+      # @param type [Class, Symbol] the resolved (or unresolved) type
+      # @return [Boolean] whether raw values must reach the type whole
+      def whole_value?(type)
+        !@collection && !@union && !@reference &&
+          type.is_a?(Class) && type < Type::Value && !Type.builtin?(type)
+      end
+    end
+  end
+end

data/lib/lutaml/model/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Model
-    VERSION = "0.8.18"
+    VERSION = "0.8.22"
   end
 end

data/lib/lutaml/model.rb

@@ -2,14 +2,14 @@
 
 module Lutaml
   # Autoload top-level modules (outside Model namespace)
-  autoload :KeyValue, "#{__dir__}/key_value"
-  autoload :Json, "#{__dir__}/json"
-  autoload :Yaml, "#{__dir__}/yaml"
-  autoload :Toml, "#{__dir__}/toml"
-  autoload :HashFormat, "#{__dir__}/hash_format"
-  autoload :Jsonl, "#{__dir__}/jsonl"
-  autoload :Yamls, "#{__dir__}/yamls"
-  autoload :Xml, "#{__dir__}/xml"
+  autoload :KeyValue, "#{__dir__}/key_value/format"
+  autoload :Json, "#{__dir__}/json/format"
+  autoload :Yaml, "#{__dir__}/yaml/format"
+  autoload :Toml, "#{__dir__}/toml/format"
+  autoload :HashFormat, "#{__dir__}/hash_format/format"
+  autoload :Jsonl, "#{__dir__}/jsonl/format"
+  autoload :Yamls, "#{__dir__}/yamls/format"
+  autoload :Xml, "#{__dir__}/xml/format"
   autoload :JsonLd, "#{__dir__}/jsonld"
   autoload :YamlLd, "#{__dir__}/yamlld"
   autoload :Turtle, "#{__dir__}/turtle"
@@ -72,6 +72,7 @@ module Lutaml
     autoload :CollectionHandler, "#{__dir__}/model/collection_handler"
     autoload :AttributeValidator, "#{__dir__}/model/attribute_validator"
     autoload :Attribute, "#{__dir__}/model/attribute"
+    autoload :ValuePolicy, "#{__dir__}/model/value_policy"
     autoload :JsonAdapter, "#{__dir__}/model/json_adapter"
     autoload :SchemaLocation, "#{__dir__}/model/schema_location"
     autoload :Validation, "#{__dir__}/model/validation"
@@ -258,14 +259,14 @@ end
 
 # Format files register DSL methods - use require to ensure proper loading order
 # These files set up FormatRegistry and detect/configure adapters
-require "#{__dir__}/key_value"
-require "#{__dir__}/json"
-require "#{__dir__}/yaml"
-require "#{__dir__}/toml"
-require "#{__dir__}/hash_format"
-require "#{__dir__}/jsonl"
-require "#{__dir__}/yamls"
-require "#{__dir__}/xml"
+require "#{__dir__}/key_value/format"
+require "#{__dir__}/json/format"
+require "#{__dir__}/yaml/format"
+require "#{__dir__}/toml/format"
+require "#{__dir__}/hash_format/format"
+require "#{__dir__}/jsonl/format"
+require "#{__dir__}/yamls/format"
+require "#{__dir__}/xml/format"
 
 # Optional formats: require "lutaml/jsonld" or "lutaml/turtle" to enable.
 # These are not eagerly loaded because they depend on optional gems

data/lib/lutaml/rdf/mapping.rb

@@ -19,8 +19,8 @@ module Lutaml
         @namespace_set = Lutaml::Rdf::NamespaceSet.new(*namespace_classes)
       end
 
-      def subject(&)
-        @rdf_subject = Proc.new(&) if block_given?
+      def subject(&block)
+        @rdf_subject = Proc.new(&block) if block
       end
 
       def type(value)

data/lib/lutaml/rdf/namespace_set.rb

@@ -38,8 +38,8 @@ module Lutaml
         nil
       end
 
-      def each(&)
-        @by_prefix.each_value(&)
+      def each(&block)
+        @by_prefix.each_value(&block)
       end
 
       def size

data/lib/lutaml/rdf/transform.rb

@@ -17,9 +17,9 @@ module Lutaml
         mapping.rdf_type.map { |t| resolve_single_type_uri(mapping, t) }
       end
 
-      def each_member(instance, member_rule, &)
+      def each_member(instance, member_rule, &block)
         collection = Array(instance.public_send(member_rule.attr_name))
-        collection.each(&)
+        collection.each(&block)
       end
 
       def member_mapping_for(member, format)

data/lib/lutaml/toml/format.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+# Internal TOML format implementation. Loaded from lib/lutaml/toml.rb
+# (the public entrypoint) and from lib/lutaml/model.rb (so the model
+# entrypoint triggers the registration side effects).
+# No require_relative "model" here — keeps the require graph acyclic.
+
+require "lutaml/model/runtime_compatibility"
+require_relative "../key_value/format"
+require_relative "adapter"
+
+module Lutaml
+  module Toml
+    class Error < StandardError; end
+
+    # Convenience aliases for common classes at the module level
+    # Allows Lutaml::Toml::Mapping to resolve to Lutaml::Toml::Adapter::Mapping
+    def self.const_missing(name)
+      if Adapter.const_defined?(name, false)
+        Adapter.const_get(name, false)
+      else
+        super
+      end
+    end
+  end
+end
+
+Lutaml::Model::FormatRegistry.register(
+  :toml,
+  mapping_class: Lutaml::Toml::Adapter::Mapping,
+  adapter_class: nil,
+  transformer: Lutaml::Toml::Adapter::Transform,
+  key_value: true,
+  adapter_options: if Lutaml::Model.opal?
+                     nil
+                   else
+                     {
+                       available: %i[tomlib toml_rb],
+                       default: Lutaml::Model::RuntimeCompatibility.windows? ? :toml_rb : :tomlib,
+                     }
+                   end,
+)
+
+require_relative "type/serializers"
+Lutaml::Toml::Type::Serializers.register_all!
+
+# Auto-detection is now handled lazily by AdapterResolver on first use.
+# No eager adapter selection at require time.

data/lib/lutaml/toml.rb

@@ -1,48 +1,7 @@
 # frozen_string_literal: true
 
-# TOML format module
-# Provides Lutaml::Toml namespace for TOML serialization
-
-require "lutaml/model/runtime_compatibility"
-require_relative "key_value"
-require_relative "toml/adapter"
-
-module Lutaml
-  module Toml
-    class Error < StandardError; end
-
-    # Convenience aliases for common classes at the module level
-    # Allows Lutaml::Toml::Mapping to resolve to Lutaml::Toml::Adapter::Mapping
-    def self.const_missing(name)
-      if Adapter.const_defined?(name, false)
-        Adapter.const_get(name, false)
-      else
-        super
-      end
-    end
-  end
-end
-
-# Register TOML format with the format registry
-Lutaml::Model::FormatRegistry.register(
-  :toml,
-  mapping_class: Lutaml::Toml::Adapter::Mapping,
-  adapter_class: nil,
-  transformer: Lutaml::Toml::Adapter::Transform,
-  key_value: true,
-  adapter_options: if Lutaml::Model.opal?
-                     nil
-                   else
-                     {
-                       available: %i[tomlib toml_rb],
-                       default: Lutaml::Model::RuntimeCompatibility.windows? ? :toml_rb : :tomlib,
-                     }
-                   end,
-)
-
-# Register TOML type serializers
-require_relative "toml/type/serializers"
-Lutaml::Toml::Type::Serializers.register_all!
-
-# Auto-detection is now handled lazily by AdapterResolver on first use.
-# No eager adapter selection at require time.
+# Public TOML format entrypoint. Loads the base model and the internal
+# implementation. The internal file does not require the model back,
+# which keeps the require graph acyclic.
+require_relative "model"
+require_relative "toml/format"

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

@@ -215,8 +215,8 @@ module Lutaml
 
         private
 
-        def attribute_values(element, &)
-          element.attributes.each_value(&)
+        def attribute_values(element, &block)
+          element.attributes.each_value(&block)
         end
 
         def schema_location_attribute?(attr)

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

@@ -180,9 +180,9 @@ module Lutaml
           result
         end
 
-        def method_missing(method_name, *args, &)
+        def method_missing(method_name, *args, &block)
           attrs = args.first.is_a?(Hash) ? args.first : {}
-          create_and_add_element(method_name.to_s, attributes: attrs, &)
+          create_and_add_element(method_name.to_s, attributes: attrs, &block)
         end
 
         def respond_to_missing?(_method_name, _include_private = false)