lutaml-model 0.8.38 → 0.8.39

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad19014fa289dad72ab50f6908d425ed7708b4f7046432ac05426b65087fc713
-  data.tar.gz: 4f2d95722e22e73b3691e6eec7903d3967ec1d9cf9ea2b641b02b77cc59911ef
+  metadata.gz: 15f9489eb4db353b481f160703e848e35b730cef179d32874941fc537ed962d3
+  data.tar.gz: f0067a5ffc4d66c8312d9cc478d9bd7d1771d9b639111c3158956b2d98e4468e
 SHA512:
-  metadata.gz: 575ac30c297c4d8059bccb27b42b1d1e942ffef3352072f1ebdbff55039073cffb228a2e6873c55afd940bc78aaac1830c5375df0b37ac1b4eb498cea3a73fe2
-  data.tar.gz: 4d1c80a2a3fd04e5c461aec33ba2248547ae5f6c877990f457d23160c272a4f67e17ef4ab05ad450265f5c2aa8c5c637deead3c27b20a2ea1978ab4815d6d397
+  metadata.gz: 9f1372cbf492e141015524382a3ac98cdc5f484441d70c593b7ad67b9021bfa959732700679534bb3690f86c064e3a1a82269833c5c73794fe87af24f21d239b
+  data.tar.gz: '048d412becdba7a8a99070740663d0d0a33e88d02018708818ce816d1ba4669a1f26efbf08d0c67390818c5efede0e362ef8f1785536c4233a2fa6dadd07da61'

data/docs/_guides/custom-methods.adoc

@@ -0,0 +1,71 @@
+= Custom serialization methods
+
+:toc:
+
+Lutaml::Model maps serialization constructs (`map_element`, `map_attribute`, `map_content`, key-value `map`) to *model attributes*. When the wire shape and the model shape disagree, custom methods bridge the gap at the mapping site instead of hand-rolled `to_h`/`from_h` code.
+
+== `with:` — per-rule custom methods
+
+Declare both directions on the rule. The methods live on the model (instance methods); the names are symbols.
+
+[source,ruby]
+----
+class Requirement
+  include Lutaml::Model::Serialize
+
+  attribute :guidance, :string
+  attribute :purpose, :string
+
+  xml do
+    element "requirement"
+    map_element "component", to: :guidance,
+      with: { from: :component_from_guidance, to: :component_to_guidance }
+  end
+
+  def component_from_guidance(model, value, ctx = nil)
+    # `from` receives (model, value[, context]); assign the model attribute
+    model.guidance = value
+  end
+
+  def component_to_guidance(model, parent, doc = nil, ctx = nil)
+    # `to` receives (model, parent[, doc[, context]]); write into parent/doc
+    parent.add_element("component", model.guidance, type: "guidance")
+  end
+end
+----
+
+Notes:
+
+* The `from` method *assigns* the attribute (it receives the whole model); the `to` method *writes* the output document.
+* The optional trailing `context` parameter receives the options hash passed to `Model.from_xml(data, context: {...})` / `model.to_xml(context: {...})` — it is forwarded when the method declares it (lutaml-model#550).
+* Callables work in key-value mappings: `with: { from: ->(value) { ... } }` maps and assigns the return value; an exact-arity-2 callable receives the context as its second argument.
+
+== `transform:` — value-level transforms
+
+`transform:` converts values (not documents). A Hash form (`transform: { from: ->(v) {...}, to: ->(v) {...} }`) wraps the value in both directions without touching assignment; a `ValueTransformer` subclass receives `from(value, format)` / `to(value, format)` and is shared by every rule that references it.
+
+== Type-level serialization
+
+A *type class* (a `Lutaml::Model::Type::Value` subclass) can carry its own format behavior, so reuse lives on the type rather than the parent mapping:
+
+[source,ruby]
+----
+class XmiNsType < Lutaml::Model::Type::String
+  xml do
+    namespace XmiNs # bind the type's own namespace
+  end
+end
+----
+
+`Lutaml::Model::Type::Value.register_format_type_serializer(format, type_class, to:, from:)` registers per-format serialize/deserialize procs for a type class; resolution walks the hierarchy.
+
+== `of_*` and the conversion entry points
+
+`Model.of_<format>(parsed_document, options)` is the documented seam between adapter parsing and mapping application: the adapter (`from_<format>`) parses the wire data into a document object, and `of_<format>` (class method) applies the mappings to build instances. It is public API for tooling that already holds a parsed document — e.g. re-applying mappings to a reparsed tree — and is what `from_<format>` delegates to.
+
+The per-instance counterparts are `to_<format>` (serialize through the mappings) and `as_<format>` (render without register-specific side effects). Prefer the generated `from_*/to_*` methods; reach for `of_*` only when you interpose between parse and mapping.
+
+== Common recipes
+
+* One wire element, several attributes dispatched by an attribute value (`component/@type`): one `with:` pair per attribute whose `from` inspects the dispatch attribute and whose `to` emits only for its type. (Polymorphic *class* dispatch has first-class support via `polymorphic:`.)
+* Key remapping, nesting shifts, delimiter splitting: prefer `transform:`, `child_mappings`, and `root`/`prefix` options before custom methods — the mapping stays declarative and reviewable.

data/docs/_guides/index.adoc

@@ -19,6 +19,7 @@ Task-oriented guides for accomplishing specific goals with Lutaml::Model.
 
 == Key-value serialization
 
+* link:../custom-methods[Custom Serialization Methods] - with:/transform:, type-level serialization, of_* entry points
 * link:../keyvalue-serialization[Key-Value Serialization] - JSON/YAML/TOML/Hash
 * link:../collection-serialization[Collection Serialization] - JSONL and YAML Stream
 

data/lib/lutaml/key_value/transform.rb

@@ -286,7 +286,6 @@ format)
           # only nil (non-existent) skips it (lutaml-model#746).
           return if value.nil?
 
