lutaml-model 0.8.36 → 0.8.38

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

@@ -12,6 +12,100 @@ module Lutaml
         #
         # @param attr [Attribute] The attribute to define methods for
         # @param register [Symbol, nil] The register for type resolution
+        # Compile (per class, cached) the method that seeds every attribute
+        # with its "no data arrived" sentinel: collections share the frozen
+        # LAZY_EMPTY_COLLECTION, scalars share the UninitializedClass
+        # singleton. Compiled once instead of walked per instance — the
+        # grammars-compile-don't-interpret rule applied to object state.
+        # Compile (per class and register, on demand) the method that
+        # seeds every attribute with its "no data arrived" sentinel:
+        # collections share the frozen LAZY_EMPTY_COLLECTION, scalars
+        # share the UninitializedClass singleton. Compiled once instead
+        # of walked per instance — grammars compile, they don't
+        # interpret.
+        def compiled_state_defaults_name!(register_id)
+          @state_defaults_names ||= {}
+          name = @state_defaults_names[register_id]
+          return name if name
+
+          method_name = :"__init_state_defaults_#{register_id}"
+          compile_state_defaults!(method_name, register_id)
+          @state_defaults_names[register_id] = method_name
+          method_name
+        end
+
+        def compile_state_defaults!(method_name, register_id = nil)
+          attrs = attributes(register_id)
+
+          if attrs.empty?
+            define_method(method_name) do
+              # no attributes to seed
+            end
+            return
+          end
+
+          lines = attrs.map do |name, attr|
+            if attr.collection?
+              "@#{name} = Lutaml::Model::Serialize::LAZY_EMPTY_COLLECTION"
+            else
+              "@#{name} = Lutaml::Model::UninitializedClass.instance"
+            end
+          end.join("\n")
+
+          # class_eval interpolates per-attribute `@name = <sentinel>` lines:
+          #   def __init_state_defaults_default
+          #     @id = Lutaml::Model::UninitializedClass.instance
+          #     @items = Lutaml::Model::Serialize::LAZY_EMPTY_COLLECTION
+          #   end
+          class_eval(<<~RUBY, __FILE__, __LINE__ + 1) # rubocop:disable Style/DocumentDynamicEvalDefinition
+            def #{method_name}
+            #{lines}
+            end
+          RUBY
+        end
+
+        # Historical getter shape for punctuation-named attributes and
+        # any name the compiled form cannot express.
+        def define_reflective_attribute_methods(name, attr)
+          if attr.collection?
+            define_method(name) do |*args|
+              if args.empty?
+                materialize_lazy_collection(name)
+              else
+                # Builder-style: g.member(item) appends to collection
+                value = args.first
+                current = instance_variable_get(:"@#{name}") || []
+                new_value = current.is_a?(Array) ? current + [value] : value
+                instance_variable_set(:"@#{name}", new_value)
+                record_mutation(name, value)
+                value
+              end
+            end
+          else
+            define_method(name) do |*args|
+              if args.empty?
+                instance_variable_get(:"@#{name}")
+              else
+                public_send(:"#{name}=", args.first)
+                args.first
+              end
+            end
+          end
+        end
+
+        def invalidate_state_defaults!
+          # Opal's method_defined? takes no inherit flag (see the
+          # setter_defined check in define_regular_attribute_methods).
+          (@state_defaults_names ||= {}).each_key do |compiled|
+            defined_now = if Lutaml::Model.opal?
+                            method_defined?(compiled)
+                          else
+                            method_defined?(compiled, false)
+                          end
+            remove_method(compiled) if defined_now
+          end
+        end
+
         def define_attribute_methods(attr, register = nil)
           name = attr.name
           register_id = extract_register_id(register)
@@ -106,35 +200,54 @@ module Lutaml
         #
         # @param name [Symbol] The attribute name
         # @param attr [Attribute] The attribute definition
