EnumerateIt

EnumerateIt can be used in any Ruby class.

For ActiveRecord models, use the has_enumeration_for macro directly.

For non-ActiveRecord classes, you must extend EnumerateIt and provide an attr_accessor for the attribute before calling has_enumeration_for.

If the enumeration class name is different from the attribute name, use the with: option to specify the class.

# ActiveRecord instance
class Person < ApplicationRecord
  has_enumeration_for :relationship_status
end

# Non-ActiveRecord instance
class Person
  extend EnumerateIt
  attr_accessor :relationship_status

  has_enumeration_for :relationship_status
end

# Using a specific enumeration class
class Person < ApplicationRecord
  has_enumeration_for :relationship_status, with: RelationshipStatus
end

You can install the gem directly via the command line or by adding it to your Gemfile for Rails projects.

gem install enumerate_it

Or in your Gemfile:

gem 'enumerate_it'

If you are working with a legacy database where enumeration values are stored as integers (e.g., in a lookup table), you can map the symbols to these specific values using associate_values in your enumeration class.

You can also use sort_by :value to control the sorting order based on these mapped values.

class RelationshipStatus < EnumerateIt::Base
  associate_values(
    single:   1,
    married:  2,
    divorced: 3
  )
end

# RelationshipStatus::MARRIED will return 2

EnumerateIt provides a Rails generator to create both an enumeration class and its corresponding locale file automatically. Use the --help flag to see all available options.

rails generate enumerate_it:enum --help

EnumerateIt supports I18n for the _humanize method and the Enumeration#to_a method.

Translations should be placed under the enumerations.<enumeration_name>.<key> path in your locale files.

For namespaced enumerations (e.g., Design::Color), use the following structure in your YAML:

enumerations:
  "design/color":
    blue: Azul

# pt-BR locale
pt-BR:
  enumerations:
    relationship_status:
      married: Casado

# Usage
p.relationship_status_humanize # => 'Casado'
RelationshipStatus.t(RelationshipStatus::MARRIED) # => 'Casado'

The translate method automatically looks for translations in the I18n library using a specific path pattern: enumerations.[class_name_underscored].[key_name_underscored]

If no translation is found, it falls back to a humanized version of the symbol (e.g., :pending_review becomes Pending Review).

# Example I18n YAML structure:
# en:
#   enumerations:
#     status:
#       pending: "Waiting for approval"
#       active: "Currently running"

EnumerateIt automatically integrates with ActiveRecord::Base when Rails is loaded. By extending ActiveRecord::Base, the module makes enumeration capabilities available to all your models. This allows you to define enumerations directly within your ActiveRecord classes.

# No manual setup required if using Rails/ActiveRecord;
# EnumerateIt hooks into ActiveSupport.on_load(:active_record)
# to extend ActiveRecord::Base automatically.

You can add custom logic and helper methods to your enumeration classes using the custom_helpers block. This allows you to encapsulate domain logic related to the enumeration values within the enumeration class itself.

class RelationshipStatus < EnumerateIt::Base
  associate_values :single, :married, :divorced

  custom_helpers do
    def ever_married?(value)
      [MARRIED, DIVORCED].include?(value)
    end
  end
end

By default, methods like to_a, to_json, and list return values in the order they were passed to associate_values. You can change this behavior using the sort_by class method.

class RelationshipStatus < EnumerateIt::Base
  associate_values :single, :married

  sort_by :translation
end

You can define custom logic within an enumeration class using a custom_helpers block. These methods become class methods on the enumeration class and, if create_helpers: true is used in the model, they also become instance methods on the model.

If prefix: true is used in the model, the custom helpers will also be prefixed.

class RelationshipStatus < EnumerateIt::Base
  associate_values :single, :married, :divorced

  custom_helpers do
    def ever_married?(value)
      [MARRIED, DIVORCED].include?(value)
    end
  end
end

# As class method
RelationshipStatus.ever_married?(RelationshipStatus::MARRIED)

# As model instance method (if create_helpers: true)
person.ever_married?