lutaml-model 0.8.37 → 0.8.39

data/lib/lutaml/xml/model_transform.rb

@@ -12,6 +12,20 @@ module Lutaml
     # - Used by model's serialization pipeline via Transform.for(:xml)
     #
     class ModelTransform < ::Lutaml::Model::Transform
+      require "cgi" unless Lutaml::Model.opal?
+
+      # Per (model class, register): compiled records for the mapping
+      # rules — attribute, derived/valid flags, and #765 group-skip —
+      # keyed on the mapping's finalize version so late changes rebuild.
+      # The loop body used to re-derive these per parsed instance.
+      # Concurrent::Map under threaded MRI, plain Hash under Opal
+      # (Concurrent is unavailable there); class identity keys either.
+      RULE_RECORDS = if Lutaml::Model.opal?
+                       {}
+                     else
+                       Concurrent::Map.new # rubocop:disable Lint/HashCompareByIdentity
+                     end
+
       # Namespaced rule name -> [local_name, rule_uri]. Pure string
       # splitting, deterministic per spelling, shared across parses.
       # Concurrent::Map under threaded MRI, plain Hash under Opal.
@@ -36,7 +50,19 @@ module Lutaml
 
         instance_is_serialize = model_class.include?(::Lutaml::Model::Serialize)
         if instance_is_serialize
+          # TODO.max-perf/17: the same child element was being re-hydrated
+          # per matching rule (593k instantiations for 12k elements on the
+          # ISO-13849 profile). Memoize one instance per (element, class)
+          # for the whole parse; the memo travels in the propagated
+          # deserialization options.
+          memo = options[:__lutaml_child_memo] ||= {}
+          memo_key = [data.object_id, model_class.object_id]
+          if (existing = memo[memo_key])
+            return existing
+          end
+
           instance = model_class.allocate_for_deserialization(child_register)
+          memo[memo_key] = instance
         else
           instance = model_class.new
           register_accessor_methods_for(instance, child_register)
@@ -281,24 +307,33 @@ module Lutaml
           effective_register,
         )
 
+        serializable = instance.class.include?(Lutaml::Model::Serialize)
+        records = if serializable
+                    compiled_rule_records(instance.class, effective_register,
+                                          grouped_plain_rules)
+                  end
         mappings.each do |rule|
-          # Performance: Cache rule properties accessed multiple times
-          rule.name
+          record = records&.[](rule)
           rule_to = rule.to
-          rule_namespace_set = rule.namespace_set?
-          rule_namespace_set ? rule.namespace_param : nil
 
-          attr = attribute_for_rule(rule)
-          next if attr&.derived?
+          if record
+            attr = record.attr
+            next if record.derived
+            next if record.group_skip
 
-          if (group = grouped_plain_rules[rule_to]) &&
-              group.size > 1 && attr&.collection? && !group.first.equal?(rule)
-            next
-          end
+            raise "Attribute '#{rule_to}' not found in #{context}" unless record.valid
+          else
+            attr = attribute_for_rule(rule)
+            next if attr&.derived?
 
-          raise "Attribute '#{rule_to}' not found in #{context}" unless valid_rule?(
-            rule, attr
-          )
+            group = grouped_plain_rules[rule_to]
+            next if group && group.size > 1 && attr&.collection? &&
+              !group.first.equal?(rule)
+
+            raise "Attribute '#{rule_to}' not found in #{context}" unless valid_rule?(
+              rule, attr
+            )
+          end
 
           # Performance: Use pre-computed frozen Hash for static namespace overrides.
           # Falls back to per-element hash only for the dynamic namespace_uri case.
@@ -371,6 +406,9 @@ module Lutaml
           value = apply_value_map(value, from_map, attr)
           value = normalize_xml_value(value, rule, attr, new_opts,
                                       effective_register)
+          value = decode_html_entities_value(value, decode_html_entities_for(
+                                                      instance, effective_register
+                                                    ))
           value = rule.transform_value(attr, value, :from, :xml)
           # An over-count is normally left for `.validate` to report. A mapped
           # PORO has no `.validate`, so deferring there would discard the
