Module: Lutaml::Model::Utils

Defined in:
lib/lutaml/model/utils.rb

Constant Summary collapse

MISSING =

Fetch sentinel distinguishing absent keys from present-nil values; shared by the deserialization fast paths.

Object.new.freeze
UNINITIALIZED = 
Lutaml::Model::UninitializedClass.instance
CACHE_SIZE_LIMIT =

Cache size limit to prevent memory leaks

1000

Class Method Summary collapse

Class Method Details

.add_accessor_if_not_defined(klass, attribute) ⇒ Object 



236
237
238
239
 
# File 'lib/lutaml/model/utils.rb', line 236

def add_accessor_if_not_defined(klass, attribute)
  add_getter_if_not_defined(klass, attribute)
  add_setter_if_not_defined(klass, attribute)
end

.add_boolean_accessor_if_not_defined(klass, attribute) ⇒ Object 



241
242
243
244
 
# File 'lib/lutaml/model/utils.rb', line 241

def add_boolean_accessor_if_not_defined(klass, attribute)
  add_boolean_getter_if_not_defined(klass, attribute)
  add_setter_if_not_defined(klass, attribute)
end

.add_boolean_getter_if_not_defined(klass, attribute) ⇒ Object 



252
253
254
255
256
 
# File 'lib/lutaml/model/utils.rb', line 252

def add_boolean_getter_if_not_defined(klass, attribute)
  add_method_if_not_defined(klass, "#{attribute}?") do
    !!instance_variable_get(:"@__#{attribute}")
  end
end

.add_getter_if_not_defined(klass, attribute) ⇒ Object 



246
247
248
249
250
 
# File 'lib/lutaml/model/utils.rb', line 246

def add_getter_if_not_defined(klass, attribute)
  add_method_if_not_defined(klass, attribute) do
    instance_variable_get(:"@__#{attribute}")
  end
end

.add_if_present(hash, key, value) ⇒ Object 



150
151
152
 
# File 'lib/lutaml/model/utils.rb', line 150

def add_if_present(hash, key, value)
  hash[key] = value if value
end

.add_method(instance, method_name, &block) ⇒ Object 



199
200
201
202
203
204
205
206
207
 
# File 'lib/lutaml/model/utils.rb', line 199

def add_method(instance, method_name, &block)
  if instance.is_a?(Class)
    instance.class_eval do
      define_method(method_name, &block)
    end
  else
    instance.define_singleton_method(method_name, &block)
  end
end

.add_method_if_not_defined(klass, method_name, &block) ⇒ Object 



228
229
230
231
232
233
234
 
# File 'lib/lutaml/model/utils.rb', line 228

def add_method_if_not_defined(klass, method_name, &block)
  unless klass.method_defined?(method_name)
    klass.class_eval do
      define_method(method_name, &block)
    end
  end
end

.add_setter_if_not_defined(klass, attribute) ⇒ Object 



258
259
260
261
262
 
# File 'lib/lutaml/model/utils.rb', line 258

def add_setter_if_not_defined(klass, attribute)
  add_method_if_not_defined(klass, "#{attribute}=") do |value|
    instance_variable_set(:"@__#{attribute}", value)
  end
end

.add_singleton_method_if_not_defined(instance, method_name, &block) ⇒ Object 



209
210
211
212
213
 
# File 'lib/lutaml/model/utils.rb', line 209

def add_singleton_method_if_not_defined(instance, method_name, &block)
  return if instance.singleton_class.method_defined?(method_name, false)

  instance.define_singleton_method(method_name, &block)
end

.base_class_name(klass) ⇒ Object

Extract the base name of the class



100
101
102
 
# File 'lib/lutaml/model/utils.rb', line 100

def base_class_name(klass)
  klass.to_s.split("::").last
end

.base_class_snake_case(klass) ⇒ Object

Convert the extracted base class to snake case format



105
106
107
 
# File 'lib/lutaml/model/utils.rb', line 105

def base_class_snake_case(klass)
  snake_case(base_class_name(klass))
end

.blank?(value) ⇒ Boolean

Returns:

  • (Boolean) 


127
128
129
130
131
132
133
134
 
# File 'lib/lutaml/model/utils.rb', line 127

