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

Defined Under Namespace

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

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

#format_element_sequences, #order_names, #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) ⇒ Object 



162
163
164
165
166
167
168
169
170
171
 
# File 'lib/lutaml/model/serialize.rb', line 162

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

Instance Attribute Details

#lutaml_parent ⇒ Object

Returns the value of attribute lutaml_parent.



86
87
88
 
# File 'lib/lutaml/model/serialize.rb', line 86

def lutaml_parent
  @lutaml_parent
end

#lutaml_register ⇒ Object

Returns the value of attribute lutaml_register.



86
87
88
 
# File 'lib/lutaml/model/serialize.rb', line 86

def lutaml_register
  @lutaml_register
end

#lutaml_root ⇒ Object

Returns the value of attribute lutaml_root.



86
87
88
 
# File 'lib/lutaml/model/serialize.rb', line 86

def lutaml_root
  @lutaml_root
end

Class Method Details

.included(base) ⇒ Object 



36
37
38
39
 
# File 'lib/lutaml/model/serialize.rb', line 36

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

.register_format_mapping_method(format) ⇒ Object 



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

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 



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

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 



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

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 



137
138
139
140
141
 
# File 'lib/lutaml/model/serialize.rb', line 137

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) 


178
179
180
181
182
 
# File 'lib/lutaml/model/serialize.rb', line 178

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

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

#extract_register_id(attrs, options) ⇒ Object 



119
120
121
122
 
# File 'lib/lutaml/model/serialize.rb', line 119

def extract_register_id(attrs, options)
  register = attrs&.dig(:lutaml_register) || options&.dig(:register)
  self.class.extract_register_id(register)
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.



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

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 



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

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) 


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

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

#key_value(hash, key) ⇒ Object 



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

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)



230
231
232
 
# File 'lib/lutaml/model/serialize.rb', line 230

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

#pretty_print_instance_variables ⇒ Object 



200
201
202
203
204
205
 
# File 'lib/lutaml/model/serialize.rb', line 200

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

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

Returns:

  • (Boolean) 


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

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 



211
212
213
214
215
216
217
218
219
220
221
222
223
 
# File 'lib/lutaml/model/serialize.rb', line 211

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 



207
208
209
 
# File 'lib/lutaml/model/serialize.rb', line 207

def to_yaml_hash
  self.class.as_yaml(self)
end

#using_default?(attribute_name) ⇒ Boolean

Returns:

  • (Boolean) 


155
156
157
158
159
160
 
# File 'lib/lutaml/model/serialize.rb', line 155

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 



143
144
145
146
 
# File 'lib/lutaml/model/serialize.rb', line 143

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

#validate_attribute!(attr_name) ⇒ Object 



184
185
186
187
188
189
190
 
# File 'lib/lutaml/model/serialize.rb', line 184

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



239
240
241
 
# File 'lib/lutaml/model/serialize.rb', line 239

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

#value_map(options) ⇒ Object 



124
125
126
127
128
129
130
131
132
133
134
135
 
# File 'lib/lutaml/model/serialize.rb', line 124

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 



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

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