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

Defined Under Namespace

Modules: LegacyMigrationMode

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 = UNSET) ⇒ Enum

Returns a new instance of Enum.



280
281
282
283
284
285
286
287
288
289
290
291
292
293
 
# File 'lib/types/enum.rb', line 280

def initialize(serialized_val=UNSET)
  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 



403
404
405
 
# File 'lib/types/enum.rb', line 403

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

._register_instance(instance) ⇒ Object 



336
337
338
339
 
# File 'lib/types/enum.rb', line 336

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 



344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
 
# File 'lib/types/enum.rb', line 344

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:



327
328
329
330
331
332
 
# File 'lib/types/enum.rb', line 327

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 



385
386
387
388
389
390
391
392
393
394
 
# File 'lib/types/enum.rb', line 385

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:



319
320
321
322
323
324
 
# File 'lib/types/enum.rb', line 319

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

#_bind_name(const_name) ⇒ Object 



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

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

#_dump(_level) ⇒ Object 



398
399
400
 
# File 'lib/types/enum.rb', line 398

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
208
209
210
 
# 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,
        caller_location: Kernel.caller_locations(1..1)&.[](0)&.then {"#{_1.path}:#{_1.lineno}"},
      },
    )
    serialize.to_s
  else
    Kernel.raise NoMethodError.new(msg)
  end
end