RubyEnum

A simple enumeration type for ruby.

Add this line to your application's Gemfile:

gem 'ruby_enum', "~> 0.4" # for Rails 3
gem 'ruby_enum', "~> 1.0" # for Rails 4

And then execute:

$ bundle

Or install it yourself as:

$ gem install ruby_enum

To create an enumeration type include the RubyEnum module in your enumeration class and provide the enumeration's values as follows:

class Coordinate
  include RubyEnum
  
  enum :north
  enum :south
  enum :west
  enum :east
end

For each value an new sigleton instance of the class will be created. If you define the same enumeration value twice, an error will be raised.

Including RubyEnum in any class will make it a singleton. You will not be able to create new instances of your class using new, allocate, clone or dup.

You can access an enumeration's values in three different ways:

Using a class method that matches the enumeration instance name:

north = Coordinate.north

Using a constant that matches the enumeration instance name:

north = Coordinate::NORTH

Treating your enumeration class as a dictionary:

north = Coordinate[:north]

Note that his method returns nil if no enumeration instance is found by the specified name.

To retrieve all enumeration instances simply use method all on your enumeration class:

coordinates = Coordinate.all

Each enumeration instance has an implicit name and associated value attributes accessible through the name and value methods. If no associated value is specified for an enumeration instance in the definition of the enumeration class, it will be implicitly set to its name:

north = Coordinate.north
north.name
# => :north
north.value
# => "north"

You may provide a custom associated value to each enumeration instance following its name in the declaration:

class Planet
  include RubyEnum

  enum :mercury, 1
  enum :venus, 2
  enum :earth, 3
end

mercury = Planet.mercury
mercury.name
# => :mercury
mercury.value
# => 1

Associated values should be unique in the context of an enumeration class. An error will be thrown in those cases, for example:

class InvalidEnumeration
  include RubyEnum

  enum :a, 1
  enum :b, 1
end

You can find an enumeration value by its associated value:

mercury = Planet.find_by_value 1

If no enumeration instance is found with the specified associated value this method returns nil. Using the find_by_value! version, an error is raised in this case.

To test enumeration classes you can use the custom be_an_enumeration and define_enumeration_value matchers.

require 'ruby_enum/rspec'

describe Coordinate do

  it { should be_an_enumeration }
  it { should define_enumeration_value :north }
  it { should define_enumeration_value :north, 'north' }
end

Nothing stops you from adding your own methods to an enumeration.

class Planet
  include RubyEnum

  enum :mercury, 1
  enum :venus, 2
  enum :earth, 3

  def description
    "#{name.to_s.capitalize} is the #{value.ordinalize} rock from the sun"
  end
end

mercury = Planet::EARTH
mercury.description
# => "Earth is the 3rd rock from the sun"

1. Fork it ( https://github.com/laskaridis/ruby_enum/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request