{"id":13879579,"url":"https://github.com/dblock/ruby-enum","last_synced_at":"2025-05-16T00:00:32.786Z","repository":{"id":8467987,"uuid":"10066834","full_name":"dblock/ruby-enum","owner":"dblock","description":"A handy way to define enums in Ruby.","archived":false,"fork":false,"pushed_at":"2024-08-16T09:51:18.000Z","size":113,"stargazers_count":180,"open_issues_count":3,"forks_count":23,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-05-10T01:26:19.728Z","etag":null,"topics":["enum","enumerable","enums","ruby"],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dblock.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-05-14T23:08:56.000Z","updated_at":"2025-03-22T17:09:21.000Z","dependencies_parsed_at":"2024-01-08T00:21:10.524Z","dependency_job_id":"74a3c8d2-0697-4676-8e31-8eac5147e22d","html_url":"https://github.com/dblock/ruby-enum","commit_stats":{"total_commits":94,"total_committers":11,"mean_commits":8.545454545454545,"dds":0.3936170212765957,"last_synced_commit":"a035d2a39e878f1fe06699a41accc46a95cdf405"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dblock%2Fruby-enum","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dblock%2Fruby-enum/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dblock%2Fruby-enum/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dblock%2Fruby-enum/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dblock","download_url":"https://codeload.github.com/dblock/ruby-enum/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254442854,"owners_count":22071877,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["enum","enumerable","enums","ruby"],"created_at":"2024-08-06T08:02:25.807Z","updated_at":"2025-05-16T00:00:32.677Z","avatar_url":"https://github.com/dblock.png","language":"Ruby","readme":"Ruby::Enum\n==========\n\n[![Gem Version](http://img.shields.io/gem/v/ruby-enum.svg)](http://badge.fury.io/rb/ruby-enum)\n[![Build Status](https://github.com/dblock/ruby-enum/workflows/test/badge.svg?branch=master)](https://github.com/dblock/ruby-enum/actions)\n[![Code Climate](https://codeclimate.com/github/dblock/ruby-enum.svg)](https://codeclimate.com/github/dblock/ruby-enum)\n\nEnum-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).\n\n## Table of Contents\n\n- [Usage](#usage)\n  - [Constants](#constants)\n  - [Class Methods](#class-methods)\n  - [Default Value](#default-value)\n  - [Enumerating](#enumerating)\n    - [Iterating](#iterating)\n    - [Mapping](#mapping)\n    - [Reducing](#reducing)\n    - [Sorting](#sorting)\n  - [Hashing](#hashing)\n    - [Retrieving keys and values](#retrieving-keys-and-values)\n    - [Mapping keys to values](#mapping-keys-to-values)\n    - [Mapping values to keys](#mapping-values-to-keys)\n  - [Duplicate enumerator keys or duplicate values](#duplicate-enumerator-keys-or-duplicate-values)\n  - [Inheritance](#inheritance)\n  - [Exhaustive case matcher](#exhaustive-case-matcher)\n  - [I18n support](#i18n-support)\n- [Benchmarks](#benchmarks)\n- [Contributing](#contributing)\n- [Copyright and License](#copyright-and-license)\n- [Related Projects](#related-projects)\n\n## Usage\n\nEnums can be defined and accessed either as constants, or class methods, which is a matter of preference.\n\n### Constants\n\nDefine enums, and reference them as constants.\n\n``` ruby\nclass OrderState\n  include Ruby::Enum\n\n  define :CREATED, 'created'\n  define :PAID, 'paid'\nend\n```\n\n``` ruby\nOrderState::CREATED # 'created'\nOrderState::PAID # 'paid'\nOrderState::UNKNOWN # raises Ruby::Enum::Errors::UninitializedConstantError\nOrderState.keys # [ :CREATED, :PAID ]\nOrderState.values # [ 'created', 'paid' ]\nOrderState.to_h # { :CREATED =\u003e 'created', :PAID =\u003e 'paid' }\n```\n\n### Class Methods\n\nDefine enums, and reference them as class methods.\n\n``` ruby\nclass OrderState\n  include Ruby::Enum\n\n  define :created, 'created'\n  define :paid, 'paid'\nend\n```\n\n```ruby\nOrderState.created # 'created'\nOrderState.paid # 'paid'\nOrderState.undefined # NoMethodError is raised\nOrderState.keys # [ :created, :paid ]\nOrderState.values # ['created', 'paid']\nOrderState.to_h # { :created =\u003e 'created', :paid =\u003e 'paid' }\n```\n\n### Default Value\n\nThe value is optional. If unspecified, the value will default to the key.\n\n``` ruby\nclass OrderState\n  include Ruby::Enum\n\n  define :UNSPECIFIED\n  define :unspecified\nend\n```\n\n``` ruby\nOrderState::UNSPECIFIED # :UNSPECIFIED\nOrderState.unspecified # :unspecified\n```\n\n### Enumerating\n\nEnums support all `Enumerable` methods.\n\n#### Iterating\n\n``` ruby\nOrderState.each do |key, enum|\n  # key and enum.key are :CREATED, :PAID\n  # enum.value is 'created', 'paid'\nend\n```\n\n``` ruby\nOrderState.each_key do |key|\n  # :CREATED, :PAID\nend\n```\n\n``` ruby\nOrderState.each_value do |value|\n  # 'created', 'paid'\nend\n```\n\n#### Mapping\n\n``` ruby\nOrderState.map do |key, enum|\n  # key and enum.key are :CREATED, :PAID\n  # enum.value is 'created', 'paid'\n  [enum.value, key]\nend\n\n# =\u003e [ ['created', :CREATED], ['paid', :PAID] ]\n```\n\n#### Reducing\n\n``` ruby\nOrderState.reduce([]) do |arr, (key, enum)|\n  # key and enum.key are :CREATED, :PAID\n  # enum.value is 'created', 'paid'\n  arr \u003c\u003c [enum.value, key]\nend\n\n# =\u003e [ ['created', :CREATED], ['paid', :PAID] ]\n```\n\n#### Sorting\n\n``` ruby\nOrderState.sort_by do |key, enum|\n  # key and enum.key are :CREATED, :PAID\n  # enum.value is 'created', 'paid'\n  enum.value.length\nend\n\n# =\u003e [[:PAID, #\u003cOrderState:0x0 @key=:PAID, @value=\"paid\"\u003e], [:CREATED, #\u003cOrderState:0x1 @key=:CREATED, @value=\"created\"\u003e]]\n```\n\n### Hashing\n\nSeveral hash-like methods are supported.\n\n#### Retrieving keys and values\n\n``` ruby\nOrderState.keys\n# =\u003e [:CREATED, :PAID]\n\nOrderState.values\n# =\u003e ['created', 'paid']\n```\n\n#### Mapping keys to values\n\n``` ruby\nOrderState.key?(:CREATED)\n# =\u003e true\n\nOrderState.value(:CREATED)\n# =\u003e 'created'\n\nOrderState.key?(:FAILED)\n# =\u003e false\n\nOrderState.value(:FAILED)\n# =\u003e nil\n```\n\n#### Mapping values to keys\n\n``` ruby\nOrderState.value?('paid')\n# =\u003e true\n\nOrderState.key('paid')\n# =\u003e :PAID\n\nOrderState.value?('failed')\n# =\u003e false\n\nOrderState.key('failed')\n# =\u003e nil\n```\n\n### Duplicate enumerator keys or duplicate values\n\nDefining duplicate enums raises `Ruby::Enum::Errors::DuplicateKeyError`.\n\n```ruby\nclass OrderState\n  include Ruby::Enum\n\n  define :CREATED, 'created'\n  define :CREATED, 'recreated' # raises DuplicateKeyError\nend\n```\n\nDefining a duplicate value raises `Ruby::Enum::Errors::DuplicateValueError`.\n\n```ruby\nclass OrderState\n  include Ruby::Enum\n\n  define :CREATED, 'created'\n  define :RECREATED, 'created' # raises DuplicateValueError\nend\n```\n\nThe `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')`.\n\n### Inheritance\n\nWhen inheriting from a `Ruby::Enum` class, all defined enums in the parent class will be accessible in sub classes as well. Sub classes can also provide extra enums, as usual.\n\n``` ruby\nclass OrderState\n  include Ruby::Enum\n\n  define :CREATED, 'CREATED'\n  define :PAID, 'PAID'\nend\n\nclass ShippedOrderState \u003c OrderState\n  define :PREPARED, 'PREPARED'\n  define :SHIPPED, 'SHIPPED'\nend\n```\n\n``` ruby\nShippedOrderState::CREATED # 'CREATED'\nShippedOrderState::PAID # 'PAID'\nShippedOrderState::PREPARED # 'PREPARED'\nShippedOrderState::SHIPPED # 'SHIPPED'\n```\n\nThe `values` class method will enumerate the values from all base classes.\n\n``` ruby\nOrderState.values # ['CREATED', 'PAID']\nShippedOrderState.values # ['CREATED', 'PAID', 'PREPARED', SHIPPED']\n```\n\n### Exhaustive case matcher\n\nIf 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.\n\n\u003e NOTE: This will add checks at runtime which might lead to worse performance. See [benchmarks](#benchmarks).\n\n\u003e NOTE: `:else` is a reserved keyword if you want to use `Ruby::Enum::Case`.\n\n```ruby\nclass Color \u003c OrderState\n  include Ruby::Enum\n  include Ruby::Enum::Case\n\n  define :RED, :red\n  define :GREEN, :green\n  define :BLUE, :blue\n  define :YELLOW, :yellow\nend\n```\n\n```ruby\ncolor = Color::RED\nColor.Case(color, {\n  [Color::GREEN, Color::BLUE] =\u003e -\u003e { \"order is green or blue\" },\n  Color::YELLOW =\u003e -\u003e { \"order is yellow\" },\n  Color::RED =\u003e -\u003e { \"order is red\" },\n})\n```\n\nIt also supports default/else:\n\n```ruby\ncolor = Color::RED\nColor.Case(color, {\n  [Color::GREEN, Color::BLUE] =\u003e -\u003e { \"order is green or blue\" },\n  else: -\u003e { \"order is yellow or red\" },\n})\n```\n\n### I18n support\n\nThis 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.\n\n```ruby\n# Add this to your Gemfile if you want to have a nice error description instead of just a message key.\ngem \"i18n\"\n```\n\n## Benchmarks\n\nBenchmark scripts are defined in the [`benchmarks`](benchmarks) folder and can be run with Rake:\n\n```console\nrake benchmarks:case\n```\n\n## Contributing\n\nYou're encouraged to contribute to ruby-enum. See [CONTRIBUTING](CONTRIBUTING.md) for details.\n\n## Copyright and License\n\nCopyright (c) 2013-2021, Daniel Doubrovkine and [Contributors](CHANGELOG.md).\n\nThis project is licensed under the [MIT License](LICENSE.md).\n\n## Related Projects\n\n* [typesafe_enum](https://github.com/dmolesUC3/typesafe_enum): Typesafe enums, inspired by Java.\n* [renum](https://github.com/duelinmarkers/renum): A readable, but terse enum.\n","funding_links":[],"categories":["Ruby"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdblock%2Fruby-enum","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdblock%2Fruby-enum","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdblock%2Fruby-enum/lists"}