https://github.com/albertosaurus/power_enum_2
Enumerations for Rails Done Right.
- PowerEnum 5.0.X (this version) supports Rails 7.X
- PowerEnum 4.0.X supports Rails 6.X, and Rails 7.0 (Experimental)
- PowerEnum 3.X supports Rails 4.2, Rails 5.X and Rails 6.0
- PowerEnum 2.X supports Rails 4.X and Rails 5.0
- PowerEnum 1.X supports Rails 3.1/3.2, available here: https://github.com/albertosaurus/power_enum
Power Enum allows you to treat instances of your ActiveRecord models as though they were an enumeration of values. It allows you to cleanly solve many of the problems that the traditional Rails alternatives handle poorly if at all. It is particularly suitable for scenarios where your Rails application is not the only user of the database, such as when it's used for analytics or reporting.
Power Enum is a fork of the Rails 3 modernization made by the fine folks at Protocool https://github.com/protocool/enumerations_mixin to the original plugin by Trevor Squires. While many of the core ideas remain, it has been reworked and a full test suite written to facilitate further development.
At it's most basic level, it allows you to say things along the lines of:
# Create a provisional booking
booking = Booking.new( status: BookingStatus[:provisional] )
# This also works
booking = Booking.new( status: :provisional )
# Set the booking status to 'confirmed'
booking.status = :confirmed
booking = Booking.create( status: :rejected )
# And now...
booking.status == BookingStatus[:rejected] # evaluates to true
booking.status === :rejected # also evaluates to true
booking.status === [:rejected, :confirmed, :provisional] # and so does this
booking.status === [%i[rejected confirmed provisional]] # and this
Booking.where( :status_id => BookingStatus[:provisional] )
BookingStatus.all.collect { |status|, [status.name, status.id] }
# built in scopes make life easier
Booking.with_status( :provisional, :confirmed )
See "How to use it" below for more information.
- Ruby 2.7 or later (JRuby should work but isn't extensively tested).
- Rails 6.0, 6.1, 6.2, 7.0
- Ruby 2.1 or later (JRuby should work but isn't extensively tested).
- Rails 4.2, 5.0, 5.1, 5.2, 6.0
- Ruby 1.9.3, 2.0, JRuby 1.7+ (Ruby 1.9.3 or 2.0 required for development)
- Rails 4.0, 4.1, 4.2, 5.0
Add the gem to your Gemfile
gem 'power_enum'
then run
bundle install
gem install power_enum
This package adds:
- Two mixins and a helper to ActiveRecord
- Methods to migrations to simplify the creation of backing tables
- Two generators to streamline working with enums
- Custom RSpec matchers to streamline the testing of enums and enumerated attributes
acts_as_enumerated
provides capabilities to treat your model and its records as an enumeration.
At a minimum, the database table for an acts_as_enumerated must contain an 'id' column and a column
to hold the value of the enum ('name' by default). It is strongly recommended that there be
a NOT NULL constraint on the 'name' column. All instances for the acts_as_enumerated
model
are cached in memory. If the table has an 'active' column, the value of that attribute
will be used to determine which enum instances are active.
Otherwise, all values are considered active.
has_enumerated
adds methods to your ActiveRecord model for setting and retrieving enumerated values using an
associated acts_as_enumerated model.
There is also an ActiveRecord::VirtualEnumerations
helper module to create 'virtual' acts_as_enumerated models
which helps to avoid cluttering up your models directory with acts_as_enumerated classes.
In the following example, we'll look at a Booking that can have several types of statuses, encapsulated by BookingStatus enums.
Invoke the generator to create a basic enum:
rails generate enum booking_status
You should see output similar to this:
create app/models/booking_status.rb
create db/migrate/20110926012928_create_power_enum_booking_status.rb
invoke test_unit
create test/unit/booking_status_test.rb
That's all you need to get started. In many cases, no further work on the enum is necessary. You can run rails generate enum --help
to see a description of the generator options. Notice, that while a unit test is generated by default, a fixture isn't. That is because
fixtures are not an ideal way to test acts_as_enumerated models. I generally prefer having a hook to seed the database from seeds.rb
from a pre-test Rake task.
When you open your migration file, it will look something like this:
class CreateEnumBookingStatus < ActiveRecord::Migration
def change
create_power_enum :booking_status
end
end
You can now customize it.
create_power_enum :booking_status, :name_limit => 50
# The above is equivalent to saying
# create_table :booking_statuses do |t|
# t.string :name, :limit => 50, :null => false
# end
Now, when you create your Booking model, your migration should create a reference column for status id's and a foreign key relationship to the booking_statuses table.
create_table :bookings do |t|
t.integer :status_id
t.timestamps
end
# It's highly recommended to add a foreign key constraint here.
# Ideally, you would use a gem of some sort to handle this for Rails < 6.
# I have been using PgPower https://rubygems.org/gems/pg_power with much
# success. It's fork, PgSaurus https://rubygems.org/gems/pg_saurus should
# work just as well.
execute "ALTER TABLE bookings ADD 'bookings_bookings_status_id_fk'"\
" FOREIGN KEY (status_id) REFERENCES booking_statuses (id);"
It's easier to use the references
method if you intend to stick to the default naming convention for reference columns.
create_table :bookings do |t|
t.references :booking_status # Same as t.integer booking_status_id
t.timestamps
end
There are two methods added to Rails migrations:
Creates a new enum table. enum_name
will be automatically pluralized. The following options are supported:
- [:name_column] Specify the column name for name of the enum. By default it's :name. This can be a String or a Symbol
- [:description] Set this to
true
to have a 'description' column generated. - [:name_limit] Set this define the limit of the name column.
- [:desc_limit] Set this to define the limit of the description column
- [:active] Set this to
true
to have a boolean 'active' column generated. The 'active' column will have the options of NOT NULL and DEFAULT TRUE. - [:timestamps] Set this to
true
to have the timestamp columns (created_at and updated_at) generated - [:table_options] Allows you to set a hash which will be passed directly to
create_table
. - [:schema] Allows you to create the enum table in a different schema (Version 2.6.0).
You can also pass in a block that takes a table object as an argument, like create_table
.
Example:
create_power_enum :booking_status
is the equivalent of
create_table :booking_statuses do |t|
t.string :name, :null => false
end
add_index :booking_statuses, [:name], :unique => true
In a more complex case:
create_power_enum :booking_status,
:name_column => :booking_name,
:name_limit => 50,
:description => true,
:desc_limit => 100,
:active => true,
:timestamps => true,
:table_options => {:primary_key => :foo}
is the equivalent of
create_table :booking_statuses, :primary_key => :foo do |t|
t.string :booking_name, :limit => 50, :null => false
t.string :description, :limit => 100
t.boolean :active, :null => false, :default => true
t.timestamps
end
add_index :booking_statuses, [:booking_name], :unique => true
You can also customize the creation process by using a block:
create_power_enum :booking_status do |t|
t.boolean :first_booking, :null => false
end
is the equivalent of
create_table :booking_statuses do |t|
t.string :name, :null => false
t.boolean :first_booking, :null => false
end
add_index :booking_statuses, [:name], :unique => true
Notice that a unique index is automatically created on the specified name column.
Drops the enum table. enum_name
will be automatically pluralized.
Example:
remove_power_enum :booking_status
is the equivalent of
drop_table :booking_statuses
class BookingStatus < ActiveRecord::Base
acts_as_enumerated :conditions => 'optional_sql_conditions',
:order => 'optional_sql_order_by',
:on_lookup_failure => :optional_class_method, # This also works: lambda{ |arg| some_custom_action }
:name_column => 'optional_name_column' # If required, may override the default name column
:alias_name => false, # If set to false and have name_column set, will not
# alias :name to the name column attribute.
:freeze_members => true # Optional, default is true in prod.
# This also works: lambda { true }
end
With that, your BookingStatus class will have the following methods defined:
BookingStatus[arg]
performs a lookup for the BookingStatus instance for the given arg. The arg value can be a
'string' or a :symbol, in which case the lookup will be against the BookingStatus.name field. Alternatively arg can be
a Integer, in which case the lookup will be against the BookingStatus.id field. It returns the arg if arg is an
instance of the enum (in this case BookingStatus) as a convenience.
The :on_lookup_failure
option specifies the name of a class method to invoke when the []
method is unable to
locate a BookingStatus record for arg. The default is the built-in :enforce_none
which returns nil. There are also
built-ins for :enforce_strict
(raise and exception regardless of the type for arg), :enforce_strict_literals
(raises
an exception if the arg is a Integer or Symbol), :enforce_strict_ids
(raises and exception if the arg is a Integer) and
:enforce_strict_symbols
(raises an exception if the arg is a Symbol).
The purpose of the :on_lookup_failure
option is that a) under some circumstances a lookup failure is a Bad Thing and
action should be taken, therefore b) a fallback action should be easily configurable. You can
also set :on_lookup_failure
to a lambda that takes in a single argument (The arg that was passed to []
).
You can also pass in multiple arguments to []
. This returns a list of enums corresponding to the
passed in values. Duplicates are filtered out. For example BookingStatus[arg1, arg2, arg3]
would be equivalent to
[BookingStatus[arg1], BookingStatus[arg2], BookingStatus[arg3]]
.
BookingStatus.contains?(arg)
returns true if
the given Symbol, String or id has a member instance in the enumeration,
false
otherwise. Returns true
if the argument is an enum instance, returns false
if the argument is nil
or any
other value.
BookingStatus.all
returns an array of all BookingStatus records that match the :conditions
specified in
acts_as_enumerated
, in the order specified by :order
.
BookingStatus.all_except(arg1, arg2)
returns an array of all BookingStatus records with the given items filtered out.
BookingStatus.active
returns an array of all BookingStatus records that are marked active. See the active?
instance
method.
BookingStatus.inactive
returns an array of all BookingStatus records that are inactive. See the inactive?
instance
method.
BookingStatus.names
will return all the names of the defined enums as an array of symbols.
The preferred mechanism to update an enumerations model in migrations and similar. Pass in a block to this method to to perform any updates.
Example:
BookingStatus.update_enumerations_model do
BookingStatus.create :name => 'Foo',
:description => 'Bar',
:active => false
end
Example 2:
BookingStatus.update_enumerations_model do |klass|
klass.create :name => 'Foo',
:description => 'Bar',
:active => false
end
Returns true
for ActiveRecord models that act as enumerated, false
for others. So
BookingStatus.acts_as_enumerated?
would return true
, while Booking.acts_as_enumerated?
would return false
.
Each enumeration model gets the following instance methods.
Behavior depends on the type of arg
.
- If
arg
isnil
, returnsfalse
. - If
arg
is an instance ofSymbol
,Integer
orString
, returns the result ofBookingStatus[:foo] == BookingStatus[arg]
. - If
arg
is anArray
, returnstrue
if any member of the array returnstrue
for===(arg)
,false
otherwise. - In all other cases, delegates to
===(arg)
of the superclass.
Examples:
BookingStatus[:foo] === :foo #Returns true
BookingStatus[:foo] === 'foo' #Returns true
BookingStatus[:foo] === :bar #Returns false
BookingStatus[:foo] === [:foo, :bar, :baz] #Returns true
BookingStatus[:foo] === nil #Returns false
You should note that defining an :on_lookup_failure
method that raises an exception will cause ===
to also raise an
exception for any lookup failure of BookingStatus[arg]
.
Aliased to ===
Returns true if any element in the list returns true for ===(arg)
, false otherwise.
Example:
BookingStatus[:foo].in? :foo, :bar, :baz #Returns true
Returns the string representation of the enum, i.e. the value in the :name_column
attribute of the enumeration model.
By default, aliased to the string representation of the :name_column
attribute. To avoid this, set the alias_name
option to false
.
Returns the symbol representation of the name of the enum. BookingStatus[:foo].name_sym
returns :foo.
Aliased to name_sym
.
Returns true if the instance is active, false otherwise. If it has an attribute 'active',
returns the attribute cast to a boolean, otherwise returns true. This method is used by the active
class method to select active enums.
Returns true if the instance is inactive, false otherwise. Default implementations returns !active?
This method is used by the inactive
class method to select inactive enums.
acts_as_enumerated
records are considered immutable. By default you cannot create/alter/destroy instances because they
are cached in memory. Because of Rails' process-based model it is not safe to allow updating acts_as_enumerated
records as the caches will get out of sync. Also, to_s
is overriden to return the name of the enum instance.
However, one instance where updating the models should be allowed is if you are using seeds.rb to seed initial values into the database.
Using the above example you would do the following:
BookingStatus.enumeration_model_updates_permitted = true
['pending', 'confirmed', 'canceled'].each do | status_name |
BookingStatus.create( :name => status_name )
end
Note that a :presence
and :uniqueness
validation is automatically defined on each model for the name column.
First of all, note that you could specify the relationship to an acts_as_enumerated
class using the belongs_to
association. However, has_enumerated
is preferable because you aren't really associated to the enumerated value, you
are aggregating it. As such, the has_enumerated
macro behaves more like an aggregation than an association.
class Booking < ActiveRecord::Base
has_enumerated :status,
:class_name => 'BookingStatus',
:foreign_key => 'status_id',
:on_lookup_failure => :optional_instance_method,
:permit_empty_name => true, #Setting this to true disables automatic conversion of empty strings to nil. Default is false.
:default => :unconfirmed, #Default value of the attribute.
:create_scope => false #Setting this to false disables the automatic creation of the 'with_status' scope.
end
By default, the foreign key is interpreted to be the name of your has_enumerated field (in this case 'booking_status')
plus '_id'. Since we chose to make the column name 'status_id' for the sake of brevity, we must explicitly designate
it. Additionally, the default value for :class_name
is the camelized version of the name for your has_enumerated
field. :on_lookup_failure
is explained below. :permit_empty_name
is an optional flag to disable automatic
conversion of empty strings to nil. It is typically desirable to have booking.update_attributes(:status => '')
assign status_id to a nil rather than raise an Error, as you'll be often calling update_attributes
with form data, but
the choice is yours. Setting a :default
option will generate an after_initialize callback to set a default value on
the attribute unless a non-nil value has already been set.
With that, your Booking class will have the following methods defined:
Returns the BookingStatus with an id that matches the value in the Booking.status_id.
Sets the value for Booking.status_id using the id of the BookingStatus instance passed as an argument. As a short-hand, you can also pass it the 'name' of a BookingStatus instance, either as a 'string' or :symbol, or pass in the id directly.
example:
mybooking.status = :confirmed
this is equivalent to:
mybooking.status = 'confirmed'
or:
mybooking.status = BookingStatus[:confirmed]
The :on_lookup_failure
option in has_enumerated is there because you may want to create an error handler for
situations where the argument passed to status=(arg)
is invalid. By default, an invalid value will cause an
ArgumentError to be raised.
Of course, this may not be optimal in your situation. In this case you can do one of three things:
-
You can set it to 'validation_error'. In this case, the invalid value will be cached and returned on subsequent lookups, but the model will fail validation.
-
Specify an instance method to be called in the case of a lookup failure. The method signature is as follows:
your_lookup_handler(operation, name, name_foreign_key, acts_enumerated_class_name, lookup_value)
The 'operation' arg will be either :read
or :write
. In the case of :read
you are expected to return something or
raise an exception, while in the case of a :write
you don't have to return anything.
Note that there's enough information in the method signature that you can specify one method to handle all lookup failures for all has_enumerated fields if you happen to have more than one defined in your model.
- Give it a lambda function. In that case, the lambda needs to accept the ActiveRecord model as its first argument, with the rest of the arguments being identical to the signature of the lookup handler instance method.
:on_lookup_failure => lambda{ |record, op, attr, fk, cl_name, value|
# handle lookup failure
}
NOTE: A nil
is always considered to be a valid value for status=(arg)
since it's assumed you're trying to null out
the foreign key. The :on_lookup_failure
will be bypassed.
Unless the :create_scope
option is set to false
, a scope is automatically created that takes a list of enums as
arguments. This allows us to say things like:
Booking.with_status :confirmed, :received
Strings, symbols, ids, or enum instances are all valid arguments. For example, the following would be valid, though not recommended for obvious reasons.
Booking.with_status 1, 'confirmed', BookingStatus[:rejected]
As a convenience, it also aliases a pluralized version of the scope, i.e. :with_statuses
By default, a scope for the inverse of with_enumerated_attribute
is created, unless the :create_scope
option is set to false
. As a result, this allows us to do things like
Booking.exclude_status :received
This will give us all the Bookings where the status is a value other than BookingStatus[:received]
.
NOTE: This will NOT pick up instances of Booking where status is nil.
A pluralized version of the scope is also created, so Booking.exclude_statuses :received, :confirmed
is valid.
The following methods are added to ActiveRecord::Base as class methods.
Returns true if the given attr is an enumerated attributes, false otherwise. attr
can be a string or a symbol. This
is a class method.
Returns an array of attributes which are enumerated.
In many instances, your acts_as_enumerated
classes will do nothing more than just act as enumerated. In that case,
you can use ActiveRecord::VirtualEnumerations to reduce that clutter.
Create a custom Rails initializer: Rails.root/config/initializers/virtual_enumerations.rb
To streamline this, a generator is provided:
rails generate virtual_enumerations_initializer
Configure as appropriate.
ActiveRecord::VirtualEnumerations.define do |config|
# Define the enum class
config.define 'ClassName',
:table_name => 'table',
:extends => 'SuperclassName',
:conditions => ['something = ?', "value"],
:order => 'column ASC',
:on_lookup_failure => :enforce_strict,
:name_column => 'name_column',
:alias_name => false {
# This gets evaluated within the class scope of the enum class.
def to_s
"#{id} - #{name}"
end
}
end
Only the 'ClassName' argument is required. :table_name
is used to define a custom table name while the :extends
option is used to set a custom superclass. Class names can be either camel-cased like ClassName or with
underscores, like class_name. Strings and symbols are both fine.
If you need to fine-tune the definition of the enum class, you can optionally pass in a block, which will be evaluated in the context of the enum class.
Example:
config.define :color, :on_lookup_failure => :enforce_strict, do
def to_argb(alpha)
case self.to_sym
when :white
[alpha, 255, 255, 255]
when :red
[alpha, 255, 0, 0]
when :blue
[alpha, 0, 0, 255]
when :yellow
[alpha, 255, 255, 0]
when :black
[alpha, 0, 0, 0]
end
end
end
As a convenience, if multiple enums share the same configuration, you can pass all of them to config.define.
config.define :booking_status, :connector_type, :color, :order => :name
STI is also supported:
config.define :base_enum, :name_column => ;foo
config.define :booking_status, :connector_type, :color, :extends => :base_enum
A pair of custom RSpec matchers are included to streamline testing of enums and enumerated attributes.
This is used to test that a model acts as enumerated. Example:
describe BookingStatus do
it { should act_as_enumerated }
end
This also works:
describe BookingStatus do
it "should act as enumerated" do
BookingStatus.should act_as_enumerated
end
end
You can use the with_items
chained matcher to test that each enum is properly seeded:
describe BookingStatus do
it {
should act_as_enumerated.with_items(:confirmed, :received, :rejected)
}
end
You can also pass in hashes if you want to be thorough and test out all the attributes of each enum. If
you do this, you must pass in the :name
attribute in each hash
describe BookingStatus do
it {
should act_as_enumerated.with_items(
{ :name => 'confirmed', :description => "Processed and confirmed" },
{ :name => 'received', :description => "Pending confirmation" },
{ :name => 'rejected', :description => "Rejected due to internal rules" }
)
}
end
This is used to test that a model has enumerated the given attribute:
describe Booking do
it { should have_enumerated(:status) }
end
This is also valid:
describe Booking do
it "Should have enumerated the status attribute" do
Booking.should have_enumerated(:status)
end
end
Tests if an enum instance matches the given value, which may be a symbol, id, string, or enum instance:
describe Booking do
it "status should be 'received' for a new booking" do
Booking.new.status.should match_enum(:received)
end
end
Of course Booking.new.status.should === :received
still works, but is liable to produce false positives.
Execute the test setup script:
script/test_setup.sh
Go to the 'dummy' project:
cd ./spec/dummy
If this is your first time, create the test database
RAILS_ENV=test bundle exec rake db:create
Run migrations for test environment:
RAILS_ENV=test bundle exec rake db:migrate
Go back to gem root directory:
cd ../../
bundle exec rake spec
- Initial Version Copyright (c) 2005 Trevor Squires
- Rails 3 Updates Copyright (c) 2010 Pivotal Labs
- Initial Test Suite Copyright (c) 2011 Sergey Potapov
- Subsequent Updates Copyright (c) 2011-2020 Arthur Shagall
Released under the MIT License. See the LICENSE file for more details.
Contributions are welcome. However, please make sure of the following before issuing a pull request:
- All specs are passing.
- Any new features have test coverage. Use the SimpleCov report to confirm.
- Anything that breaks backward compatibility has a very good reason for doing so.