@@ -379,7 +417,8 @@ module Lutaml
               !rule.content_mapping?
             attr.valid_collection!(value, context)
           end
-          rule.deserialize(instance, value, attributes, context)
+          rule.deserialize(instance, value, attributes, context,
+                           options[:context])
 
           instance.value_set_for(rule_to)
         end
@@ -512,11 +551,13 @@ _effective_register)
         # its result array entirely on that path.
         if rule_names.size == 1
           rn = rule_names[0]
-          converted = convert_rule_name_to_attribute_name(doc, rn)
+          converted = convert_rule_name_to_attribute_name(doc, rn,
+                                                          session: session)
           value = doc.root.find_attribute_value(converted || rn)
         else
           attribute_names = rule_names.map do |rn|
-            converted = convert_rule_name_to_attribute_name(doc, rn)
+            converted = convert_rule_name_to_attribute_name(doc, rn,
+                                                            session: session)
             converted || rn
           end
 
@@ -545,7 +586,7 @@ _effective_register)
       # @param doc [XmlElement] the parsed XML document root
       # @param rule_name [String] the rule name (e.g., "urn:...:ext", "http://.../ns:val", "my-ns:val")
       # @return [String, nil] the attribute name to look up, or nil if no conversion needed
-      def convert_rule_name_to_attribute_name(doc, rule_name)
+      def convert_rule_name_to_attribute_name(doc, rule_name, session: nil)
         return nil unless rule_name.include?(":")
 
         # URI-vs-prefix detection works on the whole rule name: the
@@ -564,13 +605,27 @@ _effective_register)
           # match, and unprefixed_name is not called per attribute
           # (it splits prefixed names and allocates).
           local_name = rule_name[(last_colon_index + 1)..]
-          doc.root.attributes.each_value.find do |attr|
-            ns = attr.namespace
-            next false if ns.nil? || ns.length > last_colon_index
-            next false unless rule_name.start_with?(ns) && rule_name[ns.length] == ":"
+          if session
+            candidates = session.element_local_attribute_index(doc.root)[local_name]
+            # No candidate carries this local name: nothing in the
+            # element can match, the scan is skipped entirely.
+            matched = candidates&.find do |attr|
+              ns = attr.namespace
+              next false if ns.nil? || ns.length > last_colon_index
+              next false unless rule_name.start_with?(ns) && rule_name[ns.length] == ":"
+
+              attr.unprefixed_name == local_name
+            end
+          else
+            matched = doc.root.attributes.each_value.find do |attr|
+              ns = attr.namespace
+              next false if ns.nil? || ns.length > last_colon_index
+              next false unless rule_name.start_with?(ns) && rule_name[ns.length] == ":"
 
-            attr.unprefixed_name == local_name
-          end&.name
+              attr.unprefixed_name == local_name
+            end
+          end
+          matched&.name
         else
           # Simple prefix format: look up the actual prefix from document's namespace declarations
           # The namespace_part is the namespace URI declared in the document (e.g., "my-ns").
@@ -594,39 +649,46 @@ _effective_register)
       # @return [String, nil] the attribute value or nil
       def find_attribute_by_local_name(doc, rule_names,
                                        flexible_local: false, session: nil)
-        root_index = session&.root_local_attribute_index
-
-        rule_names.each do |rn|
-          next unless rn.include?(":")
-
-          # Splitting a namespaced rule name is pure string work repeated
-          # per element; memoized per spelling (bounded by the model's
-          # distinct rule names).
-          parts = NAMESPACED_NAME_PARTS[rn]
-          unless parts
-            last_colon_index = rn.rindex(":")
-            parts = [rn[(last_colon_index + 1)..], rn[0...last_colon_index]]
-            NAMESPACED_NAME_PARTS[rn] = parts
-          end
-          local_name, rule_uri = parts
+        root_index = session&.element_local_attribute_index(doc.root)
 
