Ruby::Enum
==========

[![Gem Version](http://img.shields.io/gem/v/ruby-enum.svg)](http://badge.fury.io/rb/ruby-enum)
[![Test](https://github.com/dblock/ruby-enum/actions/workflows/test.yml/badge.svg)](https://github.com/dblock/ruby-enum/actions/workflows/test.yml)
[![Coverage Status](https://coveralls.io/repos/github/dblock/ruby-enum/badge.svg?branch=master)](https://coveralls.io/github/dblock/ruby-enum?branch=master)

Enum-like behavior for Ruby, heavily inspired by [this](http://www.rubyfleebie.com/enumerations-and-ruby), and improved upon [another blog post](http://code.dblock.org/how-to-define-enums-in-ruby).

## Table of Contents

- [Usage](#usage)
  - [Constants](#constants)
  - [Class Methods](#class-methods)
  - [Default Value](#default-value)
  - [Enumerating](#enumerating)
    - [Iterating](#iterating)
    - [Mapping](#mapping)
    - [Reducing](#reducing)
    - [Sorting](#sorting)
  - [Hashing](#hashing)
    - [Retrieving keys and values](#retrieving-keys-and-values)
    - [Mapping keys to values](#mapping-keys-to-values)
    - [Mapping values to keys](#mapping-values-to-keys)
  - [Duplicate enumerator keys or duplicate values](#duplicate-enumerator-keys-or-duplicate-values)
  - [Inheritance](#inheritance)
  - [Exhaustive case matcher](#exhaustive-case-matcher)
  - [I18n support](#i18n-support)
- [Benchmarks](#benchmarks)
  - [Performance](#performance)
- [Contributing](#contributing)
- [Copyright and License](#copyright-and-license)
- [Related Projects](#related-projects)

## Usage

Enums can be defined and accessed either as constants, or class methods, which is a matter of preference.

### Constants

Define enums, and reference them as constants.

``` ruby
class OrderState
  include Ruby::Enum

  define :CREATED, 'created'
  define :PAID, 'paid'
end
```

``` ruby
OrderState::CREATED # 'created'
OrderState::PAID # 'paid'
OrderState::UNKNOWN # raises Ruby::Enum::Errors::UninitializedConstantError
OrderState.keys # [ :CREATED, :PAID ]
OrderState.values # [ 'created', 'paid' ]
OrderState.to_h # { :CREATED => 'created', :PAID => 'paid' }
```

### Class Methods

Define enums, and reference them as class methods.

``` ruby
class OrderState
  include Ruby::Enum

  define :created, 'created'
  define :paid, 'paid'
end
```

```ruby
OrderState.created # 'created'
OrderState.paid # 'paid'
OrderState.undefined # NoMethodError is raised
OrderState.keys # [ :created, :paid ]
OrderState.values # ['created', 'paid']
OrderState.to_h # { :created => 'created', :paid => 'paid' }
```

### Default Value

The value is optional. If unspecified, the value will default to the key.

``` ruby
class OrderState
  include Ruby::Enum

  define :UNSPECIFIED
  define :unspecified
end
```

``` ruby
OrderState::UNSPECIFIED # :UNSPECIFIED
OrderState.unspecified # :unspecified
```

### Enumerating

Enums support all `Enumerable` methods.

#### Iterating

``` ruby
OrderState.each do |key, enum|
  # key and enum.key are :CREATED, :PAID
  # enum.value is 'created', 'paid'
end
```

``` ruby
OrderState.each_key do |key|
  # :CREATED, :PAID
end
```

``` ruby
OrderState.each_value do |value|
  # 'created', 'paid'
end
```

#### Mapping

``` ruby
OrderState.map do |key, enum|
  # key and enum.key are :CREATED, :PAID
  # enum.value is 'created', 'paid'
  [enum.value, key]
end

# => [ ['created', :CREATED], ['paid', :PAID] ]
```

#### Reducing

``` ruby
OrderState.reduce([]) do |arr, (key, enum)|
  # key and enum.key are :CREATED, :PAID
  # enum.value is 'created', 'paid'
  arr << [enum.value, key]
end

# => [ ['created', :CREATED], ['paid', :PAID] ]
```

#### Sorting

``` ruby
OrderState.sort_by do |key, enum|
  # key and enum.key are :CREATED, :PAID
  # enum.value is 'created', 'paid'
  enum.value.length
end

# => [[:PAID, #<OrderState:0x0 @key=:PAID, @value="paid">], [:CREATED, #<OrderState:0x1 @key=:CREATED, @value="created">]]
```

### Hashing

Several hash-like methods are supported.

#### Retrieving keys and values

``` ruby
OrderState.keys
# => [:CREATED, :PAID]

OrderState.values
# => ['created', 'paid']
```

#### Mapping keys to values

``` ruby
OrderState.key?(:CREATED)
# => true

OrderState.value(:CREATED)
# => 'created'

OrderState.key?(:FAILED)
# => false

OrderState.value(:FAILED)
# => nil
```

#### Mapping values to keys

``` ruby
OrderState.value?('paid')
# => true

OrderState.key('paid')
# => :PAID

OrderState.value?('failed')
# => false

OrderState.key('failed')
# => nil
```

### Duplicate enumerator keys or duplicate values

Defining duplicate enums raises `Ruby::Enum::Errors::DuplicateKeyError`.

```ruby
class OrderState
  include Ruby::Enum

  define :CREATED, 'created'
  define :CREATED, 'recreated' # raises DuplicateKeyError
end
```

Defining a duplicate value raises `Ruby::Enum::Errors::DuplicateValueError`.

```ruby
class OrderState
  include Ruby::Enum

  define :CREATED, 'created'
  define :RECREATED, 'created' # raises DuplicateValueError
end
```

The `DuplicateValueError` exception is raised to be consistent with the unique key constraint. Since keys are unique, there needs to be a way to map values to keys using `OrderState.value('created')`.

### Inheritance

When inheriting from a `Ruby::Enum` class, all defined enums in the parent class will be accessible in subclasses as well. Subclasses can also provide extra enums, as usual.

``` ruby
class OrderState
  include Ruby::Enum

  define :CREATED, 'CREATED'
  define :PAID, 'PAID'
end

class ShippedOrderState < OrderState
  define :PREPARED, 'PREPARED'
  define :SHIPPED, 'SHIPPED'
end
```

``` ruby
ShippedOrderState::CREATED # 'CREATED'
ShippedOrderState::PAID # 'PAID'
ShippedOrderState::PREPARED # 'PREPARED'
ShippedOrderState::SHIPPED # 'SHIPPED'
```

The `values` class method will enumerate the values from all base classes.

``` ruby
OrderState.values # ['CREATED', 'PAID']
ShippedOrderState.values # ['CREATED', 'PAID', 'PREPARED', SHIPPED']
```

All other enumerating and hashing methods (`keys`, `key?`, `value?`, `key`, `value`, `to_h`, `parse` and `each`) also consider enums defined anywhere in the class hierarchy.

``` ruby
ShippedOrderState.keys # [:CREATED, :PAID, :PREPARED, :SHIPPED]
ShippedOrderState.key?(:CREATED) # true
ShippedOrderState.value(:CREATED) # 'CREATED'
```

A subclass may redefine a key or value already used by a parent class without raising `DuplicateKeyError` or `DuplicateValueError`; its own definition takes precedence.

``` ruby
class ShippedOrderState < OrderState
  define :CREATED, 'RECREATED' # does not raise, overrides the parent class' definition
end

ShippedOrderState::CREATED # 'RECREATED'
ShippedOrderState.value(:CREATED) # 'RECREATED'
OrderState.value(:CREATED) # 'CREATED', unaffected
```

### Exhaustive case matcher

If you want to make sure that you cover all cases in a case stament, you can use the exhaustive case matcher: `Ruby::Enum::Case`. It will raise an error if a case/enum value is not handled, or if a value is specified that's not part of the enum. This is inspired by the [Rust Pattern Syntax](https://doc.rust-lang.org/book/ch18-03-pattern-syntax.html). If multiple cases match, all matches are being executed. The return value is the value from the matched case, or an array of return values if multiple cases matched.

> NOTE: This will add checks at runtime which might lead to worse performance. See [benchmarks](#benchmarks).

> NOTE: `:else` is a reserved keyword if you want to use `Ruby::Enum::Case`.

```ruby
class Color < OrderState
  include Ruby::Enum
  include Ruby::Enum::Case

  define :RED, :red
  define :GREEN, :green
  define :BLUE, :blue
  define :YELLOW, :yellow
end
```

```ruby
color = Color::RED
Color.Case(color, {
  [Color::GREEN, Color::BLUE] => -> { "order is green or blue" },
  Color::YELLOW => -> { "order is yellow" },
  Color::RED => -> { "order is red" },
})
```

It also supports default/else:

```ruby
color = Color::RED
Color.Case(color, {
  [Color::GREEN, Color::BLUE] => -> { "order is green or blue" },
  else: -> { "order is yellow or red" },
})
```

### I18n support

This gem has an optional dependency to `i18n`. If it's available, the error messages will have a nice description and can be translated. If it's not available, the errors will only contain the message keys.

```ruby
# Add this to your Gemfile if you want to have a nice error description instead of just a message key.
gem "i18n"
```

## Benchmarks

Benchmark scripts are defined in the [`benchmarks`](benchmarks) folder and can be run with Rake:

```console
rake benchmark:basic
rake benchmark:case
rake benchmark:inheritance
```

### Performance

Constant access (e.g. `Colors::RED`) has no measurable overhead versus a plain Ruby constant, since it's just a constant lookup either way. Basic operations backed by a hash lookup - `value`, `key`, `key?`, `value?`, `keys`, `values` - carry some overhead (roughly 3-5x) compared to using a plain `Hash` directly, due to the extra method dispatch and object wrapping `Ruby::Enum` does internally. Run `rake benchmark:basic` to measure this on your own machine.

This overhead is constant regardless of how deep a subclass hierarchy is - `keys`, `key?`, `value?`, `key`, `value`, `to_h`, `parse` and `each` merge and memoize enums inherited from superclasses, so a subclass' lookups are effectively as fast as the base class' (see `rake benchmark:inheritance`).

The one notable exception is `Ruby::Enum::Case`, whose exhaustive `case`-like matcher is significantly slower (on the order of 50-100x, see `rake benchmark:case`) than a native Ruby `case`/`when` statement, since it builds and evaluates lambdas on every call rather than being optimized by the Ruby VM. Prefer a native `case` statement in hot code paths and reserve `Ruby::Enum::Case` for cases where its exhaustiveness check is worth the overhead.

For most applications this overhead is negligible in absolute terms (low single-digit microseconds per call), but it's worth being aware of in very hot code paths.

## Contributing

You're encouraged to contribute to ruby-enum. See [CONTRIBUTING](CONTRIBUTING.md) for details.

## Copyright and License

Copyright (c) 2013-2026, Daniel Doubrovkine and [Contributors](CHANGELOG.md).

This project is licensed under the [MIT License](LICENSE.md).

## Related Projects

* [typesafe_enum](https://github.com/dmolesUC3/typesafe_enum): Typesafe enums, inspired by Java.
* [renum](https://github.com/duelinmarkers/renum): A readable, but terse enum.
