This is a very basic implementation of enums in Ruby. The cornerstone of the library is safety.
Add this line to your application's Gemfile:
And then execute:
Or install it yourself as:
$ gem install safe-enum
Define set of enums with code like this:
class Side < Enum::Base values :left, :right end
Now get a value with the
enum method safely defined values by argument with its
String type. If there is no defined such value
Enum::TokenNotFoundError exception will be raised. And this is the safety - you will be noticed about the problem and fix it by introducing a new value or fixing a source of the invalid value. While others implementations of enums in Ruby (that I know) just silently ignore invalid values returning
nil this one will raise the exception always. Example of usage:
Side.enum(:left) # => "left" Side.enum('left') # => "left" Side.enum(:invalid) # => Enum::TokenNotFoundError: token 'invalid'' not found in the enum Side Side.enum('invalid') # => Enum::TokenNotFoundError: token 'invalid'' not found in the enum Side
Get all defined enum values with the
Side.all # => ['left', 'rigth', 'whole']
Order or the returned values in the same as their definition. It's guaranteed.
In order to get array of defined enums safely use
Side.enums(:left, :right) # => ['left', 'right']
If you have installed
I18n in your application feel free to use
name method to retreive the values' translations. For the given example the possible translation structure in
yml format is the following:
en: enum: Side: left: 'Left' right: 'Right'
name method usage example:
Side.name(:left) # => "Left" Side.name('left') # => "Left" Side.name(:right) # => "Right" Side.name('right') # => "Right" Side.name(:invalid) # => Enum::TokenNotFoundError: token 'invalid'' not found in the enum Side
If you don't have installed
I18nin your project
NameErrorexception will be raised on the
Consider the case when we have an object with a field with only enum values. Extend the class of this object by
Enum::Predicates and use
enumerize method to generate predicates. This is a more convenient way matching current value of the field with an enum value. Usage the predicate methods is safe also. It means that you can't pass to the method invalid enum value neither can have an invalid value in the field:
class Table extend Enum::Predicates attr_accessor :side enumerize :side, Side end @table = Table.new @table.side_is?(:left) # => false @table.side_is?(nil) # => false @table.side = Side.enum(:left) @table.side_is?(:left) # => true @table.side_is?(:right) # => false @table.side_is?(nil) # => false @table.side_is?(:invalid) # => Enum::TokenNotFoundError: token 'invalid'' not found in the enum Side @table.side = 'invalid' @table.side_is?(nil) # => false @table.side_is?(:left) # => Enum::TokenNotFoundError: token 'invalid'' not found in the enum Side @table.side_any?(:left, :right) # => true @table.side_any?(:right) # => false @table.side_any?(:invalid, :left) # => Enum::TokenNotFoundError: token 'invalid'' not found in the enum Side
If you pass to the predicate
nilvalue in the field the result will be always
false. If you want to check that the field is
niljust use Ruby's standard method
It's possible to get index of an enum value with
index method. It can be convenient in some circumstances:
class WeekDay < Enum::Base values :sunday, :monday, :tuesday, :wednesday, :thusday, :friday, :saturday end WeekDay.index(:sunday) == Date.new(2015, 9, 13).wday # => true WeekDay.index(:monday) # => 1 WeekDay.indexes # => [0, 1, 2, 3, 4, 5, 6]
After checking out the repo, run
bin/setup to install dependencies. Then, run
rake test to run the tests. You can also run
bin/console for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run
bundle exec rake install. To release a new version, update the version number in
version.rb, and then run
bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the
.gem file to rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/mezuka/enum. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
The gem is available as open source under the terms of the MIT License.