-          candidates = root_index&.[](local_name)
-          matched_attr = if candidates
-                           candidates.find do |attr|
-                             local_name_match?(attr, local_name, rule_uri,
-                                               flexible_local)
-                           end
-                         else
-                           doc.root.attributes.each_value.find do |attr|
-                             local_name_match?(attr, local_name, rule_uri,
-                                               flexible_local)
-                           end
-                         end
-          return matched_attr&.value if matched_attr
+        rule_names.each do |rule_name|
+          next unless rule_name.include?(":")
+
+          resolved = match_attribute_by_local_name(
+            doc, rule_name, root_index, flexible_local
+          )
+          return resolved if resolved
         end
         nil
       end
 
+      def match_attribute_by_local_name(doc, rule_name, root_index, flexible_local)
+        # Splitting a namespaced rule name is pure string work repeated
+        # per element; memoized per spelling (bounded by the model's
+        # distinct rule names).
+        parts = NAMESPACED_NAME_PARTS[rule_name]
+        unless parts
+          last_colon_index = rule_name.rindex(":")
+          parts = [rule_name[(last_colon_index + 1)..], rule_name[0...last_colon_index]]
+          NAMESPACED_NAME_PARTS[rule_name] = parts
+        end
+        local_name, rule_uri = parts
+
+        candidates = root_index&.[](local_name)
+        matched_attr = if candidates
+                         candidates.find do |attr|
+                           local_name_match?(attr, local_name, rule_uri,
+                                             flexible_local)
+                         end
+                       else
+                         doc.root.attributes.each_value.find do |attr|
+                           local_name_match?(attr, local_name, rule_uri,
+                                             flexible_local)
+                         end
+                       end
+        matched_attr&.value
+      end
+
       # Namespace discipline of the lenient local-name fallback
       # (#744/#758/#790): sole claimants bind any qualification; shared
       # names must resolve to the rule's namespace.
@@ -648,6 +710,68 @@ _effective_register)
         (colon = attr.name.rindex(":")) ? attr.name[(colon + 1)..] : attr.name
       end
 
+      # lutaml-model#154: decode HTML entities for mappings that opted in
+      # (`html_entities` in the xml block). Values stay untouched
+      # otherwise — XML keeps undefined entities literal by design.
+      def decode_html_entities_value(value, enabled)
+        return value if value.nil? || !value.is_a?(String)
+        return value unless enabled
+        return value if Lutaml::Model.opal?
+
+        Lutaml::Xml::HtmlEntities.decode(value)
+      end
+
+      Record = Struct.new(:attr, :derived, :group_skip, :valid)
+
+      def compiled_rule_records(model_class, register, grouped_plain_rules)
+        return {}.compare_by_identity unless model_class.include?(Lutaml::Model::Serialize)
+
+        mapping = model_class.mappings_for(:xml, register)
+        version = mapping&.rule_records_version.to_i
+        per_class = RULE_RECORDS[model_class.object_id] # rubocop:disable Lint/HashCompareByIdentity
+        unless per_class
+          per_class = Lutaml::Model.opal? ? {} : Concurrent::Map.new
+          RULE_RECORDS[model_class.object_id] = per_class # rubocop:disable Lint/HashCompareByIdentity
+        end
+        cached = per_class[register]
+        return cached.records if cached && cached.version == version
+
+        records = {}.compare_by_identity
+        mapping&.mappings(register)&.each do |rule| # rubocop:disable Style/SafeNavigationChain,Style/SafeNavigation
+          attr = attribute_for_rule_static(model_class, rule, register)
+          group = grouped_plain_rules[rule.to]
+          records[rule] = Record.new(
+            attr,
+            attr&.derived? || false,
+            !!(group && group.size > 1 && attr&.collection? &&
+               !group.first.equal?(rule)),
+            !!(attr || rule.custom_methods[:from]),
+          )
+        end
+        entry = Struct.new(:version, :records).new(version, records)
+        per_class[register] = entry
+        records
+      end
+
+      def attribute_for_rule_static(model_class, rule, register)
+        if rule.delegate
+          delegate_attr = model_class.attributes(register)[rule.delegate]
+          delegate_type = delegate_attr&.type(register)
+          delegate_type&.attributes(register)&.[](rule.to) # rubocop:disable Style/SafeNavigationChain
+        else
+          model_class.attributes(register)[rule.to]
+        end
+      rescue StandardError
+        nil
+      end
+
+      def decode_html_entities_for(instance, register)
+        klass = instance.class
+        return false unless klass.is_a?(Class) && klass.include?(Lutaml::Model::Serialize)
+
+        klass.mappings_for(:xml, register)&.decode_html_entities?
+      end
+
       def value_for_rule(session, rule, options, cached_attr = nil,
                          extra_rule_names = nil)
         doc = session.doc
