Module: Lutaml::Model::Serialize

Includes:
ComparableModel, Liquefiable, Registrable, Builder, Validation
Included in:
Serializable
Defined in:
lib/lutaml/model/serialize.rb,
lib/lutaml/model/serialize/builder.rb,
lib/lutaml/model/serialize/model_import.rb,
lib/lutaml/model/serialize/enum_handling.rb,
lib/lutaml/model/serialize/value_mapping.rb,
lib/lutaml/model/serialize/initialization.rb,
lib/lutaml/model/serialize/format_conversion.rb,
lib/lutaml/model/serialize/attribute_definition.rb,
lib/lutaml/model/serialize/transformation_builder.rb,
lib/lutaml/model/serialize/deserialization_context.rb

Defined Under Namespace

Modules: AttributeDefinition, Builder, ClassMethods, EnumHandling, FormatConversion, Initialization, ModelImport, TransformationBuilder, ValueMapping Classes: DeserializationContext

Constant Summary collapse

DEFAULT_VALUE_MAP =

Performance: Pre-computed default value map to avoid per-call allocations

{
  omitted: :nil,
  nil: :nil,
  empty: :empty,
}.freeze
LAZY_EMPTY_COLLECTION =

Shared frozen sentinel for lazy collection initialization. The getter materializes a real Array on first access.

[].freeze
INTERNAL_ATTRIBUTES = 
%i[@using_default @lutaml_register @lutaml_parent @lutaml_root
@register_records].freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Liquefiable

#to_liquid

Methods included from Validation

#element_order, #format_element_sequences, new_registry, #order_names, #validate, validate, #validate!, validate!, #validate_helper, #validate_sequence!

Methods included from ComparableModel

#already_compared?, #attributes_hash, #calculate_hash, #comparison_key, #eql?, #hash, #same_class?

Methods included from Builder

#mixed_content?

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(method_name, *args) ⇒ Object

rubocop:disable Style/ArgumentsForwarding – anonymous * requires Ruby 3.2+, but required_ruby_version >= 3.0



179
180
181
182
183
184
185
186
187
188
 
# File 'lib/lutaml/model/serialize.rb', line 179

def method_missing(method_name, *args)
  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)
  else
    super
  end
end

Instance Attribute Details

#lutaml_parent ⇒ Object

Returns the value of attribute lutaml_parent.



88
89
90
 
# File 'lib/lutaml/model/serialize.rb', line 88

def lutaml_parent
  @lutaml_parent
end

#lutaml_register ⇒ Object

Returns the value of attribute lutaml_register.



88
89
90
 
# File 'lib/lutaml/model/serialize.rb', line 88

def lutaml_register
  @lutaml_register
end

#lutaml_root ⇒ Object

Returns the value of attribute lutaml_root.



88
89
90
 
# File 'lib/lutaml/model/serialize.rb', line 88

def lutaml_root
  @lutaml_root
end

Class Method Details

.included(base) ⇒ Object 



38
39
40
41
 
# File 'lib/lutaml/model/serialize.rb', line 38

def self.included(base)
  base.extend(ClassMethods)
  base.initialize_attrs(base)
end

.register_format_mapping_method(format) ⇒ Object 



56
57
58
59
60
61
62
 
# File 'lib/lutaml/model/serialize.rb', line 56

def self.register_format_mapping_method(format)
  method_name = format == :hash ? :hsh : format

  ::Lutaml::Model::Serialize::ClassMethods.define_method(method_name) do |*args, &block|
    process_mapping(format, *args, &block)
  end
end

.register_from_format_method(format) ⇒ Object 



64
65
66
67
68
69
70
71
72
 
# File 'lib/lutaml/model/serialize.rb', line 64

def self.register_from_format_method(format)
  ClassMethods.define_method(:"from_#{format}") do |data, options = {}|
    from(format, data, options)
  end

  ClassMethods.define_method(:"of_#{format}") do |doc, options = {}|
    of(format, doc, options)
  end
end

.register_to_format_method(format) ⇒ Object 



74
75
76
77
78
79
80
81
82
83
84
85
86
 
# File 'lib/lutaml/model/serialize.rb', line 74