def blank?(value)
  # Hot path: the nil test is a pointer compare, and nil dominates
  # in optional-field-heavy documents.
  return true if value.nil?
  return false unless value.is_a?(::String) || value.is_a?(::Array) || value.is_a?(::Hash)

  value.empty?
end

.camel_case(str) ⇒ Object

Convert string to camel case (cached)



38
39
40
41
42
43
44
45
46
47
48
49
50
 
# File 'lib/lutaml/model/utils.rb', line 38

def camel_case(str)
  return "" if str.nil? || str.empty?

  @camel_case_cache ||= {}
  cached = @camel_case_cache[str]
  return cached if cached

  result = str.split("/").map { |part| camelize_part(part) }.join("::")

  # Evict oldest entry if cache is full
  @camel_case_cache.shift if @camel_case_cache.size >= CACHE_SIZE_LIMIT
  @camel_case_cache[str] = result
end

.classify(str) ⇒ Object

Convert string to class name



53
54
55
56
57
58
59
60
61
62
 
# File 'lib/lutaml/model/utils.rb', line 53

def classify(str)
  str = str.to_s.delete(".")
  str = str.sub(/^[a-z\d]*/) { |match| camel_case(match) || match }

  str.gsub("::", "/").gsub(%r{(?:_|-|(/))([a-z\d]*)}i) do
    word = Regexp.last_match(2)
    substituted = camel_case(word) || word
    Regexp.last_match(1) ? "::#{substituted}" : substituted
  end
end

.clear_caches ⇒ Object

Clear all caches (call between schema compilations)



17
18
19
20
 
# File 'lib/lutaml/model/utils.rb', line 17

def clear_caches
  @camel_case_cache = {}
  @snake_case_cache = {}
end

.deep_dup(object) ⇒ Object 



264
265
266
267
268
269
270
271
272
273
 
# File 'lib/lutaml/model/utils.rb', line 264

def deep_dup(object)
  return object if object.nil?
  return object if immutable?(object)

  case object
  when ::Hash then deep_dup_hash(object)
  when Array then deep_dup_array(object)
  else deep_dup_object(object)
  end
end

.empty?(value) ⇒ Boolean

Returns:

  • (Boolean) 


143
144
145
146
147
148
 
# File 'lib/lutaml/model/utils.rb', line 143

def empty?(value)
  case value
  when ::String, ::Array, ::Hash then value.empty?
  else false
  end
end

.empty_collection?(collection) ⇒ Boolean

Returns:

  • (Boolean) 


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

def empty_collection?(collection)
  return false if collection.nil?
  return false unless [::Array, ::Hash].include?(collection.class)

  collection.empty?
end

.fetch_str_or_sym(hash, key, default = nil) ⇒ Object

Fetch the value from the hash using the key in string or symbol format

Examples:

hash = { "key" => "value" }
fetch_str_or_sym(hash, "key") # => "value"
fetch_str_or_sym(hash, :key) # => "value"
fetch_str_or_sym(hash, "invalid_key") # => nil

Parameters:

  • hash (Hash) —

    the hash to fetch the value from

  • key (String, Symbol) —

    the key to fetch the value for

Returns:

  • (Object) —

    the value associated with the key



176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
 
# File 'lib/lutaml/model/utils.rb', line 176

def fetch_str_or_sym(hash, key, default = nil)
  case key
  when String
    if hash.key?(key)
      hash[key]
    else
      (hash.key?(key.to_sym) ? hash[key.to_sym] : default)
    end
  when Symbol
    if hash.key?(key)
      hash[key]
    else
      (hash.key?(key.to_s) ? hash[key.to_s] : default)
    end
  else
    if hash.key?(key.to_s)
      hash[key.to_s]
    else
      (hash.key?(key.to_sym) ? hash[key.to_sym] : default)
    end
  end
end

.immutable?(object) ⇒ Boolean

Check if object is immutable and should not be duplicated

Returns:

  • (Boolean) 


276
277
278
279
280
281
282
283
284
285
286
 
# File 'lib/lutaml/model/utils.rb', line 276

def immutable?(object)
  object.is_a?(Symbol) ||
    object.is_a?(TrueClass) ||
    object.is_a?(FalseClass) ||
    object.is_a?(Numeric) ||
    object.is_a?(Class) ||
    object.is_a?(Module) ||
    object.is_a?(Proc) ||
    object.is_a?(Method) ||
    (object.is_a?(Range) && immutable_range?(object))