@@ -682,12 +806,16 @@ _effective_register)
         rule_names = rule_names.concat(extra_rule_names).uniq if extra_rule_names
 
         if rule.attribute?
-          return value_for_xml_attribute(
+          value = value_for_xml_attribute(
             doc, rule, rule_names,
             flexible_local: attribute_rule_sole_local_claimant?(
               instance, rule, effective_register
-            )
+            ),
+            session: session
           )
+          return decode_html_entities_value(value, decode_html_entities_for(
+                                                     instance, effective_register
+                                                   ))
         end
 
         # Performance: Pre-compute type-related values used in the hot loop

data/lib/lutaml/xml/parse_session.rb

@@ -24,18 +24,31 @@ module Lutaml
         @instance_is_serialize ||= instance.is_a?(::Lutaml::Model::Serialize)
       end
 
-      # Local-name -> [attributes] index over the root element's
-      # attributes, built on first lenient lookup (TODO.max-perf/08).
-      # The fallback used to rescan every attribute per missed rule;
-      # elements are parse-frozen, so the index builds at most once per
-      # session. Each attribute is filed under every local-name spelling
-      # the matcher compares (unprefixed name and colon-split local).
-      def root_local_attribute_index
-        @root_local_attribute_index ||= begin
-          index = ::Hash.new { |h, k| h[k] = [] }
-          doc.root.attributes.each_value do |attr|
+      # (element, rule name) -> resolved attribute name / matched
+      # attribute VALUE for the lenient lookup paths. Both are pure
+      # functions of the element and the name; ISO-13849-shaped
+      # documents repeat the same resolutions per rule application, so
+      # the computed answer is memoized per element for the parse.
+      def rule_name_resolution
+        @rule_name_resolution ||= {}
+      end
+
+      # Local-name -> [attributes] index over one element's attributes,
+      # built on first lenient lookup (TODO.max-perf/08) and memoized per
+      # element for the life of the session. The URI-form attribute
+      # conversion and the lenient fallback used to rescan every
+      # attribute per rule per element (the ISO-13849 pathology);
+      # elements are parse-frozen, so each index builds at most once.
+      def element_local_attribute_index(element)
+        @element_local_attribute_index ||= {}.compare_by_identity
+        @element_local_attribute_index[element] ||= begin
+          # Plain hash: a miss must stay a nil lookup, not allocate an
+          # empty default array — misses dominate (the ISO-13849 shape
+          # resolves ~390k lenient lookups that match nothing).
+          index = {}
+          element.attributes.each_value do |attr|
             local_names(attr).each do |key|
-              entries = index[key]
+              entries = (index[key] ||= [])
               entries << attr unless entries.include?(attr)
             end
           end

data/lib/lutaml/xml/transformation/rule_applier.rb

@@ -227,13 +227,7 @@ register_id)
         # @param rule [CompiledRule] The rule
         # @return [Boolean] true if custom method only
         def custom_method_only?(rule)
-          # Check if attribute name is a placeholder (e.g., :__content__)
-          return true if rule.attribute_name.to_s.start_with?("__") &&
-            rule.attribute_name.to_s.end_with?("__")
-
-          # Also check if rule has custom methods but attribute_type is nil
-          # This handles cases where we inferred an attribute name for custom methods
-          rule.has_custom_methods? && rule.attribute_type.nil?
+          rule.custom_method_only?
         end
 
         # Extract value for a rule

data/lib/lutaml/yaml/format.rb

@@ -24,6 +24,7 @@ Lutaml::Model::FormatRegistry.register(
     available: %i[standard standard_yaml yeptris],
     default: :standard,
   },