-          warn "PROBE-264 keys=#{options.keys.inspect} ctx=#{options[:context].inspect}"
           return rule.deserialize(instance, value, attributes, model_class,
                                   options[:context])
         end

data/lib/lutaml/model/compiled_rule.rb

@@ -208,6 +208,15 @@ module Lutaml
       # @param args [Array] Arguments (ignored for options)
       # @param block [Proc] Block (ignored for options)
       # @return [Object] The option value or nil
+      # Static per rule (see MappingRule#custom_method_only?). Compiled
+      # rules are frozen, so the answer is recomputed with a single
+      # to_s instead of the historical two.
+      def custom_method_only?
+        name = attribute_name.to_s
+        (name.start_with?("__") && name.end_with?("__")) ||
+          (!custom_methods.empty? && attribute_type.nil?)
+      end
+
       def method_missing(method_name, *args, &block)
         # Check if this is an option key
         if options.key?(method_name)

data/lib/lutaml/model/mapping/mapping_rule.rb

@@ -307,6 +307,18 @@ context = nil)
         end
       end
 
+      # Static per rule: placeholder `__name__` targets and inferred
+      # custom-method targets without an attribute type never change —
+      # the applier asked this per element and paid two to_s strings
+      # each time (240k allocations on the ISO-13849 serialize profile).
+      # Rules may be frozen, so no per-instance memo: one to_s instead
+      # of two is the frozen-safe diet.
+      def custom_method_only?
+        name = attribute_name.to_s
+        (name.start_with?("__") && name.end_with?("__")) ||
+          (has_custom_methods? && attribute_type.nil?)
+      end
+
       def has_custom_method_for_serialization?
         !custom_methods.empty? && custom_methods[:to]
       end

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

@@ -264,9 +264,12 @@ module Lutaml
           # 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
+          reader_defined = if Lutaml::Model.opal?
+                             method_defined?(attr_reader_method)
+                           else
+                             method_defined?(attr_reader_method, false)
+                           end
+          define_method(attr_reader_method) { attr } unless reader_defined
 
           if attr.collection?
             # class_eval interpolates, e.g.:

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
 
+      # Ivar symbols for lazy collections, memoized per attribute name:
+      # the "@name" interpolation allocated twice per collection read
+      # (491k on the ISO-13849 serialize profile).
+      LAZY_IVAR = {}.compare_by_identity
+
       # 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.
@@ -406,11 +411,16 @@ module Lutaml
       # @param attribute_name [Symbol] the collection attribute
       # @return [Object] the stored collection
       def materialize_lazy_collection(attribute_name)
-        current = instance_variable_get(:"@#{attribute_name}")
+        ivar = LAZY_IVAR[attribute_name]
+        unless ivar
+          ivar = :"@#{attribute_name}"
+          LAZY_IVAR[attribute_name] = ivar
+        end
+        current = instance_variable_get(ivar)
         return current unless current.equal?(LAZY_EMPTY_COLLECTION)
         return current if frozen?
 
-        instance_variable_set(:"@#{attribute_name}", [])
+        instance_variable_set(ivar, [])
       end
 
       # Hand back a reference collection the caller can push onto.

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

@@ -19,7 +19,10 @@ module Lutaml
           end
 
           value = value.to_s
-          value = value.gsub(/[\t\n\r]/, " ") unless mode == :preserve
+          # tr, not gsub: the regexp engine is measurable on hot text
+          # paths; :collapse keeps squeeze+strip (two C passes, no
+          # intermediate regexp state).
+          value = value.tr("\t\n\r", " ") unless mode == :preserve
           value = value.squeeze(" ").strip if mode == :collapse
 
           unless options.equal?(EMPTY_OPTIONS)

data/lib/lutaml/model/version.rb

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

data/lib/lutaml/xml/model_transform.rb

@@ -18,9 +18,13 @@ module Lutaml
       # 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 has no compare_by_identity; class identity is
-      # the key semantic here.
-      RULE_RECORDS = Concurrent::Map.new # rubocop:disable Lint/HashCompareByIdentity
+      # 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.
@@ -724,8 +728,11 @@ _effective_register)
 
         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
-          (RULE_RECORDS[model_class.object_id] = Concurrent::Map.new) # rubocop:disable Lint/HashCompareByIdentity,Layout/MultilineAssignmentLayout
+        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
 

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lutaml-model
 version: !ruby/object:Gem::Version
-  version: 0.8.38
+  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