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.



249
250
251
252
253
254
255
256
257
258
259
260
261
262
 
# File 'lib/types/enum.rb', line 249

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 



367
368
369
 
# File 'lib/types/enum.rb', line 367

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

._register_instance(instance) ⇒ Object 



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

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 



313
314
315
316
317
318
319
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
 
# File 'lib/types/enum.rb', line 313

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:



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

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 



354
355
356
357
358
 
# File 'lib/types/enum.rb', line 354

def self.inherited(child_class)
  super

  raise "Inheriting from children of T::Enum is prohibited" if self != T::Enum
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:



288
289
290
291
292
293
 
# File 'lib/types/enum.rb', line 288

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 



172
173
174
175
176
177
178
179
 
# File 'lib/types/enum.rb', line 172

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

#==(other) ⇒ Object 



203
204
205
206
207
208
209
210
211
212
213
214
215
 
# File 'lib/types/enum.rb', line 203

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 



218
219
220
221
222
223
224
225
226
227
228
229
230
 
# File 'lib/types/enum.rb', line 218

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 



273
274
275
276
277
 
# File 'lib/types/enum.rb', line 273

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 



362
363
364
 
# File 'lib/types/enum.rb', line 362

def _dump(_level)
  Marshal.dump(serialize)
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 



167
168
169
 
# File 'lib/types/enum.rb', line 167

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 



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

def to_s
  inspect
end

#to_str ⇒ Object 



189
190
191
192
193
194
195
196
197
198
199
200
 
# File 'lib/types/enum.rb', line 189

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