module ActiveRecord::Enum
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.status = 1 conversation.status = "archived" 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:
Conversation.active Conversation.not_active Conversation.archived Conversation.not_archived
Of course, you can also query them directly if the scopes don't fit your needs:
Conversation.where(status: [:active, :archived]) Conversation.where.not(status: :active)
Defining scopes can be disabled by setting :_scopes
to false
.
class Conversation < ActiveRecord::Base enum status: [ :active, :archived ], _scopes: false end
You can set the default enum value by setting :_default
, like:
class Conversation < ActiveRecord::Base enum status: [ :active, :archived ], _default: "active" end conversation = Conversation.new conversation.status # => "active"
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, which return the mapping in a HashWithIndifferentAccess
:
Conversation.statuses[:active] # => 0 Conversation.statuses["archived"] # => 1
Use that class method when you need to know the ordinal value of an enum. For example, you can use that when manually building SQL strings:
Conversation.where("status <> ?", Conversation.statuses[:archived])
You can use the :_prefix
or :_suffix
options when you need to define multiple enums with same values. If the passed value is true
, the methods are prefixed/suffixed with the name of the enum. It is also possible to supply a custom value:
class Conversation < ActiveRecord::Base enum status: [:active, :archived], _suffix: true enum comments_status: [:active, :inactive], _prefix: :comments end
With the above example, the bang and predicate methods along with the associated scopes are now prefixed and/or suffixed accordingly:
conversation.active_status! conversation.archived_status? # => false conversation.comments_inactive! conversation.comments_active? # => false
Constants
- ENUM_CONFLICT_MESSAGE
Public Instance Methods
# File lib/active_record/enum.rb, line 158 def enum(definitions) enum_prefix = definitions.delete(:_prefix) enum_suffix = definitions.delete(:_suffix) enum_scopes = definitions.delete(:_scopes) default = {} default[:default] = definitions.delete(:_default) if definitions.key?(:_default) definitions.each do |name, values| assert_valid_enum_definition_values(values) # statuses = { } enum_values = ActiveSupport::HashWithIndifferentAccess.new name = name.to_s # def self.statuses() statuses end detect_enum_conflict!(name, name.pluralize, true) singleton_class.define_method(name.pluralize) { enum_values } defined_enums[name] = enum_values detect_enum_conflict!(name, name) detect_enum_conflict!(name, "#{name}=") attr = attribute_alias?(name) ? attribute_alias(name) : name decorate_attribute_type(attr, **default) do |subtype| EnumType.new(attr, enum_values, subtype) end value_method_names = [] _enum_methods_module.module_eval do prefix = if enum_prefix == true "#{name}_" elsif enum_prefix "#{enum_prefix}_" end suffix = if enum_suffix == true "_#{name}" elsif enum_suffix "_#{enum_suffix}" end pairs = values.respond_to?(:each_pair) ? values.each_pair : values.each_with_index pairs.each do |label, value| enum_values[label] = value label = label.to_s value_method_name = "#{prefix}#{label}#{suffix}" value_method_names << value_method_name define_enum_methods(name, value_method_name, value, enum_scopes) method_friendly_label = label.gsub(/[\W&&[:ascii:]]+/, "_") value_method_alias = "#{prefix}#{method_friendly_label}#{suffix}" if value_method_alias != value_method_name && !value_method_names.include?(value_method_alias) value_method_names << value_method_alias define_enum_methods(name, value_method_alias, value, enum_scopes) end end end detect_negative_enum_conditions!(value_method_names) if enum_scopes != false enum_values.freeze end end
Private Instance Methods
# File lib/active_record/enum.rb, line 254 def _enum_methods_module @_enum_methods_module ||= begin mod = EnumMethods.new(self) include mod mod end end
# File lib/active_record/enum.rb, line 262 def assert_valid_enum_definition_values(values) unless values.is_a?(Hash) || values.all? { |v| v.is_a?(Symbol) } || values.all? { |v| v.is_a?(String) } error_message = <<~MSG Enum values #{values} must be either a hash, an array of symbols, or an array of strings. MSG raise ArgumentError, error_message end if values.is_a?(Hash) && values.keys.any?(&:blank?) || values.is_a?(Array) && values.any?(&:blank?) raise ArgumentError, "Enum label name must not be blank." end end
# File lib/active_record/enum.rb, line 281 def detect_enum_conflict!(enum_name, method_name, klass_method = false) if klass_method && dangerous_class_method?(method_name) raise_conflict_error(enum_name, method_name, type: "class") elsif klass_method && method_defined_within?(method_name, Relation) raise_conflict_error(enum_name, method_name, type: "class", source: Relation.name) elsif !klass_method && dangerous_attribute_method?(method_name) raise_conflict_error(enum_name, method_name) elsif !klass_method && method_defined_within?(method_name, _enum_methods_module, Module) raise_conflict_error(enum_name, method_name, source: "another enum") end end
# File lib/active_record/enum.rb, line 303 def detect_negative_enum_conditions!(method_names) return unless logger method_names.select { |m| m.start_with?("not_") }.each do |potential_not| inverted_form = potential_not.sub("not_", "") if method_names.include?(inverted_form) logger.warn "Enum element '#{potential_not}' in #{self.name} uses the prefix 'not_'." \ " This has caused a conflict with auto generated negative scopes." \ " Avoid using enum elements starting with 'not' where the positive form is also an element." end end end
# File lib/active_record/enum.rb, line 293 def raise_conflict_error(enum_name, method_name, type: "instance", source: "Active Record") raise ArgumentError, ENUM_CONFLICT_MESSAGE % { enum: enum_name, klass: name, type: type, method: method_name, source: source } end