+  stream_methods: true,
 )
 
 require_relative "type/serializers"

data/spec/lutaml/model/custom_method_context_spec.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# lutaml-model#550: options passed to `from_*` / `to_*` flow to custom
+# methods that declare the extra context parameter (arity-aware; the
+# historical signatures keep working).
+RSpec.describe "Custom method context forwarding" do
+  let(:model_class) do
+    Class.new(Lutaml::Model::Serializable) do
+      attribute :name, :string
+
+      def name_from(model, value, ctx = nil)
+        model.name = "#{value} (#{ctx ? ctx[:schema] : 'none'})"
+      end
+
+      def name_to(model, hash, ctx = nil)
+        hash["name"] = "#{model.name} <#{ctx ? ctx[:schema] : 'none'}>"
+      end
+
+      key_value do
+        map "name", to: :name,
+                    with: { from: :name_from, to: :name_to }
+      end
+    end
+  end
+
+  it "passes context to custom methods on parse when accepted" do
+    parsed = model_class.from_yaml({ "name" => "Alpine" }.to_yaml,
+                                   context: { schema: "ISO" })
+    expect(parsed.name).to eq("Alpine (ISO)")
+  end
+
+  it "passes context to custom methods on serialize when accepted" do
+    instance = model_class.from_yaml({ "name" => "Alpine" }.to_yaml)
+    out = instance.to_yaml(context: { schema: "ISO" })
+    expect(out).to include("Alpine (none) <ISO>")
+  end
+
+  it "keeps two-parameter custom methods working without context" do
+    parsed = model_class.from_yaml({ "name" => "Alpine" }.to_yaml)
+    expect(parsed.name).to eq("Alpine (none)")
+
+    out = parsed.to_yaml
+    expect(out).to include("Alpine (none) <none>")
+  end
+
+  it "forwards context to with-lambdas of exact arity 2" do
+    klass = Class.new(Lutaml::Model::Serializable) do
+      attribute :code, :string
+
+      key_value do
+        map "code", to: :code,
+                    with: { from: ->(value, ctx) { "#{value}-#{ctx[:rev]}" } }
+      end
+    end
+
+    parsed = klass.from_yaml({ "code" => "A1" }.to_yaml,
+                              context: { rev: 7 })
+    expect(parsed.code).to eq("A1-7")
+  end
+end

data/spec/lutaml/model/yaml_stream_spec.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# lutaml-model#436: multi-document YAML streams with per-document model
+# dispatch (the glossarist-ruby#132 / ISO 5843-6 shape).
+RSpec.describe "YAML streams" do
+  let(:concept_class) do
+    Class.new(Lutaml::Model::Serializable) do
+      attribute :id, :string
+      attribute :language_code, :string
+
+      key_value do
+        map "id", to: :id
+        map "language_code", to: :language_code
+      end
+    end
+  end
+
+  let(:localized_class) do
+    Class.new(Lutaml::Model::Serializable) do
+      attribute :id, :string
+      attribute :status, :string
+
+      key_value do
+        map "id", to: :id
+        map "status", to: :status
+      end
+    end
+  end
+
+  let(:stream) do
+    <<~YAML
+      ---
+      id: 1-EN
+      language_code: eng
+      ---
+      id: 3a75
+      status: accepted
+      ---
+      id: 1-FR
+      language_code: fra
+    YAML
+  end
+
+  it "parses every document in the stream" do
+    models = concept_class.from_yaml_stream(stream)
+    expect(models.map(&:id)).to eq(%w[1-EN 3a75 1-FR])
+  end
+
+  it "dispatches documents polymorphically via discriminator" do
+    models = concept_class.from_yaml_stream(
+      stream,
+      discriminator: lambda { |doc|
+        doc.key?("language_code") ? concept_class : localized_class
+      },
+    )
+    expect(models.map(&:class)).to eq([concept_class, localized_class,
+                                       concept_class])
+    expect(models[1].status).to eq("accepted")
+  end
+
+  it "round-trips through to_yaml_stream" do
+    models = concept_class.from_yaml_stream(stream)
+    out = concept_class.to_yaml_stream(models)
+    reparsed = concept_class.from_yaml_stream(out)
+    expect(reparsed.map(&:id)).to eq(models.map(&:id))
+    expect(out).to include("---")
+  end
+end

