Merge pull request #43 from peterfication/add-exhaustive-case-statement

Add exhaustive case matcher

.rubocop.yml

@@ -12,6 +12,12 @@ Metrics/BlockLength:
   Exclude:
     - 'spec/**/*_spec.rb'
 
+RSpec/SpecFilePathFormat:
+  Enabled: false
+
+RSpec/FilePath:
+  Enabled: false
+
 Style/HashEachMethods:
   Enabled: true
 

.rubocop_todo.yml

@@ -33,14 +33,6 @@ Naming/MethodParameterName:
 RSpec/ExampleLength:
   Max: 11
 
-# Offense count: 2
-# Configuration parameters: Include, CustomTransform, IgnoreMethods, SpecSuffixOnly.
-# Include: **/*_spec*rb*, **/spec/**/*
-RSpec/FilePath:
-  Exclude:
-    - 'spec/ruby-enum/enum_spec.rb'
-    - 'spec/ruby-enum/version_spec.rb'
-
 # Offense count: 4
 RSpec/LeakyConstantDeclaration:
   Exclude:

CHANGELOG.md

@@ -1,5 +1,6 @@
-### 0.9.1 (Next)
+### 1.0.0 (Next)
 
+* [#43](https://github.com/dblock/ruby-enum/pull/43): Add exhaustive case matcher - [@peterfication](https://github.com/peterfication).
 * [#40](https://github.com/dblock/ruby-enum/pull/39): Enable new Rubocop cops and address/allowlist lints - [@petergoldstein](https://github.com/petergoldstein).
 * [#39](https://github.com/dblock/ruby-enum/pull/39): Require Ruby >= 2.7 - [@petergoldstein](https://github.com/petergoldstein).
 * [#38](https://github.com/dblock/ruby-enum/pull/38): Ensure Ruby >= 2.3 - [@ojab](https://github.com/ojab).

README.md

@@ -24,6 +24,8 @@ Enum-like behavior for Ruby, heavily inspired by [this](http://www.rubyfleebie.c
     - [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)
+- [Benchmarks](#benchmarks)
 - [Contributing](#contributing)
 - [Copyright and License](#copyright-and-license)
 - [Related Projects](#related-projects)
@@ -259,6 +261,53 @@ OrderState.values # ['CREATED', 'PAID']
 ShippedOrderState.values # ['CREATED', 'PAID', 'PREPARED', SHIPPED']
 ```
 
+### 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" },
+})
+```
+
+## Benchmarks
+
+Benchmark scripts are defined in the [`benchmarks`](benchmarks) folder and can be run with Rake:
+
+```console
+rake benchmarks:case
+```
+
 ## Contributing
 
 You're encouraged to contribute to ruby-enum. See [CONTRIBUTING](CONTRIBUTING.md) for details.

Rakefile

@@ -16,3 +16,10 @@ require 'rubocop/rake_task'
 RuboCop::RakeTask.new(:rubocop)
 
 task default: %i[rubocop spec]
+
+namespace :benchmark do
+  desc 'Run benchmark for the Ruby::Enum::Case'
+  task :case do
+    require_relative 'benchmarks/case'
+  end
+end

benchmarks/case.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
+require 'benchmark'
+require 'ruby-enum'
+
+##
+# Test enum
+class Color
+  include Ruby::Enum
+  include Ruby::Enum::Case
+
+  define :RED, :red
+  define :GREEN, :green
+  define :BLUE, :blue
+end
+
+puts 'Running 1.000.000 normal case statements'
+case_statement_time = Benchmark.realtime do
+  1_000_000.times do
+    case Color::RED
+    when Color::RED, Color::GREEN
+      'red or green'
+    when Color::BLUE
+      'blue'
+    end
+  end
+end
+
+puts 'Running 1.000.000 ruby-enum case statements'
+ruby_enum_time = Benchmark.realtime do
+  1_000_000.times do
+    Color.case(Color::RED,
+               {
+                 [Color::RED, Color::GREEN] => -> { 'red or green' },
+                 Color::BLUE => -> { 'blue' }
+               })
+  end
+end
+
+puts "ruby-enum case: #{ruby_enum_time.round(4)}"
+puts "case statement: #{case_statement_time.round(4)}"
+
+puts "ruby-enum case is #{(ruby_enum_time / case_statement_time).round(2)} times slower"

lib/ruby-enum.rb

@@ -4,6 +4,7 @@
 
 require 'ruby-enum/version'
 require 'ruby-enum/enum'
+require 'ruby-enum/enum/case'
 
 I18n.load_path << File.join(File.dirname(__FILE__), 'config', 'locales', 'en.yml')
 

lib/ruby-enum/enum/case.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Ruby
+  module Enum
+    ##
+    # Adds a method to an enum class that allows for exhaustive matching on a value.
+    #
+    # @example
+    # class Color
+    #   include Ruby::Enum
+    #   include Ruby::Enum::Case
+    #
+    #   define :RED, :red
+    #   define :GREEN, :green
+    #   define :BLUE, :blue
+    #   define :YELLOW, :yellow
+    # end
+    #
+    # Color.case(Color::RED, {
+    #   [Color::RED, Color::GREEN] => -> { "red or green" },
+    #   Color::BLUE => -> { "blue" },
+    #   Color::YELLOW => -> { "yellow" },
+    # })
+    #
+    # Reserves the :else key for a default case:
+    # Color.case(Color::RED, {
+    #   [Color::RED, Color::GREEN] => -> { "red or green" },
+    #   else: -> { "blue or yellow" },
+    # })
+    module Case
+      def self.included(klass)
+        klass.extend(ClassMethods)
+      end
+
+      ##
+      # @see Ruby::Enum::Case
+      module ClassMethods
+        class ValuesNotDefinedError < StandardError
+        end
+
+        class NotAllCasesHandledError < StandardError
+        end
+
+        def case(value, cases)
+          validate_cases(cases)
+
+          filtered_cases = cases.select do |values, _proc|
+            values = [values] unless values.is_a?(Array)
+            values.include?(value)
+          end
+
+          return call_proc(cases[:else], value) if filtered_cases.none?
+
+          results = filtered_cases.map { |_values, proc| call_proc(proc, value) }
+
+          # Return the first result if there is only one result
+          results.size == 1 ? results.first : results
+        end
+
+        private
+
+        def call_proc(proc, value)
+          return if proc.nil?
+
+          if proc.arity == 1
+            proc.call(value)
+          else
+            proc.call
+          end
+        end
+
+        def validate_cases(cases)
+          all_values = cases.keys.flatten - [:else]
+          else_defined = cases.key?(:else)
+          superfluous_values = all_values - values
+          missing_values = values - all_values
+
+          raise ValuesNotDefinedError, "Value(s) not defined: #{superfluous_values.join(', ')}" if superfluous_values.any?
+          raise NotAllCasesHandledError, "Not all cases handled: #{missing_values.join(', ')}" if missing_values.any? && !else_defined
+        end
+      end
+    end
+  end
+end

lib/ruby-enum/errors/base.rb

@@ -39,7 +39,7 @@ def compose_message(key, attributes = {})
         #
         # Returns a localized error message string.
         def translate(key, options)
-          ::I18n.translate("#{BASE_KEY}.#{key}", **{ locale: :en }.merge(options)).strip
+          ::I18n.translate("#{BASE_KEY}.#{key}", locale: :en, **options).strip
         end
 
         # Create the problem.

lib/ruby-enum/version.rb

@@ -2,6 +2,6 @@
 
 module Ruby
   module Enum
-    VERSION = '0.9.1'
+    VERSION = '1.0.0'
   end
 end

spec/ruby-enum/enum/case_spec.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Ruby::Enum::Case do
+  test_enum =
+    Class.new do
+      include Ruby::Enum
+      include Ruby::Enum::Case
+
+      define :RED, :red
+      define :GREEN, :green
+      define :BLUE, :blue
+    end
+
+  describe '.case' do
+    context 'when all cases are defined' do
+      subject { test_enum.case(test_enum::RED, cases) }
+
+      let(:cases) do
+        {
+          [test_enum::RED, test_enum::GREEN] => -> { 'red or green' },
+          test_enum::BLUE => -> { 'blue' }
+        }
+      end
+
+      it { is_expected.to eq('red or green') }
+
+      context 'when the value is nil' do
+        subject { test_enum.case(nil, cases) }
+
+        it { is_expected.to be_nil }
+      end
+
+      context 'when the value is empty' do
+        subject { test_enum.case('', cases) }
+
+        it { is_expected.to be_nil }
+      end
+
+      context 'when the value is the value of the enum' do
+        subject { test_enum.case(:red, cases) }
+
+        it { is_expected.to eq('red or green') }
+      end
+
+      context 'when the value is used inside the lambda' do
+        subject { test_enum.case(test_enum::RED, cases) }
+
+        let(:cases) do
+          {
+            [test_enum::RED, test_enum::GREEN] => ->(color) { "is #{color}" },
+            test_enum::BLUE => -> { 'blue' }
+          }
+        end
+
+        it { is_expected.to eq('is red') }
+      end
+    end
+
+    context 'when there are mutliple matches' do
+      subject do
+        test_enum.case(
+          test_enum::RED,
+          {
+            [test_enum::RED, test_enum::GREEN] => -> { 'red or green' },
+            test_enum::RED => -> { 'red' },
+            test_enum::BLUE => -> { 'blue' }
+          }
+        )
+      end
+
+      it { is_expected.to eq(['red or green', 'red']) }
+    end
+
+    context 'when not all cases are defined' do
+      it 'raises an error' do
+        expect do
+          test_enum.case(
+            test_enum::RED,
+            { [test_enum::RED, test_enum::GREEN] => -> { 'red or green' } }
+          )
+        end.to raise_error(Ruby::Enum::Case::ClassMethods::NotAllCasesHandledError)
+      end
+    end
+
+    context 'when not all cases are defined but :else is specified (default case)' do
+      it 'does not raise an error' do
+        expect do
+          result = test_enum.case(
+            test_enum::BLUE,
+            {
+              [test_enum::RED, test_enum::GREEN] => -> { 'red or green' },
+              else: -> { 'blue' }
+            }
+          )
+
+          expect(result).to eq('blue')
+        end.not_to raise_error
+      end
+    end
+
+    context 'when a superfluous case is defined' do
+      it 'raises an error' do
+        expect do
+          test_enum.case(
+            test_enum::RED,
+            {
+              [test_enum::RED, test_enum::GREEN] => -> { 'red or green' },
+              test_enum::BLUE => -> { 'blue' },
+              :something => -> { 'green' }
+            }
+          )
+        end.to raise_error(Ruby::Enum::Case::ClassMethods::ValuesNotDefinedError)
+      end
+    end
+  end
+end

spec/ruby-enum/enum_spec.rb

@@ -122,7 +122,7 @@ class SecondSubclass < FirstSubclass
 
   describe '#key' do
     it 'returns enum instances for values' do
-      Colors.each do |_, enum|
+      Colors.each do |_, enum| # rubocop:disable Style/HashEachMethods
         expect(Colors.key(enum.value)).to eq(enum.key)
       end
     end