def self.register_to_format_method(format)
  ClassMethods.define_method(:"to_#{format}") do |instance, options = {}|
    to(format, instance, options)
  end

  ClassMethods.define_method(:"as_#{format}") do |instance, options = {}|
    as(format, instance, options)
  end

  define_method(:"to_#{format}") do |options = {}|
    to_format(format, options)
  end
end

Instance Method Details

#attr_value(attrs, name, attribute) ⇒ Object 



148
149
150
151
152
 
# File 'lib/lutaml/model/serialize.rb', line 148

def attr_value(attrs, name, attribute)
  value = Utils.fetch_str_or_sym(attrs, name,
                                 attribute.default(lutaml_register, self))
  attribute.cast_value(value, lutaml_register)
end

#attribute_exist?(name) ⇒ Boolean

Returns:

  • (Boolean) 


196
197
198
199
200
 
# File 'lib/lutaml/model/serialize.rb', line 196

def attribute_exist?(name)
  name = name.to_s.chomp("=").to_sym if name.end_with?("=")

  self.class.attributes(lutaml_register).key?(name)
end

#define_singleton_attribute_methods ⇒ Object

Ensure register-specific attribute methods are defined on the class. Delegates to the class method which defines methods once per (class, register) combination instead of per-instance singleton methods.



264
265
266
 
# File 'lib/lutaml/model/serialize.rb', line 264

def define_singleton_attribute_methods
  self.class.ensure_register_methods_defined(lutaml_register)
end

#extract_register_id(attrs, options) ⇒ Object 



130
131
132
133
 
# File 'lib/lutaml/model/serialize.rb', line 130

def extract_register_id(attrs, options)
  register = attrs&.dig(:lutaml_register) || options&.dig(:register)
  self.class.extract_register_id(register)
end

#finalize_deserialization(register) ⇒ Object

Complete deserialization initialization after allocation. Called by allocate_for_deserialization to set up instance state, define register-specific methods, and register in the reference store.



124
125
126
127
128
 
# File 'lib/lutaml/model/serialize.rb', line 124

def finalize_deserialization(register)
  init_deserialization_state(register)
  define_singleton_attribute_methods
  register_in_reference_store
end

#init_deserialization_state(register) ⇒ Object

Initialize instance state for fast deserialization path. Called by allocate_for_deserialization instead of initialize. Uses nil for @using_default to mean “all attributes use default” —no hash allocation needed until value_set_for is called.



105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
 
# File 'lib/lutaml/model/serialize.rb', line 105

def init_deserialization_state(register)
  @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
end

#initialize(attrs = {}, options = {}) ⇒ Object 



90
91
92
93
94
95
96
97
98
99
 
# File 'lib/lutaml/model/serialize.rb', line 90

def initialize(attrs = {}, options = {})
  @using_default = {}
  @lutaml_register = extract_register_id(attrs, options)
  return unless self.class.attributes(@lutaml_register)

  initialize_attributes(attrs, options)
  define_singleton_attribute_methods

  register_in_reference_store
end

#key_exist?(hash, key) ⇒ Boolean

Returns:

  • (Boolean) 


210
211
212
 
# File 'lib/lutaml/model/serialize.rb', line 210

def key_exist?(hash, key)
  hash.key?(key.to_sym) || hash.key?(key.to_s)
end

#key_value(hash, key) ⇒ Object 



214
215
216
 
# File 'lib/lutaml/model/serialize.rb', line 214

def key_value(hash, key)
  hash[key.to_sym] || hash[key.to_s]
end

#prepare_instance_format_options(_format, _options) ⇒ Object

Hook for format-specific instance-level options preparation. XML overrides via InstanceMethods prepend.

Parameters:

  • _format (Symbol) —

    The format

  • _options (Hash) —

    Options hash (modified in place)



248
249
250
 
# File 'lib/lutaml/model/serialize.rb', line 248

def prepare_instance_format_options(_format, _options)
  # No-op by default
end

#pretty_print_instance_variables ⇒ Object 



218
219
220
221
222
223
 
# File 'lib/lutaml/model/serialize.rb', line 218

def pretty_print_instance_variables
  reference_attributes = instance_variables.select do |var|
    var.to_s.end_with?("_ref")
  end
  (instance_variables - INTERNAL_ATTRIBUTES - reference_attributes).sort
