модуль ActiveRecord::Enum

Объявляет атрибут перечисления, где значения сопоставляются с целыми числами в базе данных, но могут быть запрошены по имени. Пример:

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

Также будут предоставлены области, основанные на разрешённых значениях поля перечисления. Приведённом примере:

Conversation.active
Conversation.not_active
Conversation.archived
Conversation.not_archived

Конечно, вы также можете запросить их напрямую, если области вам не подойдут:

Conversation.where(status: [:active, :archived])
Conversation.where.not(status: :active)

Определение областей можно отключить, установив :scopes на false.

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

Вы можете установить значение перечисления по умолчанию, установив :default, например:

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

conversation = Conversation.new
conversation.status # => "active"

Возможна явная привязка связи между атрибутом и целочисленным значением базы данных с помощью хэша:

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

Наконец, также можно использовать строковый столбец для сохранения значения перечисления. Обратите внимание, что это, вероятно, приведёт к более медленным запросам к базе данных:

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

Обратите внимание, что при использовании массива неявное сопоставление значений с целочисленными значениями базы данных определяется порядком появления значений в массиве. В примере :active сопоставляется с 0, поскольку это первый элемент, а :archived сопоставляется с 1. В общем случае i-й элемент сопоставляется с i-1 в базе данных.

Поэтому после добавления значения в массив перечисления его положение в массиве необходимо сохранить, а новые значения следует добавлять только в конец массива. Чтобы удалить неиспользуемые значения, необходимо использовать явную синтаксическую конструкцию с хэшем.

В редких случаях вам может потребоваться получить доступ к сопоставлению напрямую. Сопоставления представлены через метод класса с множественным числом имени атрибута, который возвращает сопоставление в формате ActiveSupport::HashWithIndifferentAccess:

Conversation.statuses[:active]    # => 0
Conversation.statuses["archived"] # => 1

Используйте этот метод класса, когда вам нужно узнать порядковое значение перечисления. Например, это может понадобиться при ручном составлении SQL-строк:

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

Вы можете использовать опции :prefix или :suffix, когда вам нужно определить несколько перечислений с одинаковыми значениями. Если переданное значение равно true, методы будут иметь префикс/суффикс с именем перечисления. Также возможно передать пользовательское значение:

class Conversation < ActiveRecord::Base
  enum :status, [ :active, :archived ], suffix: true
  enum :comments_status, [ :active, :inactive ], prefix: :comments
end

В приведённом примере методы с восклицательным знаком и предикатные методы, а также связанные с ними области, теперь имеют соответствующие префиксы и/или суффиксы:

conversation.active_status!
conversation.archived_status? # => false

conversation.comments_inactive!
conversation.comments_active? # => false

Если вы хотите отключить автоматически генерируемые методы в модели, вы можете сделать это, установив опцию :instance_methods в значение false:

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

Если вы хотите, чтобы значение перечисления проверялось перед сохранением, используйте опцию :validate:

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

conversation = Conversation.new

conversation.status = :unknown
conversation.valid? # => false

conversation.status = nil
conversation.valid? # => false

conversation.status = :active
conversation.valid? # => true

Также возможно передать дополнительные параметры валидации:

class Conversation < ActiveRecord::Base
  enum :status, [ :active, :archived ], validate: { allow_nil: true }
end

conversation = Conversation.new

conversation.status = :unknown
conversation.valid? # => false

conversation.status = nil
conversation.valid? # => true

conversation.status = :active
conversation.valid? # => true

В противном случае ArgumentError вызовет ошибку:

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

conversation = Conversation.new

conversation.status = :unknown # 'unknown' is not a valid status (ArgumentError)