ruby-enum 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ef6a193362634cd178978189b5e5a09fafe68ad2428c1d646abf33ef6f66d4a
-  data.tar.gz: 182bdfaff04b1b241bac9614722a3010d2613e2ff8b0cb7a603053df6796b664
+  metadata.gz: 0424fcb26d8fc260165a669fa7be1d83e41a3a8e967ad606c5eb72abb656b349
+  data.tar.gz: 2ea8e9dc094a9612447679c7d5bebf88ac466b1c1b9a5f666d3ce5a8d0981965
 SHA512:
-  metadata.gz: 40d0b2b8a93150ec1f21ef209e020dcb6a75142eaba2fd989b9f0ac6853953ec5a6ec0b9a356f8d1411e2ffb6ab955acb453cb576ba841cad3ec7eea6ffebac5
-  data.tar.gz: 65fe31ba27ba5f9c76d95090d00d8024fb0ba1f7abb8bd5e5bff87ea7559f941ec67a35a655f5cfe39b1e68e89de043d0702bd572ed18465483c1c4bc36fe6dc
+  metadata.gz: 024aac1db4f01d3528a1130817e3db22e7e413d598e99d5dc333a040057896129420193731cec1706922a5c462322809e4e6ce5de2d871f1d2492e67990b56ab
+  data.tar.gz: c8a5b49346df275afd18502410a9e24a5806fdfdb0d31d2a7a53783edf8b592b3fe27789ca19d26f32d3937142f40c561b2a9d87ef5cff66e9aa7d05c3054cf6

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+### 1.2.0 (2026/8/14)
+
+* [#49](https://github.com/dblock/ruby-enum/issues/49): Fixed `NoMethodError` on `keys`, `values`, `key?`, `value?`, `key`, `value`, `to_h`, `parse` and `each` when a subclass defines no enums of its own - [@dblock](https://github.com/dblock).
+* [#49](https://github.com/dblock/ruby-enum/issues/49): `keys`, `key?`, `value?`, `key`, `value`, `to_h`, `parse` and `each` now include enums defined in a superclass, matching the existing behavior of `values` - [@dblock](https://github.com/dblock).
+* [#61](https://github.com/dblock/ruby-enum/pull/61): Document performance overhead in README, add `rake benchmark:basic` - [@dblock](https://github.com/dblock).
+
 ### 1.1.0 (2026/6/20)
 
 * [#56](https://github.com/dblock/ruby-enum/pull/56): Fix `DuplicateKeyError` when the enum class is reloaded - [@flvrone](https://github.com/flvrone).

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    ruby-enum (1.1.0)
+    ruby-enum (1.2.0)
 
 GEM
   remote: http://rubygems.org/

data/README.md

@@ -27,6 +27,7 @@ Enum-like behavior for Ruby, heavily inspired by [this](http://www.rubyfleebie.c
   - [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)
@@ -232,7 +233,7 @@ The `DuplicateValueError` exception is raised to be consistent with the unique k
 
 ### Inheritance
 
-When 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.
+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
@@ -262,6 +263,26 @@ 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.
@@ -315,9 +336,21 @@ gem "i18n"
 Benchmark scripts are defined in the [`benchmarks`](benchmarks) folder and can be run with Rake:
 
 ```console
-rake benchmarks:case
+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.

data/RELEASING.md

@@ -11,7 +11,7 @@ bundle install
 rake
 ```
 
-Check that the last build succeeded in [Travis CI](https://travis-ci.org/dblock/ruby-enum) for all supported platforms.
+Check that the last build succeeded in [GitHub Actions](https://github.com/dblock/ruby-enum/actions) for all supported platforms.
 
 Add a date to this release in [CHANGELOG.md](CHANGELOG.md).
 
@@ -28,15 +28,24 @@ git add README.md CHANGELOG.md lib/ruby-enum/version.rb
 git commit -m "Preparing for release, 0.2.2."
 ```
 
-Release.
+Release. If you have MFA enabled on RubyGems (you should), `rake release` will build the gem, tag it, and push commits/tags to GitHub, but fail at the RubyGems push. Push the gem manually with your OTP.
 
 ```
 $ rake release
 
-ruby-enum 0.2.2 built to pkg/ruby-enum-0.2.2.gem.
-Tagged v0.2.2.
+ruby-enum 1.1.0 built to pkg/ruby-enum-1.1.0.gem.
+Tagged v1.1.0.
 Pushed git commits and tags.
-Pushed ruby-enum 0.2.2 to rubygems.org.
+...
+You have enabled multi-factor authentication. Please enter OTP code.
+```
+
+Then push to RubyGems manually:
+
+```
+$ gem push pkg/ruby-enum-1.1.0.gem --otp <OTP>
+Pushing gem to https://rubygems.org...
+Successfully registered gem: ruby-enum (1.1.0)
 ```
 
 ### Prepare for the Next Version

data/Rakefile

@@ -18,8 +18,18 @@ RuboCop::RakeTask.new(:rubocop)
 task default: %i[rubocop spec]
 
 namespace :benchmark do
+  desc 'Run benchmark for basic Ruby::Enum operations vs. plain Ruby equivalents'
+  task :basic do
+    require_relative 'benchmarks/basic'
+  end
+
   desc 'Run benchmark for the Ruby::Enum::Case'
   task :case do
     require_relative 'benchmarks/case'
   end
+
+  desc 'Run benchmark for enum lookups on classes with inheritance'
+  task :inheritance do
+    require_relative 'benchmarks/inheritance'
+  end
 end

data/UPGRADING.md

@@ -1,5 +1,44 @@
 # Upgrading Ruby::Enum
 
+## Upgrading to >= 1.2.0
+
+### Inheritance & `keys`, `key?`, `value?`, `key`, `value`, `to_h`, `parse` and `each`
+
+This only applies to classes that inherit from another which is a `Ruby::Enum`.
+
+Prior to version `1.2.0`, only `values` enumerated enums defined in the entire class hierarchy; `keys`, `key?`, `value?`, `key`, `value`, `to_h`, `parse` and `each` only considered enums defined directly on the class, silently ignoring anything defined in a superclass.
+
+As of version `1.2.0`, these methods behave consistently with `values` and also enumerate/consider enums defined anywhere in the class hierarchy, ancestors first. A subclass may still redefine a key or value already used by a superclass; its own definition takes precedence.
+
+``` ruby
+class PrimaryColors
+  include Ruby::Enum
+
+  define :RED, 'RED'
+  define :GREEN, 'GREEN'
+end
+
+class RainbowColors < PrimaryColors
+  define :ORANGE, 'ORANGE'
+end
+```
+
+`gem 'ruby-enum', '< 1.2.0'`
+
+``` ruby
+RainbowColors.keys       # => [:ORANGE]
+RainbowColors.key?(:RED) # => false
+```
+
+`gem 'ruby-enum', '>= 1.2.0'`
+
+``` ruby
+RainbowColors.keys       # => [:RED, :GREEN, :ORANGE]
+RainbowColors.key?(:RED) # => true
+```
+
+See [#49](https://github.com/dblock/ruby-enum/issues/49) for more information.
+
 ## Upgrading to >= 0.9.0
 
 ### Inheritance & `Ruby::Enum.values`

data/benchmarks/basic.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
+require 'benchmark'
+require 'ruby-enum'
+
+##
+# Ruby::Enum equivalent of a plain Hash/constant lookup.
+class Colors
+  include Ruby::Enum
+
+  define :RED, 'red'
+  define :GREEN, 'green'
+  define :BLUE, 'blue'
+end
+
+# Plain Ruby equivalents, doing the same lookups without Ruby::Enum.
+PLAIN_HASH = { RED: 'red', GREEN: 'green', BLUE: 'blue' }.freeze
+
+module PlainConstants
+  RED = 'red'
+  GREEN = 'green'
+  BLUE = 'blue'
+end
+
+n = 1_000_000
+
+def benchmark(label, iterations, &block)
+  time = Benchmark.realtime { iterations.times(&block) }
+  puts "#{label}: #{time.round(4)}"
+  time
+end
+
+puts "Running #{n} iterations of each scenario below\n\n"
+
+puts '--- Constant access ---'
+enum_const_time = benchmark('Ruby::Enum constant (Colors::RED)', n) { Colors::RED }
+plain_const_time = benchmark('plain Ruby constant (PlainConstants::RED)', n) { PlainConstants::RED }
+
+puts "\n--- Key to value lookup ---"
+enum_value_time = benchmark('Ruby::Enum (Colors.value(:RED))', n) { Colors.value(:RED) }
+hash_value_time = benchmark('plain Hash (PLAIN_HASH[:RED])', n) { PLAIN_HASH[:RED] }
+
+puts "\n--- Value to key lookup ---"
+benchmark('Ruby::Enum (Colors.key(\'red\'))', n) { Colors.key('red') }
+benchmark('plain Hash (PLAIN_HASH.key(\'red\'))', n) { PLAIN_HASH.key('red') }
+
+puts "\n--- Existence checks ---"
+benchmark('Ruby::Enum (Colors.key?(:RED))', n) { Colors.key?(:RED) }
+benchmark('plain Hash (PLAIN_HASH.key?(:RED))', n) { PLAIN_HASH.key?(:RED) }
+
+puts "\n--- Enumerating all keys/values ---"
+benchmark('Ruby::Enum (Colors.keys)', n) { Colors.keys }
+benchmark('plain Hash (PLAIN_HASH.keys)', n) { PLAIN_HASH.keys }
+benchmark('Ruby::Enum (Colors.values)', n) { Colors.values }
+benchmark('plain Hash (PLAIN_HASH.values)', n) { PLAIN_HASH.values }
+
+puts "\n--- Comparison ---"
+puts "Ruby::Enum constant access is #{(enum_const_time / plain_const_time).round(2)}x plain Ruby constant access"
+puts "Ruby::Enum .value is #{(enum_value_time / hash_value_time).round(2)}x plain Hash#[]"

data/benchmarks/inheritance.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
+require 'benchmark'
+require 'ruby-enum'
+
+##
+# Base enum, no inheritance.
+class Colors
+  include Ruby::Enum
+
+  define :RED, 'red'
+  define :GREEN, 'green'
+end
+
+##
+# Subclass, adds its own enum on top of an inherited one (1 level).
+class SubColors < Colors
+  define :BLUE, 'blue'
+end
+
+##
+# Sub-subclass, adds its own enum on top of 2 inherited levels.
+class SubSubColors < SubColors
+  define :YELLOW, 'yellow'
+end
+
+n = 1_000_000
+
+def benchmark(label, iterations, &block)
+  time = Benchmark.realtime { iterations.times(&block) }
+  puts "#{label}: #{time.round(4)}"
+  time
+end
+
+puts "Running #{n} iterations of each scenario below\n\n"
+
+puts '--- .value lookups, by depth of inheritance ---'
+base_value = benchmark('base class (no inheritance)', n) { Colors.value(:RED) }
+sub_value = benchmark('subclass (1 level)', n) { SubColors.value(:RED) }
+sub_sub_value = benchmark('sub-subclass (2 levels)', n) { SubSubColors.value(:RED) }
+
+puts "\n--- Other methods on a subclass (1 level) ---"
+benchmark('.keys', n) { SubColors.keys }
+benchmark('.key?', n) { SubColors.key?(:RED) }
+benchmark('.to_h', n) { SubColors.to_h }
+count = 0
+benchmark('.each', n) { SubColors.each { |_k, _v| count += 1 } }
+
+puts "\n--- Comparison ---"
+puts "subclass value is #{(sub_value / base_value).round(2)}x base class value"
+puts "sub-subclass value is #{(sub_sub_value / base_value).round(2)}x base class value"

data/lib/ruby-enum/enum.rb

@@ -20,8 +20,8 @@ module Ruby
 
       base.private_class_method(:new)
 
-      base.instance_variable_set(:@_enum_hash, {})
-      base.instance_variable_set(:@_enums_by_value, {})
+      base.instance_variable_set(:@_own_enum_hash, {})
+      base.instance_variable_set(:@_own_enums_by_value, {})
     end
 
     module ClassMethods
@@ -31,9 +31,6 @@ module Ruby
       # [key] Enumerator key.
       # [value] Enumerator value.
       def define(key, value = key)
-        @_enum_hash ||= {}
-        @_enums_by_value ||= {}
-
         validate_key!(key)
         validate_value!(value)
 
@@ -48,18 +45,21 @@ module Ruby
 
       def store_new_instance(key, value)
         new_instance = new(key, value)
-        @_enum_hash[key] = new_instance
-        @_enums_by_value[value] = new_instance
+        _own_enum_hash[key] = new_instance
+        _own_enums_by_value[value] = new_instance
+
+        # Invalidate memoized, merged hashes since this class' own enums changed.
+        @_enum_hash = @_enums_by_value = nil
       end
 
       def const_missing(key)
         raise Ruby::Enum::Errors::UninitializedConstantError, name: name, key: key
       end
 
-      # Iterate over all enumerated values.
+      # Iterate over all enumerated values, including those defined in a superclass.
       # Required for Enumerable mixin
       def each(&block)
-        @_enum_hash.each(&block)
+        _enum_hash.each(&block)
       end
 
       # Attempt to parse an enum key and return the
@@ -77,56 +77,56 @@ module Ruby
         nil
       end
 
-      # Whether the specified key exists in this enum.
+      # Whether the specified key exists in this enum, including those defined in a superclass.
       #
       # === Parameters
       # [k] The string key to check.
       #
       # Returns true if the key exists, false otherwise.
       def key?(k)
-        @_enum_hash.key?(k)
+        _enum_hash.key?(k)
       end
 
-      # Gets the string value for the specified key.
+      # Gets the string value for the specified key, including those defined in a superclass.
       #
       # === Parameters
       # [k] The key symbol to get the value for.
       #
       # Returns the corresponding enum instance or nil.
       def value(k)
-        enum = @_enum_hash[k]
+        enum = _enum_hash[k]
         enum&.value
       end
 
-      # Whether the specified value exists in this enum.
+      # Whether the specified value exists in this enum, including those defined in a superclass.
       #
       # === Parameters
       # [k] The string value to check.
       #
       # Returns true if the value exists, false otherwise.
       def value?(v)
-        @_enums_by_value.key?(v)
+        _enums_by_value.key?(v)
       end
 
-      # Gets the key symbol for the specified value.
+      # Gets the key symbol for the specified value, including those defined in a superclass.
       #
       # === Parameters
       # [v] The string value to parse.
       #
       # Returns the corresponding key symbol or nil.
       def key(v)
-        enum = @_enums_by_value[v]
+        enum = _enums_by_value[v]
         enum&.key
       end
 
-      # Returns all enum keys.
+      # Returns all enum keys, including those defined in a superclass.
       def keys
-        @_enum_hash.values.map(&:key)
+        _enum_hash.values.map(&:key)
       end
 
       # Returns all enum values.
       def values
-        result = @_enum_hash.values.map(&:value)
+        result = _own_enum_hash.values.map(&:value)
 
         if superclass < Ruby::Enum
           superclass.values + result
@@ -135,40 +135,77 @@ module Ruby
         end
       end
 
-      # Iterate over all enumerated values.
+      # Iterate over all enumerated values, including those defined in a superclass.
       # Required for Enumerable mixin
       def each_value(&_block)
-        @_enum_hash.each_value do |v|
+        _enum_hash.each_value do |v|
           yield v.value
         end
       end
 
-      # Iterate over all enumerated keys.
+      # Iterate over all enumerated keys, including those defined in a superclass.
       # Required for Enumerable mixin
       def each_key(&_block)
-        @_enum_hash.each_value do |v|
+        _enum_hash.each_value do |v|
           yield v.key
         end
       end
 
+      # Returns a hash of key:values, including those defined in a superclass.
       def to_h
-        @_enum_hash.transform_values(&:value)
+        _enum_hash.transform_values(&:value)
       end
 
       private
 
+      # Returns this class' own enum hash, defaulting to an empty hash.
+      #
+      # A subclass that does not `define` any of its own enums does not have
+      # its `@_own_enum_hash` instance variable set, since it's only initialized
+      # in `define` and in the `included` hook.
+      def _own_enum_hash
+        @_own_enum_hash ||= {}
+      end
+
+      # Returns this class' own enums-by-value hash, defaulting to an empty hash.
+      def _own_enums_by_value
+        @_own_enums_by_value ||= {}
+      end
+
+      # Returns the enum hash for this class merged with all of its superclasses,
+      # with keys defined in this class taking precedence over those inherited
+      # from a superclass.
+      def _enum_hash
+        @_enum_hash ||= if superclass < Ruby::Enum
+                          superclass.send(:_enum_hash).merge(_own_enum_hash)
+                        else
+                          _own_enum_hash
+                        end
+      end
+
+      # Returns the enums-by-value hash for this class merged with all of its
+      # superclasses, with values defined in this class taking precedence over
+      # those inherited from a superclass.
+      def _enums_by_value
+        @_enums_by_value ||= if superclass < Ruby::Enum
+                               superclass.send(:_enums_by_value).merge(_own_enums_by_value)
+                             else
+                               _own_enums_by_value
+                             end
+      end
+
       def upper?(s)
         !/[[:upper:]]/.match(s).nil?
       end
 
       def validate_key!(key)
-        return unless @_enum_hash.key?(key)
+        return unless _own_enum_hash.key?(key)
 
         raise Ruby::Enum::Errors::DuplicateKeyError, name: name, key: key
       end
 
       def validate_value!(value)
-        return unless @_enums_by_value.key?(value)
+        return unless _own_enums_by_value.key?(value)
 
         raise Ruby::Enum::Errors::DuplicateValueError, name: name, value: value
       end

data/lib/ruby-enum/version.rb

@@ -2,6 +2,6 @@
 
 module Ruby
   module Enum
-    VERSION = '1.1.0'
+    VERSION = '1.2.0'
   end
 end