Class: T::Enum

Inherits:
Object
  • Object
show all
Extended by:
Props::CustomType, Sig
Defined in:
lib/types/enum.rb

Overview

Enumerations allow for type-safe declarations of a fixed set of values.

Every value is a singleton instance of the class (i.e. ‘Suit::SPADE.is_a?(Suit) == true`).

Each value has a corresponding serialized value. By default this is the constant’s name converted to lowercase (e.g. ‘Suit::Club.serialize == ’club’‘); however a custom value may be passed to the constructor. Enum will `freeze` the serialized value.

WARNING: Enum instances are singletons that are shared among all their users. Their internals should be kept immutable to avoid unpredictable action at a distance.

Examples:

Declaring an Enum:

class Suit < T::Enum
  enums do
    CLUB = new
    SPADE = new
    DIAMOND = new
    HEART = new
  end
end

Custom serialization value:

class Status < T::Enum
  enums do
    READY = new('rdy')
    ...
  end
end

Accessing values:

Suit::SPADE

Converting from serialized value to enum instance:

Suit.deserialize('club') == Suit::CLUB

Using enums in type signatures:

sig {params(suit: Suit).returns(Boolean)}
def is_red?(suit); ...; end

Constant Summary

Constants included from Helpers

Helpers::Private

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Sig

sig

Methods included from Props::CustomType

checked_serialize, deserialize, included, instance?, scalar_type?, valid?, valid_serialization?

Methods included from Helpers

#abstract!, #final!, #interface!, #mixes_in_class_methods, #requires_ancestor, #sealed!

Constructor Details

#initialize(serialized_val = nil) ⇒ Enum

Returns a new instance of Enum.



256
257
258
259
260
261
262
263
264
265
266
267
268
269
 
# File 'lib/types/enum.rb', line 256

def initialize(serialized_val=nil)
  raise 'T::Enum is abstract' if self.class == T::Enum
  if !self.class.started_initializing?
    raise "Must instantiate all enum values of #{self.class} inside 'enums do'."
  end
  if self.class.fully_initialized?
    raise "Cannot instantiate a new enum value of #{self.class} after it has been initialized."
  end

  serialized_val = serialized_val.frozen? ? serialized_val : serialized_val.dup.freeze
  @serialized_val = T.let(serialized_val, T.nilable(SerializedVal))
  @const_name = T.let(nil, T.nilable(Symbol))
  self.class._register_instance(self)
end

Class Method Details

._load(args) ⇒ Object 



379
380
381
 
# File 'lib/types/enum.rb', line 379

def self._load(args)
  deserialize(Marshal.load(args)) # rubocop:disable Security/MarshalLoad
end

._register_instance(instance) ⇒ Object 



312
313
314
315
 
# File 'lib/types/enum.rb', line 312

def self._register_instance(instance)
  @values ||= []
  @values << T.cast(instance, T.attached_class)
end

.deserialize(mongo_value) ⇒ Object 



130
131
132
133
134
135
 
# File 'lib/types/enum.rb', line 130

def self.deserialize(mongo_value)
  if self == T::Enum
    raise "Cannot call T::Enum.deserialize directly. You must call on a specific child class."
  end
  self.from_serialized(mongo_value)
end

.each_value(&blk) ⇒ Object 



63
64
65
66
67
68
69
 
# File 'lib/types/enum.rb', line 63

def self.each_value(&blk)
  if blk
    values.each(&blk)
  else
    values.each
  end
end

.enums(&blk) ⇒ Object 



320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
 
# File 'lib/types/enum.rb', line 320

def self.enums(&blk)
  raise "enums cannot be defined for T::Enum" if self == T::Enum
  raise "Enum #{self} was already initialized" if fully_initialized?
  raise "Enum #{self} is still initializing" if started_initializing?

  @started_initializing = true

  @values = T.let(nil, T.nilable(T::Array[T.attached_class]))

  yield

  @mapping = T.let(nil, T.nilable(T::Hash[SerializedVal, T.attached_class]))
  @mapping = {}

  # Freeze the Enum class and bind the constant names into each of the instances.
  self.constants(false).each do |const_name|
    instance = self.const_get(const_name, false)
    if !instance.is_a?(self)
      raise "Invalid constant #{self}::#{const_name} on enum. " \
        "All constants defined for an enum must be instances itself (e.g. `Foo = new`)."
    end

    instance._bind_name(const_name)
    serialized = instance.serialize
    if @mapping.include?(serialized)
      raise "Enum values must have unique serializations. Value '#{serialized}' is repeated on #{self}."
    end
    @mapping[serialized] = instance
  end
  @values.freeze
  @mapping.freeze

  orphaned_instances = T.must(@values) - @mapping.values
  if !orphaned_instances.empty?
    raise "Enum values must be assigned to constants: #{orphaned_instances.map {|v| v.instance_variable_get('@serialized_val')}}"
  end

  @fully_initialized = true
end

.from_serialized(serialized_val) ⇒ Object 



92
93
94
95
96
97
98
 
# File 'lib/types/enum.rb', line 92

def self.from_serialized(serialized_val)
  res = try_deserialize(serialized_val)
  if res.nil?
    raise KeyError.new("Enum #{self} key not found: #{serialized_val.inspect}")
  end
  res
end

.fully_initialized? ⇒ Boolean

Returns:



303
304
305
306
307
308
 
# File 'lib/types/enum.rb', line 303

def self.fully_initialized?
  unless defined?(@fully_initialized)
    @fully_initialized = T.let(false, T.nilable(T::Boolean))
  end
  T.must(@fully_initialized)
end

.has_serialized?(serialized_val) ⇒ Boolean

Returns:



103
104
105
106
107
108
109
 
# File 'lib/types/enum.rb', line 103

def self.has_serialized?(serialized_val)
  if @mapping.nil?
    raise "Attempting to access serialization map of #{self.class} before it has been initialized." \
      " Enums are not initialized until the 'enums do' block they are defined in has finished running."
  end
  @mapping.include?(serialized_val)
end

.inherited(child_class) ⇒ Object 



361
362
363
364
365
366
367
368
369
370
 
# File 'lib/types/enum.rb', line 361

def self.inherited(child_class)
  super

  raise "Inheriting from children of T::Enum is prohibited" if self != T::Enum

  # "oj" gem JSON support
  if Object.const_defined?(:Oj)
    Object.const_get(:Oj).register_odd(child_class, child_class, :try_deserialize, :serialize)
  end
end

.serialize(instance) ⇒ Object 



113
114
115
116
117
118
119
120
121
122
123
124
125
126
 
# File 'lib/types/enum.rb', line 113

def self.serialize(instance)
  # This is needed otherwise if a Chalk::ODM::Document with a property of the shape
  # T::Hash[T.nilable(MyEnum), Integer] and a value that looks like {nil => 0} is
  # serialized, we throw the error on L102.
  return nil if instance.nil?

  if self == T::Enum
    raise "Cannot call T::Enum.serialize directly. You must call on a specific child class."
  end
  if instance.class != self
    raise "Cannot call #serialize on a value that is not an instance of #{self}."
  end
  instance.serialize
end

.started_initializing? ⇒ Boolean

Returns:



295
296
297
298
299
300
 
# File 'lib/types/enum.rb', line 295

def self.started_initializing?
  unless defined?(@started_initializing)
    @started_initializing = T.let(false, T.nilable(T::Boolean))
  end
  T.must(@started_initializing)
end

.try_deserialize(serialized_val) ⇒ Object 



76
77
78
79
80
81
82
 
# File 'lib/types/enum.rb', line 76

def self.try_deserialize(serialized_val)
  if @mapping.nil?
    raise "Attempting to access serialization map of #{self.class} before it has been initialized." \
      " Enums are not initialized until the 'enums do' block they are defined in has finished running."
  end
  @mapping[serialized_val]
end

.values ⇒ Object 



52
53
54
55
56
57
58
 
# File 'lib/types/enum.rb', line 52

def self.values
  if @values.nil?
    raise "Attempting to access values of #{self.class} before it has been initialized." \
      " Enums are not initialized until the 'enums do' block they are defined in has finished running."
  end
  @values
end

Instance Method Details

#<=>(other) ⇒ Object 



179
180
181
182
183
184
185
186
 
# File 'lib/types/enum.rb', line 179

def <=>(other)
  case other
  when self.class
    self.serialize <=> other.serialize
  else
    nil
  end
end

#==(other) ⇒ Object 



210
211
212
213
214
215
216
217
218
219
220
221
222
 
# File 'lib/types/enum.rb', line 210

def ==(other)
  case other
  when String
    if T::Configuration.legacy_t_enum_migration_mode?
      comparison_assertion_failed(:==, other)
      self.serialize == other
    else
      false
    end
  else
    super(other)
  end
end

#===(other) ⇒ Object 



225
226
227
228
229
230
231
232
233
234
235
236
237
 
# File 'lib/types/enum.rb', line 225

def ===(other)
  case other
  when String
    if T::Configuration.legacy_t_enum_migration_mode?
      comparison_assertion_failed(:===, other)
      self.serialize == other
    else
      false
    end
  else
    super(other)
  end
end

#_bind_name(const_name) ⇒ Object 



280
281
282
283
284
 
# File 'lib/types/enum.rb', line 280

def _bind_name(const_name)
  @const_name = const_name
  @serialized_val = const_to_serialized_val(const_name) if @serialized_val.nil?
  freeze
end

#_dump(_level) ⇒ Object 



374
375
376
 
# File 'lib/types/enum.rb', line 374

def _dump(_level)
  Marshal.dump(serialize)
end

#as_json(*args) ⇒ Object 



162
163
164
165
166
 
# File 'lib/types/enum.rb', line 162

def as_json(*args)
  serialized_val = serialize
  return serialized_val unless serialized_val.respond_to?(:as_json)
  serialized_val.as_json(*args)
end

#clone ⇒ Object 



145
146
147
 
# File 'lib/types/enum.rb', line 145

def clone
  self
end

#dup ⇒ Object 



140
141
142
 
# File 'lib/types/enum.rb', line 140

def dup
  self
end

#inspect ⇒ Object 



174
175
176
 
# File 'lib/types/enum.rb', line 174

def inspect
  "#<#{self.class.name}::#{@const_name || '__UNINITIALIZED__'}>"
end

#serialize ⇒ Object 



151
152
153
154
 
# File 'lib/types/enum.rb', line 151

def serialize
  assert_bound!
  @serialized_val
end

#to_json(*args) ⇒ Object 



157
158
159
 
# File 'lib/types/enum.rb', line 157

def to_json(*args)
  serialize.to_json(*args)
end

#to_s ⇒ Object 



169
170
171
 
# File 'lib/types/enum.rb', line 169

def to_s
  inspect
end

#to_str ⇒ Object 



196
197
198
199
200
201
202
203
204
205
206
207
 
# File 'lib/types/enum.rb', line 196

def to_str
  msg = 'Implicit conversion of Enum instances to strings is not allowed. Call #serialize instead.'
  if T::Configuration.legacy_t_enum_migration_mode?
    T::Configuration.soft_assert_handler(
      msg,
      storytime: {class: self.class.name},
    )
    serialize.to_s
  else
    raise NoMethodError.new(msg)
  end
end