Module: ActiveRecord::Enum

Included in:
Base
Defined in:
activerecord/lib/active_record/enum.rb

Overview

Declare an enum attribute where the values map to integers in the database, but can be queried by name. Example:

class Conversation < ActiveRecord::Base
  enum status: [ :active, :archived ]
end

# conversation.update! status: 0
conversation.active!
conversation.active? # => true
conversation.status  # => "active"

# conversation.update! status: 1
conversation.archived!
conversation.archived? # => true
conversation.status    # => "archived"

# conversation.update! status: 1
conversation.status = "archived"

# conversation.update! status: nil
conversation.status = nil
conversation.status.nil? # => true
conversation.status      # => nil

Scopes based on the allowed values of the enum field will be provided as well. With the above example, it will create an active and archived scope.

You can set the default value from the database declaration, like:

create_table :conversations do |t|
  t.column :status, :integer, default: 0
end

Good practice is to let the first declared status be the default.

Finally, it’s also possible to explicitly map the relation between attribute and database integer with a Hash:

class Conversation < ActiveRecord::Base
  enum status: { active: 0, archived: 1 }
end

Note that when an Array is used, the implicit mapping from the values to database integers is derived from the order the values appear in the array. In the example, :active is mapped to 0 as it’s the first element, and :archived is mapped to 1. In general, the i-th element is mapped to i-1 in the database.

Therefore, once a value is added to the enum array, its position in the array must be maintained, and new values should only be added to the end of the array. To remove unused values, the explicit Hash syntax should be used.

In rare circumstances you might need to access the mapping directly. The mappings are exposed through a class method with the pluralized attribute name:

Conversation.statuses # => { "active" => 0, "archived" => 1 }

Use that class method when you need to know the ordinal value of an enum:

Conversation.where("status <> ?", Conversation.statuses[:archived])

Where conditions on an enum attribute must use the ordinal value of an enum.

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.extended(base) ⇒ Object

:nodoc:



70
71
72
73
 
# File 'activerecord/lib/active_record/enum.rb', line 70

def self.extended(base) # :nodoc:
  base.class_attribute(:defined_enums)
  base.defined_enums = {}
end

Instance Method Details

#enum(definitions) ⇒ Object 



80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
 
# File 'activerecord/lib/active_record/enum.rb', line 80

def enum(definitions)
  klass = self
  definitions.each do |name, values|
    # statuses = { }
    enum_values = ActiveSupport::HashWithIndifferentAccess.new
    name        = name.to_sym

    # def self.statuses statuses end
    detect_enum_conflict!(name, name.to_s.pluralize, true)
    klass.singleton_class.send(:define_method, name.to_s.pluralize) { enum_values }

    _enum_methods_module.module_eval do
      # def status=(value) self[:status] = statuses[value] end
      klass.send(:detect_enum_conflict!, name, "#{name}=")
      define_method("#{name}=") { |value|
        if enum_values.has_key?(value) || value.blank?
          self[name] = enum_values[value]
        elsif enum_values.has_value?(value)
          # Assigning a value directly is not a end-user feature, hence it's not documented.
          # This is used internally to make building objects from the generated scopes work
          # as expected, i.e. +Conversation.archived.build.archived?+ should be true.
          self[name] = value
        else
          raise ArgumentError, "'#{value}' is not a valid #{name}"
        end
      }

      # def status() statuses.key self[:status] end
      klass.send(:detect_enum_conflict!, name, name)
      define_method(name) { enum_values.key self[name] }

      # def status_before_type_cast() statuses.key self[:status] end
      klass.send(:detect_enum_conflict!, name, "#{name}_before_type_cast")
      define_method("#{name}_before_type_cast") { enum_values.key self[name] }

      pairs = values.respond_to?(:each_pair) ? values.each_pair : values.each_with_index
      pairs.each do |value, i|
        enum_values[value] = i

        # def active?() status == 0 end
        klass.send(:detect_enum_conflict!, name, "#{value}?")
        define_method("#{value}?") { self[name] == i }

        # def active!() update! status: :active end
        klass.send(:detect_enum_conflict!, name, "#{value}!")
        define_method("#{value}!") { update! name => value }

        # scope :active, -> { where status: 0 }
        klass.send(:detect_enum_conflict!, name, value, true)
        klass.scope value, -> { klass.where name => i }
      end
    end
    defined_enums[name.to_s] = enum_values
  end
end

#inherited(base) ⇒ Object

:nodoc:



75
76
77
78
 
# File 'activerecord/lib/active_record/enum.rb', line 75

def inherited(base) # :nodoc:
  base.defined_enums = defined_enums.deep_dup
  super
end