+        # Plain identifier names compile to `@name` reads; punctuation
+        # names (`mixed?`) keep the reflective path (@name is not valid
+        # Ruby for them).
+        PLAIN_NAME = /\A[a-zA-Z_][a-zA-Z0-9_]*\z/
+
         def define_regular_attribute_methods(name, attr)
-          # For collection attributes, the getter accepts an optional argument
-          # for builder-style syntax: g.member(item) appends to the collection
+          unless name.to_s.match?(PLAIN_NAME)
+            return define_reflective_attribute_methods(name, attr)
+          end
+
+          # Getters compile with a sentinel default argument instead of a
+          # `*args` splat: the splat allocated an (almost always empty)
+          # Array on EVERY read — the largest per-call allocation source
+          # on instance-heavy parses (TODO.max-perf/06). The optional-arg
+          # form allocates nothing, and the read is a direct @ivar.
           if attr.collection?
-            define_method(name) do |*args|
-              if args.empty?
-                materialize_lazy_collection(name)
-              else
-                # Builder-style: g.member(item) appends to collection
-                value = args.first
-                current = instance_variable_get(:"@#{name}") || []
-                new_value = current.is_a?(Array) ? current + [value] : value
-                instance_variable_set(:"@#{name}", new_value)
-                record_mutation(name, value)
-                value
+            # class_eval interpolates, e.g.:
+            #   def items(arg = Lutaml::Model::Serialize::NO_ARG)
+            #     if arg.equal?(Lutaml::Model::Serialize::NO_ARG)
+            #       materialize_lazy_collection(:items)
+            #     else
+            #       ... builder append ...
+            #     end
+            #   end
+            class_eval(<<~RUBY, __FILE__, __LINE__ + 1) # rubocop:disable Style/DocumentDynamicEvalDefinition
+              def #{name}(arg = Lutaml::Model::Serialize::NO_ARG)
+                if arg.equal?(Lutaml::Model::Serialize::NO_ARG)
+                  materialize_lazy_collection(:#{name})
+                else
+                  current = @#{name} || []
+                  new_value = current.is_a?(Array) ? current + [arg] : arg
+                  @#{name} = new_value
+                  record_mutation(:#{name}, arg)
+                  arg
+                end
               end
-            end
+            RUBY
           else
-            # For non-collection attributes, getter accepts optional argument
-            # 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
-                public_send(:"#{name}=", args.first)
-                args.first
+            class_eval(<<~RUBY, __FILE__, __LINE__ + 1) # rubocop:disable Style/DocumentDynamicEvalDefinition
+              def #{name}(arg = Lutaml::Model::Serialize::NO_ARG)
+                if arg.equal?(Lutaml::Model::Serialize::NO_ARG)
+                  @#{name}
+                else
+                  public_send(:"#{name}=", arg)
+                  arg
+                end
               end
-            end
+            RUBY
           end
 
           enum_shorthand_names = instance_variable_get(:@__enum_shorthand_names__) || Set.new
@@ -146,35 +259,50 @@ module Lutaml
                            else
                              method_defined?(:"#{name}=", false)
                            end
-          unless setter_defined && !enum_shorthand_names.include?(name.to_s)
-            if attr.collection?
-              define_method(:"#{name}=") do |value|
-                value_set_for(name)
-                value = attr.cast_value(value, lutaml_register)
-                # Preserve the frozen sentinel when the deserialization pipeline
-                # would overwrite it with nil/UninitializedClass (meaning "no data
-                # found for this collection"). This maintains the zero-allocation
-                # guarantee for unused collections. The sentinel is replaced with
-                # a real Array only when actual data is set.
-                current = instance_variable_get(:"@#{name}")
-                if current.equal?(LAZY_EMPTY_COLLECTION) &&
+          return if setter_defined && !enum_shorthand_names.include?(name.to_s)
+
+          # class_eval'd bodies cannot close over locals; a hidden
+          # define_method accessor holds the Attribute handle.
+          attr_reader_method = :"__attribute_definition_#{name}"
+          unless method_defined?(attr_reader_method, false)
+            define_method(attr_reader_method) { attr }
+          end
+
+          if attr.collection?
+            # class_eval interpolates, e.g.:
+            #   def items=(value)
+            #     value_set_for(:items)
+            #     value = ATTR.cast_value(value, lutaml_register)
+            #     current = @items
+            #     ... sentinel preservation ...
+            #     record_mutation_collection(:items, value)
+            #   end
+            # The compiled body writes @items directly: the define_method
+            # form interpolated "@items" name strings per call — one per
+            # setter invocation on instance-heavy parses (TODO.max-perf/06).
+            class_eval(<<~RUBY, __FILE__, __LINE__ + 1) # rubocop:disable Style/DocumentDynamicEvalDefinition
+              def #{name}=(value)
+                value_set_for(:#{name})
+                value = __attribute_definition_#{name}.cast_value(value, lutaml_register)
+                current = @#{name}
+                if current.equal?(Lutaml::Model::Serialize::LAZY_EMPTY_COLLECTION) &&
                     (value.nil? || Lutaml::Model::Utils.uninitialized?(value))
                   # Sentinel stays — no allocation for truly empty collections
                 else
-                  instance_variable_set(:"@#{name}", value)
+                  @#{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)
+                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)
+            RUBY
+          else
+            class_eval(<<~RUBY, __FILE__, __LINE__ + 1) # rubocop:disable Style/DocumentDynamicEvalDefinition
+              def #{name}=(value)
+                value_set_for(:#{name})
+                value = __attribute_definition_#{name}.cast_value(value, lutaml_register)
+                @#{name} = value
+                record_mutation(:#{name}, value)
               end
-            end
+            RUBY
           end
         end
 
@@ -200,6 +328,7 @@ module Lutaml
           attr = Attribute.new(name, type, options)
           @attributes[name] = attr
           @merged_attributes_cache = nil
+          invalidate_state_defaults!
           define_attribute_methods(attr)
 
           attr

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

@@ -29,6 +29,7 @@ module Lutaml
           import_declaration_plan
           polymorphic
           collection
+          __lutaml_child_memo
           render_empty
           render_nil
           cdata

data/lib/lutaml/model/serialize.rb

@@ -33,6 +33,11 @@ module Lutaml
       # The getter materializes a real Array on first access.
       LAZY_EMPTY_COLLECTION = [].freeze
 
+      # Sentinel distinguishing "getter called with no argument" from
+      # builder-syntax `g.attr(value)` where value may be nil. Compiled
+      # getters default to it instead of a `*args` splat.
+      NO_ARG = Object.new.freeze
+
       INTERNAL_ATTRIBUTES = %i[@using_default @lutaml_register @lutaml_parent @lutaml_root
                                @register_records].freeze
 
@@ -73,6 +78,49 @@ module Lutaml
         end
       end
 
+      # lutaml-model#436: multi-document streams. `from_<f>_stream`
+      # parses each document separately; `discriminator:` receives each
+      # parsed document hash and returns the model class to build with,
+      # enabling polymorphic streams. `to_<f>_stream` joins instances
+      # into one stream document.
+      def self.register_stream_methods(format)
+        ClassMethods.define_method(:"from_#{format}_stream") do |data, options = {}|
+          docs = Lutaml::Model::Serialize.stream_documents(data, format, options)
+          discriminator = options[:discriminator]
+          docs.map do |doc|
+            target = discriminator ? discriminator.call(doc) : self
+            target.send(:"of_#{format}", doc, options)
+          end
+        end
+
+        ClassMethods.define_method(:"to_#{format}_stream") do |instances, options = {}|
+          instances.map do |instance|
+            instance.send(:"to_#{format}", options)
+          end.join("---\n")
+        end
+      end
+
+      def self.stream_documents(data, format, options)
+        require "yaml"
+        if YAML.respond_to?(:load_stream, true)
+          begin
+            docs = YAML.load_stream(data,
+                                    aliases: options.fetch(:aliases, true))
+          rescue ArgumentError
+            # Older Psych builds without the aliases keyword: aliases are
+            # on by default there.
+            docs = YAML.load_stream(data)
+          end
+          docs.is_a?(Array) ? docs.compact : [docs].compact
+        else
+          data.split(/^---\s*$/).filter_map do |chunk|
+            chunk.strip.empty? ? nil : YAML.safe_load(chunk)
+          end
+        end
+      rescue StandardError => e
+        raise Lutaml::Model::InvalidFormatError.new(format, e.message)
+      end
+
       def self.register_to_format_method(format)
         ClassMethods.define_method(:"to_#{format}") do |instance, options = {}|
           to(format, instance, options)
@@ -108,16 +156,12 @@ module Lutaml
         @using_default = nil
         @lutaml_register = register
 
-        # Initialize all attributes to their "empty" state.
-        # Collections use a shared frozen sentinel (zero allocation per instance).
-        # Non-collections use UninitializedClass.instance (singleton, no allocation).
-        # This ensures consistent initial state for the deserialization pipeline:
-        # attributes that don't match any rule keep their UninitializedClass value,
-        # avoiding the need for the setter to be called as a no-op.
-        self.class.attributes(register).each do |name, attr|
-          instance_variable_set(:"@#{name}",
-                                attr.collection? ? LAZY_EMPTY_COLLECTION : Lutaml::Model::UninitializedClass.instance)
-        end
+        # Seed every attribute through the per-(class, register) compiled
+        # method: plain `@x = sentinel` writes, no per-call "@#{name}"
+        # string interpolation, no instance_variable_set. The previous
+        # generic walk interpolated a name string per attribute per
+        # instance — 581k allocations on the ISO-13849 profile.
+        public_send(self.class.compiled_state_defaults_name!(self.class.extract_register_id(register)))
       end
 
       # Complete deserialization initialization after allocation.

data/lib/lutaml/model/services/transformer.rb

@@ -2,8 +2,8 @@ module Lutaml
   module Model
     class Transformer
       class << self
-        def call(value, rule, attribute, format: nil)
-          new(rule, attribute, format).call(value)
+        def call(value, rule, attribute, format: nil, context: nil)
+          new(rule, attribute, format, context).call(value)
         end
 
         private
@@ -15,7 +15,7 @@ module Lutaml
           transform.is_a?(::Hash) ? transform[direction] : transform
         end
 
-        def apply_static(value, sources, direction, format)
+        def apply_static(value, sources, direction, format, context = nil)
           methods = sources.filter_map do |obj|
             get_transform_static(obj, direction)
           end
@@ -34,16 +34,23 @@ module Lutaml
             tc.public_send(apply_direction, v, format)
           end
 
-          methods.reduce(result) { |tv, m| m.call(tv) }
+          methods.reduce(result) do |tv, m|
+            if m.arity == 2
+              m.call(tv, context)
+            else
+              m.call(tv)
+            end
+          end
         end
       end
 
-      attr_reader :rule, :attribute, :format
+      attr_reader :rule, :attribute, :format, :context
 
-      def initialize(rule, attribute, format = nil)
+      def initialize(rule, attribute, format = nil, context = nil)
         @rule = rule
         @attribute = attribute
         @format = format
+        @context = context
       end
 
       def call(value)
@@ -61,7 +68,19 @@ module Lutaml
         end
 
         methods.reduce(result) do |transformed_value, method|
-          method.call(transformed_value)
+          invoke_transform(method, transformed_value)
+        end
+      end
+
+      # lutaml-model#550: `with:` custom methods opt into the options
+      # passed to `from_*` / `to_*` by declaring a second parameter
+      # (exact arity 2); one-parameter methods keep the historical
+      # single-argument call.
+      def invoke_transform(method, value)
+        if method.arity == 2
+          method.call(value, context)
+        else
+          method.call(value)
         end
       end
 
@@ -87,8 +106,8 @@ module Lutaml
 
     class ImportTransformer < Transformer
       class << self
-        def call(value, rule, attribute, format: nil)
-          apply_static(value, [rule, attribute], :import, format)
+        def call(value, rule, attribute, format: nil, context: nil)
+          apply_static(value, [rule, attribute], :import, format, context)
         end
       end
 
@@ -103,8 +122,8 @@ module Lutaml
 
     class ExportTransformer < Transformer
       class << self
-        def call(value, rule, attribute, format: nil)
-          apply_static(value, [attribute, rule], :export, format)
+        def call(value, rule, attribute, format: nil, context: nil)
+          apply_static(value, [attribute, rule], :export, format, context)
         end
       end
 

data/lib/lutaml/model/store.rb

@@ -6,15 +6,28 @@ require "weakref" unless Lutaml::Model.opal?
 module Lutaml
   module Model
     class Store
-      # Compact dead WeakRef shells once a class bucket grows past this size.
+      # Compact dead index entries once a class bucket grows past this size.
       COMPACTION_THRESHOLD = 1000
 
       # Once the threshold is exceeded, only compact every Nth subsequent
-      # register call. Amortises the O(N) reject! over N inserts so
+      # register call. Amortises the O(N) prune over N inserts so
       # register stays O(1) per call rather than O(N) per call (O(N^2)
       # cumulatively for the class).
       COMPACTION_INTERVAL = 1000
 
+      WeakBucket = if Lutaml::Model.opal?
+                     # Opal has neither WeakRef nor ObjectSpace::WeakMap; documents in
+                     # the browser are small, so strong references are the fallback.
+                     ::Hash
+                   else
+                     # CRuby: WeakMap holds keys weakly with zero Ruby-level
+                     # allocation per insert and no per-object finalizer — the WeakRef
+                     # approach allocated one finalizer-registering object per
+                     # instance (lutaml-model#695) and dominated GC cycles on
+                     # instance-heavy parses.
+                     ::ObjectSpace::WeakMap
+                   end
+
       class << self
         def instance
           @instance ||= new
@@ -42,8 +55,10 @@ module Lutaml
       end
 
       def initialize
-        @store = ::Hash.new { |hash, key| hash[key] = [] }
-        # Nested index: { model_key => { reference_key => { value => WeakRef(object) } } }
+        # WeakMap-based buckets: value presence marks liveness, no
+        # per-instance allocation (lutaml-model#695).
+        @store = ::Hash.new { |hash, key| hash[key] = WeakBucket.new }
+        # Nested index: { model_key => { reference_key => { value => object } } }
         # Grouped by model_key so register only iterates this class's own indices.
         @index = {}
         @inserts_since_compaction = ::Hash.new(0)
@@ -52,11 +67,10 @@ module Lutaml
 
       def register(object)
         model_key = object.class.to_s
-        refs = @store[model_key]
-        refs << WeakRef.new(object)
+        @store[model_key][object] = true
         @inserts_since_compaction[model_key] += 1
 
-        compact_if_needed(refs, model_key)
+        compact_if_needed(model_key)
 
         update_existing_indices(object, model_key)
       end
@@ -78,25 +92,26 @@ module Lutaml
         obj
       end
 
+      def live_objects(model_key)
+        bucket = @store[model_key]
+        return [] unless bucket
+
+        live_objects_for(bucket)
+      end
+
       def clear
-        @store = ::Hash.new { |hash, key| hash[key] = [] }
+        @store = ::Hash.new { |hash, key| hash[key] = WeakBucket.new }
         @index = {}
         @inserts_since_compaction = ::Hash.new(0)
         @compaction_count = 0
       end
 
       def store
-        @store.transform_values do |refs|
-          refs.each_with_object([]) do |ref, alive|
-            alive << ref.__getobj__ if ref.weakref_alive?
-          rescue WeakRef::RefError
-            nil
-          end
-        end
+        @store.transform_values { |refs| live_objects_for(refs) }
       end
 
       def refs_for(model_key)
-        @store[model_key]
+        LiveView.new(self, model_key)
       end
 
       def inserts_since_compaction
@@ -117,15 +132,15 @@ module Lutaml
         @index[model_key] ||= {}
       end
 
-      # Build index for a (model_class, reference_key) pair by scanning existing instances.
+      # Build index for a (model_class, reference_key) pair by scanning
+      # live instances. Index values hold WeakRefs: the index must not
+      # pin objects (only the rare classes with resolved reference keys
+      # pay this; the per-instance bucket stays allocation-free WeakMap).
       def build_index(model_indices, model_key, reference_key)
         entries = model_indices[reference_key] = {}
-        @store[model_key]&.each do |ref|
-          obj = ref.__getobj__
+        each_live(model_key) do |obj|
           value = obj.public_send(reference_key)
           entries[value] = WeakRef.new(obj) if value
-        rescue WeakRef::RefError
-          next
         end
       end
 
@@ -136,11 +151,9 @@ module Lutaml
         model_indices = @index[model_key]
         return unless model_indices
 
-        model_indices.each do |reference_key, entries|
+        model_indices.each_key do |reference_key|
           value = object.public_send(reference_key)
-          entries[value] = WeakRef.new(object) if value
-        rescue WeakRef::RefError
-          next
+          model_indices[reference_key][value] = WeakRef.new(object) if value
         end
       end
 
@@ -150,17 +163,11 @@ module Lutaml
         nil
       end
 
-      def compact_if_needed(refs, model_key)
-        return unless refs.size > COMPACTION_THRESHOLD
+      def compact_if_needed(model_key)
         return unless @inserts_since_compaction[model_key] >= COMPACTION_INTERVAL
 
         @inserts_since_compaction[model_key] = 0
         @compaction_count += 1
-        refs.reject! do |ref|
-          !ref.weakref_alive?
-        rescue WeakRef::RefError
-          true
-        end
         prune_index(model_key)
       end
 
@@ -177,6 +184,37 @@ module Lutaml
           entries.empty?
         end
       end
+
+      def each_live(model_key, &block)
+        @store[model_key]&.each_key(&block)
+      end
+
+      def live_objects_for(bucket)
+        # WeakMap#each_key requires a block on CRuby; WeakMap#each
+        # yields key/value pairs, and Hash buckets enumerate the same
+        # way (value is `true` for WeakMap, the object for the Opal
+        # fallback keyed by object identity).
+        bucket.map { |key, _value| key }
+      end
+
+      # Array-shaped live view over a class's WeakMap bucket, for
+      # specs/debugging (refs_for used to expose the raw array).
+      class LiveView
+        include Enumerable
+
+        def initialize(store, model_key)
+          @store = store
+          @model_key = model_key
+        end
+
+        def each(&block)
+          @store.live_objects(@model_key).each(&block)
+        end
+
+        def size
+          @store.live_objects(@model_key).size
+        end
+      end
     end
   end
 end

data/lib/lutaml/model/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Model
-    VERSION = "0.8.36"
+    VERSION = "0.8.38"
   end
 end

data/lib/lutaml/xml/format.rb

@@ -21,6 +21,7 @@ end
 
 module Lutaml
   module Xml
+    autoload :HtmlEntities, "#{__dir__}/html_entities"
     autoload :PlanCompiler, "#{__dir__}/plan_compiler"
     autoload :PlanHydrator, "#{__dir__}/plan_hydrator"
     autoload :PlanOrder, "#{__dir__}/plan_order"