end

#register_in_reference_store ⇒ Object 



268
269
270
 
# File 'lib/lutaml/model/serialize.rb', line 268

def register_in_reference_store
  Lutaml::Model::Store.register(self) if self.class.reference_resolvable?
end

#respond_to_missing?(method_name, include_private = false) ⇒ Boolean

rubocop:enable Style/ArgumentsForwarding

Returns:

  • (Boolean) 


191
192
193
194
 
# File 'lib/lutaml/model/serialize.rb', line 191

def respond_to_missing?(method_name, include_private = false)
  (method_name.to_s.end_with?("=") && attribute_exist?(method_name)) ||
    super
end

#to_format(format, options = {}) ⇒ Object 



229
230
231
232
233
234
235
236
237
238
239
240
241
 
# File 'lib/lutaml/model/serialize.rb', line 229

def to_format(format, options = {})
  # Hook for format-specific validation (e.g., XML root mapping check)
  validate_root_mapping!(format, options)

  # Pass instance's lutaml_register if not explicitly provided
  options[:register] ||= lutaml_register if lutaml_register

  # Hook for format-specific options preparation
  # XML overrides to handle prefix, doctype, declaration, namespaces
  prepare_instance_format_options(format, options)

  self.class.to(format, self, options)
end

#to_yaml_hash ⇒ Object 



225
226
227
 
# File 'lib/lutaml/model/serialize.rb', line 225

def to_yaml_hash
  self.class.as_yaml(self)
end

#using_default?(attribute_name) ⇒ Boolean

Returns:

  • (Boolean) 


171
172
173
174
175
176
 
# File 'lib/lutaml/model/serialize.rb', line 171

def using_default?(attribute_name)
  # nil means "all attributes using default" — return true without allocation
  return true if @using_default.nil?

  @using_default[attribute_name]
end

#using_default_for(attribute_name) ⇒ Object 



154
155
156
157
 
# File 'lib/lutaml/model/serialize.rb', line 154

def using_default_for(attribute_name)
  @using_default ||= ::Hash.new(true)
  @using_default[attribute_name] = true
end

#validate_attribute!(attr_name) ⇒ Object 



202
203
204
205
206
207
208
 
# File 'lib/lutaml/model/serialize.rb', line 202

def validate_attribute!(attr_name)
  attr = self.class.attributes[attr_name]
  value = instance_variable_get(:"@#{attr_name}")
  resolver = Services::DefaultValueResolver.new(attr, lutaml_register,
                                                self)
  attr.validate_value!(value, lutaml_register, resolver)
end

#validate_root_mapping!(_format, _options) ⇒ Object

Hook for format-specific root mapping validation. XML overrides via InstanceMethods prepend.

Parameters:

  • _format (Symbol) —

    The format

  • _options (Hash) —

    Options hash



257
258
259
 
# File 'lib/lutaml/model/serialize.rb', line 257

def validate_root_mapping!(_format, _options)
  # No-op by default
end

#value_map(options) ⇒ Object 



135
136
137
138
139
140
141
142
143
144
145
146
 
# File 'lib/lutaml/model/serialize.rb', line 135

def value_map(options)
  # Fast path: return default map if no custom options
  return DEFAULT_VALUE_MAP if options.equal?(Type::Value::EMPTY_OPTIONS)
  return DEFAULT_VALUE_MAP if options.empty?

  # Slow path: merge with custom options
  {
    omitted: options[:omitted] || :nil,
    nil: options[:nil] || :nil,
    empty: options[:empty] || :empty,
  }
end

#value_set_for(attribute_name) ⇒ Object 



159
160
161
162
163
164
 
# File 'lib/lutaml/model/serialize.rb', line 159

def value_set_for(attribute_name)
  # Only allocate hash when transitioning from "all defaults" (nil)
  # Hash.new(true) ensures unset keys still return true
  @using_default ||= ::Hash.new(true)
  @using_default[attribute_name] = false
end

#values_set_for(attribute_names) ⇒ Object 



166
167
168
169
 
# File 'lib/lutaml/model/serialize.rb', line 166

def values_set_for(attribute_names)
  @using_default ||= ::Hash.new(true)
  attribute_names.each { |name| @using_default[name] = false }
end