data/spec/lutaml/xml/html_entities_spec.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# lutaml-model#154: HTML named/numeric entities decode only for
+# mappings that opt in via `html_entities` — XML otherwise keeps
+# undefined entities literal.
+RSpec.describe "Opt-in HTML entity decoding" do
+  context "when the mapping opts in" do
+    let(:model_class) do
+      Class.new(Lutaml::Model::Serializable) do
+        attribute :t, :string
+
+        xml do
+          element "doc"
+          map_element "t", to: :t
+          html_entities
+        end
+      end
+    end
+
+    it "decodes named and numeric entities in element text" do
+      parsed = model_class.from_xml("<doc><t>a &amp; b &#8212; c &copy; d</t></doc>")
+      expect(parsed.t).to eq("a & b — c © d")
+    end
+  end
+
+  context "when the mapping does not opt in" do
+    let(:model_class) do
+      Class.new(Lutaml::Model::Serializable) do
+        attribute :t, :string
+
+        xml do
+          element "doc"
+          map_element "t", to: :t
+        end
+      end
+    end
+
+    it "keeps undefined entities literal" do
+      parsed = model_class.from_xml("<doc><t>a &amp; b &copy; d</t></doc>")
+      expect(parsed.t).to eq("a & b &copy; d")
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lutaml-model
 version: !ruby/object:Gem::Version
-  version: 0.8.37
+  version: 0.8.39
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-18 00:00:00.000000000 Z
+date: 2026-09-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -202,6 +202,7 @@ files:
 - docs/_guides/character-encoding.adoc
 - docs/_guides/collection-serialization.adoc
 - docs/_guides/creating-xsd.adoc
+- docs/_guides/custom-methods.adoc
 - docs/_guides/document-validation.adoc
 - docs/_guides/index.adoc
 - docs/_guides/jsonld-serialization.adoc
@@ -776,6 +777,7 @@ files:
 - lib/lutaml/xml/format.rb
 - lib/lutaml/xml/format_chooser.rb
 - lib/lutaml/xml/hoisting_algorithm.rb
+- lib/lutaml/xml/html_entities.rb
 - lib/lutaml/xml/leptris/element.rb
 - lib/lutaml/xml/listener.rb
 - lib/lutaml/xml/mapping.rb
@@ -1716,6 +1718,7 @@ files:
 - spec/lutaml/model/custom_bibtex_adapter_spec.rb
 - spec/lutaml/model/custom_collection_spec.rb
 - spec/lutaml/model/custom_from_empty_values_spec.rb
+- spec/lutaml/model/custom_method_context_spec.rb
 - spec/lutaml/model/custom_model_spec.rb
 - spec/lutaml/model/custom_serialization_spec.rb
 - spec/lutaml/model/custom_vobject_adapter_spec.rb
@@ -1859,6 +1862,7 @@ files:
 - spec/lutaml/model/xsd_type_spec.rb
 - spec/lutaml/model/xsd_type_validation_spec.rb
 - spec/lutaml/model/yaml_adapter_spec.rb
+- spec/lutaml/model/yaml_stream_spec.rb
 - spec/lutaml/model/yamls/standard_adapter_spec.rb
 - spec/lutaml/model/yamls_range_spec.rb
 - spec/lutaml/model/yamls_sequence_spec.rb
@@ -1913,6 +1917,7 @@ files:
 - spec/lutaml/xml/format_chooser_spec.rb
 - spec/lutaml/xml/fpi_namespace_spec.rb
 - spec/lutaml/xml/general_namespace_spec.rb
+- spec/lutaml/xml/html_entities_spec.rb
 - spec/lutaml/xml/indent_spec.rb
 - spec/lutaml/xml/line_ending_spec.rb
 - spec/lutaml/xml/mapping_finalization_guard_spec.rb