end

.immutable_range?(range) ⇒ Boolean

Check if Range has immutable bounds

Returns:

  • (Boolean) 


289
290
291
 
# File 'lib/lutaml/model/utils.rb', line 289

def immutable_range?(range)
  immutable?(range.begin) && (range.end.nil? || immutable?(range.end))
end

.initialized?(value) ⇒ Boolean

Returns:

  • (Boolean) 


115
116
117
 
# File 'lib/lutaml/model/utils.rb', line 115

def initialized?(value)
  !value.equal?(UNINITIALIZED)
end

.last_of_split(field) ⇒ Object

Return the final segment of a prefix:local style qualified name, e.g. "xs:string" -> "string". Returns nil for nil input.



111
112
113
 
# File 'lib/lutaml/model/utils.rb', line 111

def last_of_split(field)
  field&.split(":")&.last
end

.pluralize(str) ⇒ Object

Simple English pluralization for method names. Handles common cases; not a full inflector.



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

def pluralize(str)
  str = str.to_s
  return str if str.empty?

  if str.end_with?("s", "x", "z", "ch", "sh")
    "#{str}es"
  elsif str.end_with?("y") && str.length > 1 && !%w[a e i o
                                                    u].include?(str[-2])
    "#{str[0..-2]}ies"
  else
    "#{str}s"
  end
end

.present?(value) ⇒ Boolean

Returns:

  • (Boolean) 


123
124
125
 
# File 'lib/lutaml/model/utils.rb', line 123

def present?(value)
  !blank?(value)
end

.resolve_child_register(child_class, parent_register) ⇒ Symbol?

Deprecated.

Use Register.resolve_for_child instead. This method will be removed in a future version.

Determines the appropriate register for a child model during deserialization.

Parameters:

  • child_class (Class) —

    The child model class

  • parent_register (Symbol, nil) —

    The parent's register/context ID

Returns:

  • (Symbol, nil) —

    The register ID to use for the child



223
224
225
226
 
# File 'lib/lutaml/model/utils.rb', line 223

def resolve_child_register(child_class, parent_register)
  Lutaml::Model::Register.resolve_for_child(child_class,
                                            parent_register)
end

.safe_load(file, constant) ⇒ Boolean

Safely attempts to require a file and check for a constant

Parameters:

  • file (String) —

    the file to require

  • constant (Symbol) —

    the constant name to check for

Returns:

  • (Boolean) —

    true if the constant is defined, false otherwise



27
28
29
30
31
32
33
34
35
 
# File 'lib/lutaml/model/utils.rb', line 27

def safe_load(file, constant)
  return true if Object.const_defined?(constant)

  require file

  Object.const_defined?(constant)
rescue LoadError
  false
end

.snake_case(str) ⇒ Object

Convert string to snake case (cached)



65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
 
# File 'lib/lutaml/model/utils.rb', line 65

def snake_case(str)
  str = str.to_s.tr(".", "_")
  return str unless /[A-Z-]|::/.match?(str)

  @snake_case_cache ||= {}
  cached = @snake_case_cache[str]
  return cached if cached

  result = str.gsub("::", "/")
    .gsub(/([A-Z][A-Z]*)(?=[A-Z][a-z])|([a-z\d])(?=[A-Z])/) { "#{$1 || $2}_" }
    .tr("-", "_")
    .downcase

  # Evict oldest entry if cache is full
  @snake_case_cache.shift if @snake_case_cache.size >= CACHE_SIZE_LIMIT
  @snake_case_cache[str] = result
end

.string_or_symbol_key?(hash, key) ⇒ Boolean

Check if the hash contains the given key in string or symbol format

Examples:

hash = { "key" => "value" }
string_or_symbol_key?(hash, "key") # => true
string_or_symbol_key?(hash, :key) # => true
string_or_symbol_key?(hash, "invalid_key") # => false

Parameters:

  • hash (Hash) —

    the hash to check

  • key (String, Symbol) —

    the key to check

Returns:

  • (Boolean) —

    true if the hash contains the key, false otherwise



163
164
165
 
# File 'lib/lutaml/model/utils.rb', line 163

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

.uninitialized?(value) ⇒ Boolean

Returns:

  • (Boolean) 


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

def uninitialized?(value)
  value.equal?(UNINITIALIZED)
end