philiprehberger-enum

Type-safe enumerations with ordinals, custom values, and pattern matching

Requirements

Ruby >= 3.1

Installation

Add to your Gemfile:

gem "philiprehberger-enum"

Or install directly:

gem install philiprehberger-enum

Usage

require "philiprehberger/enum"

class Status < Philiprehberger::Enum
  member :draft
  member :published
  member :archived
end

Status::DRAFT.name       # => :draft
Status::DRAFT.ordinal    # => 0
Status.members           # => [DRAFT, PUBLISHED, ARCHIVED]

Custom Values

class HttpCode < Philiprehberger::Enum
  member :ok, value: 200
  member :not_found, value: 404
  member :server_error, value: 500
end

HttpCode::OK.value          # => 200
HttpCode.from_value(404)    # => HttpCode::NOT_FOUND

Lookup Methods

Status.from_name(:draft)    # => Status::DRAFT
Status.from_string('draft') # => Status::DRAFT
Status.valid?(:draft)       # => true
Status.valid?(:unknown)     # => false

Enumerable

Enum classes include Enumerable, so you can iterate, map, select, etc.:

Status.each { |member| puts member.name }
Status.map(&:name)                # => [:draft, :published, :archived]
Status.select { |m| m.ordinal > 0 } # => [PUBLISHED, ARCHIVED]
Status.to_a                       # => [DRAFT, PUBLISHED, ARCHIVED]
Status.min                        # => DRAFT

Collection Methods

Status.to_h              # => { draft: nil, published: nil, archived: nil }
HttpCode.to_h            # => { ok: 200, not_found: 404, server_error: 500 }
HttpCode.members_by_value # => { 200 => OK, 404 => NOT_FOUND, 500 => SERVER_ERROR }
Status.size              # => 3
Status.count             # => 3

Strict Lookup

fetch and fetch_by_value raise an error instead of returning nil:

Status.fetch(:draft)          # => Status::DRAFT
Status.fetch(:unknown)        # raises Philiprehberger::Enum::Error
HttpCode.fetch_by_value(200)  # => HttpCode::OK
HttpCode.fetch_by_value(999)  # raises Philiprehberger::Enum::Error

Names, Values, First & Last

HttpCode.names   # => [:ok, :not_found, :server_error]
HttpCode.values  # => [200, 404, 500]
Status.first     # => Status::DRAFT
Status.last      # => Status::ARCHIVED

Slice

slice returns members matching the given names, silently skipping any that are unknown:

Status.slice(:draft, :archived)          # => [Status::DRAFT, Status::ARCHIVED]
Status.slice(:draft, :nonexistent)       # => [Status::DRAFT]
Status.slice(:archived, :draft)          # => [Status::ARCHIVED, Status::DRAFT]

Sample

sample returns a random member. Pass an integer to get an array:

Status.sample       # => Status::DRAFT  (random)
Status.sample(2)    # => [Status::PUBLISHED, Status::ARCHIVED]  (random)

Case-Insensitive Lookup

from_name tries an exact match first, then falls back to case-insensitive:

Status.from_name(:draft)    # => Status::DRAFT (exact match)
Status.from_name("DRAFT")   # => Status::DRAFT (case-insensitive)
Status.from_name("Draft")   # => Status::DRAFT (case-insensitive)

Comparison

Members are comparable by ordinal:

Status::DRAFT < Status::PUBLISHED   # => true
Status.members.sort                  # sorted by declaration order

Pattern Matching

case Status::DRAFT
in { name: :draft }
  'is draft'
in { name: :published }
  'is published'
end

Serialization

Status::DRAFT.to_s     # => "draft"
Status::DRAFT.to_json  # => '{"name":"draft","ordinal":0,"value":null}'

API