exclusive_case 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3e6f61086cef55f398527daf61d443a704f3ee229292b8c1c018274cafe8500b
+  data.tar.gz: b368ec1f93619f448b331d40047e6c0d7793fcf93e8ed130246d08dd81f2ba2d
+SHA512:
+  metadata.gz: a9974d64182c95765dfc1d20737a3d336d8e5cfabeb09d05778f48454fe822503396c75422dcc88100ed6327f04ba7fdf47baab9555e426c8a6135cd8f6616cf
+  data.tar.gz: a5c174dcd2af2969127485719096832635d68c855b858ca7bcc9f44b16c27811902b7d2eaf37e2be6fb7705e4e9ab2de65ad46dd5d5bbbbaea9b5145c42e2bf6

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,31 @@
+AllCops:
+  NewCops: enable
+  SuggestExtensions: false
+
+plugins:
+  - rubocop-rspec
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Max: 120
+
+Style/Documentation:
+  Enabled: true
+
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+
+# Disable RSpec/ExampleLength - allow longer test examples for clarity
+RSpec/ExampleLength:
+  Enabled: false

data/.ruby-version

@@ -0,0 +1 @@
+3.4.5

data/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2025-08-02
+
+### Added
+- **BREAKING**: Optional `of:` parameter for enhanced validation
+- `InvalidCaseError` - raised when cases are not in the allowed `of:` list
+- `MissingCaseError` - raised when not all `of:` values are handled
+- Comprehensive validation ensuring all cases belong to specified list
+- Requirement that all `of:` values must have corresponding cases
+- Full backward compatibility when `of:` parameter is not used
+
+### Changed
+- **BREAKING**: `exhaustive_case` signature now accepts optional `of:` parameter
+
+### Technical
+- 100% test coverage maintained
+- Full RuboCop compliance with comprehensive documentation
+- GitHub Actions CI/CD pipeline with multi-Ruby version testing
+- Automated dependency management via Dependabot
+
+## [0.1.0] - 2025-08-02
+
+### Added
+- Initial implementation of `exhaustive_case` method
+- Support for single and multiple value matching in `on` clauses
+- Automatic error raising for unhandled cases via `UnhandledCaseError`
+- Core gem structure and configuration
+- RSpec testing framework setup
+- RuboCop linting configuration
+- Development scripts (`bin/setup`, `bin/console`)
+
+[Unreleased]: https://github.com/yourusername/exclusive_case/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/yourusername/exclusive_case/releases/tag/v1.0.0
+[0.1.0]: https://github.com/yourusername/exclusive_case/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ajay Sharma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,221 @@
+# Exclusive Case
+
+[![Gem Version](https://badge.fury.io/rb/exclusive_case.svg)](https://badge.fury.io/rb/exclusive_case)
+[![CI](https://github.com/ajsharma/exclusive_case/actions/workflows/ci.yml/badge.svg)](https://github.com/ajsharma/exclusive_case/actions/workflows/ci.yml)
+
+Exhaustive case statements for Ruby to prevent bugs from unhandled cases when new values are added to a system.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'exclusive_case'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install exclusive_case
+```
+
+## Usage
+
+Include the module to get access to the `exhaustive_case` method:
+
+```ruby
+require 'exclusive_case'
+include ExclusiveCase
+
+# Now you can use exhaustive_case
+result = exhaustive_case user_status do
+  on(:active) { "User is active" }
+  on(:inactive) { "User is inactive" }
+  on(:pending) { "User is pending approval" }
+end
+```
+
+or to avoid globally adding the module, it can be included in a class:
+
+```ruby
+require 'exclusive_case'
+
+class UserRenderer
+  include ExclusiveCase
+
+  def handle_status(user_status)
+    # Now you can use exhaustive_case
+    result = exhaustive_case user_status do
+      on(:active) { "User is active" }
+      on(:inactive) { "User is inactive" }
+      on(:pending) { "User is pending approval" }
+    end
+  end
+end
+```
+
+## The problem
+
+If/else statements can easily lead to mistake flows when introducing new cases across the systems.
+
+For instance, with a constant set of inputs `['A', 'B', 'C']`:
+
+```ruby
+if letter == 'A'
+  // handle a
+elsif letter == 'B'
+  // handle b
+else // implicit c
+  // handle c 
+end
+```
+
+However, if a new entry `D` is introduced to the system, now:
+
+```ruby
+if letter == 'A'
+  // code to handle a (whoops!)
+elsif letter == 'B'
+  // code to handle b (whoops!)
+else // implicit c and d
+  // code to handle c  (whoops!)
+end
+```
+
+This kind of code does not reveal itself in tests, providing no feedback to the developer that that a new flow is needed.
+
+We can address this with a more explicit initial switch:
+
+```ruby
+if letter == 'A'
+  // handle a
+elsif letter == 'B'
+  // handle b
+elsif letter == 'C'
+  // handle c
+else 
+  raise "Unknown letter #{letter}"
+end
+```
+
+Now, a new letter would trigger the runtime error, alerting the developer to address this gap.
+
+Note: for these examples, we're using an if/elsif/else chain, but the same concepts apply for `case/when/else` statements:
+
+```ruby
+case letter
+when 'A'
+  // handle a
+when 'B'
+  // handle b
+when 'C'
+  // handle c
+else 
+  raise "Unknown letter #{letter}"
+end
+```
+
+This new syntax is better, but leaves some gaps:
+
+1. Engineers taught to use the class `if/else` structure constantly introduce these problems.
+2. The final raise statement is often "impossible" to access via testing, it's nature preventing access without mocking (especially when these types of clauses are part of private functions).
+
+## The solution
+
+But what if had a new type of case statement that could both ensure that all cases are correctly implemented and provide feedback if a new case has been introduced but not implemented?
+
+Enter exhaustive case:
+
+```ruby
+exhaustive_case letter do 
+  on('A') { // handle A }
+  on('B') { // handle B }
+  on('C') { // handle C }
+end
+```
+
+with the new syntax, `exhaustive_case` handles the final else statement and raises and error if there's an unexpected.
+
+`exhaustive_case` also tries to provide a syntax simple to the native Ruby `case` switch, with multiple matchers supported.
+
+
+```ruby
+exhaustive_case letter do 
+  on('A') { // handle A }
+  on('B', 'C') { // handle B or C }
+end
+```
+
+## Enhanced validation with `of:` parameter
+
+In situations where the central system relies on a series of strategies or an enumerated list, it's often unclear where a growing codebase new logic should be added.
+
+By declaring explicitly the known list of forks, the list of forks can be centralized and then the test suite can provide feedback when a new entry to the list is added or removed.
+
+For even stronger guarantees, you can specify the complete list of acceptable inputs using the `of:` parameter. This ensures that:
+
+1. All declared cases must belong to the specified list
+2. All values in the `of:` list must be handled by at least one case
+
+```ruby
+# Define all possible values upfront
+VALID_LETTERS = ['A', 'B', 'C'].freeze
+
+exhaustive_case letter, of: VALID_LETTERS do 
+  on('A') { // handle A }
+  on('B') { // handle B }
+  on('C') { // handle C }
+end
+```
+
+This will raise an `InvalidCaseError` if:
+- You try to handle a case not in the `of:` list: `on('D') { ... }` 
+- You forget to handle all cases: missing `on('C') { ... }`
+
+The `of:` parameter is optional - without it, `exhaustive_case` works as before, only validating that the input value has a matching case.
+
+### Examples with `of:`
+
+```ruby
+# Status handling with validation
+STATUSES = [:pending, :success, :failure].freeze
+
+result = exhaustive_case status, of: STATUSES do
+  on(:pending) { "Processing..." }
+  on(:success) { "Completed successfully" }
+  on(:failure) { "Failed with error" }
+end
+
+# Multiple values per case still work
+USER_TYPES = [:admin, :moderator, :user, :guest].freeze
+
+permissions = exhaustive_case user_type, of: USER_TYPES do
+  on(:admin) { [:read, :write, :delete, :manage] }
+  on(:moderator, :user) { [:read, :write] }
+  on(:guest) { [:read] }
+end
+```
+
+if a new status is added to `STATUSES` a test suite should reveal that a case is missing.
+
+## Error Handling
+
+The following are the expected errors when using the gem:
+
+- **`UnhandledCaseError`** - Raised when the input value doesn't match any `on` clause
+- **`InvalidCaseError`** - Raised when using `of:` and an `on` clause contains a value not in the allowed list
+- **`MissingCaseError`** - Raised when using `of:` and not all allowed values have corresponding `on` clauses
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/ajsharma/exclusive_case.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+desc "Run tests and linting"
+task default: %i[spec rubocop]

data/exclusive_case.gemspec

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "lib/exclusive_case/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "exclusive_case"
+  spec.version = ExclusiveCase::VERSION
+  spec.authors = ["Ajay Sharma"]
+  spec.email = ["aj@ajsharma.com"]
+
+  spec.summary = "Exhaustive case statements for Ruby to prevent unhandled cases"
+  spec.description =  "A Ruby gem that provides exhaustive case statement functionality to prevent bugs " \
+                      "from unhandled cases when new values are added to a system."
+  spec.homepage = "https://github.com/ajsharma/exclusive_case"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/ajsharma/exclusive_case"
+  spec.metadata["changelog_uri"] = "https://github.com/ajsharma/exclusive_case/blob/main/CHANGELOG.md"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  # Specify which files should be added to the gem when it is released.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) || f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+end

data/lib/exclusive_case/case_builder.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module ExclusiveCase
+  # CaseBuilder handles the construction and execution of exhaustive case statements.
+  # It validates cases against an optional 'of' list and ensures all required cases are handled.
+  #
+  # @api private
+  class CaseBuilder
+    def initialize(value, of)
+      @value = value
+      @of = of
+      @cases = []
+      @matched = false
+    end
+
+    def on(*matchers, &block)
+      validate_matchers(matchers) if @of
+      @cases << { matchers: matchers, block: block }
+    end
+
+    def execute
+      validate_completeness if @of
+
+      @cases.each do |case_def|
+        if case_def[:matchers].any? { |matcher| matcher == @value }
+          @matched = true
+          return case_def[:block].call
+        end
+      end
+
+      raise UnhandledCaseError, "No case handled value: #{@value.inspect}"
+    end
+
+    private
+
+    def validate_matchers(matchers)
+      invalid_matchers = matchers.reject { |matcher| @of.include?(matcher) }
+      return if invalid_matchers.empty?
+
+      raise InvalidCaseError, "Invalid case(s): #{invalid_matchers.map(&:inspect).join(", ")}. " \
+                              "Must be one of: #{@of.map(&:inspect).join(", ")}"
+    end
+
+    def validate_completeness
+      declared_cases = @cases.flat_map { |case_def| case_def[:matchers] }.uniq
+      missing_cases = @of - declared_cases
+      return if missing_cases.empty?
+
+      raise MissingCaseError, "Missing case(s): #{missing_cases.map(&:inspect).join(", ")}. " \
+                              "All values from 'of' must be handled: #{@of.map(&:inspect).join(", ")}"
+    end
+  end
+end

data/lib/exclusive_case/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ExclusiveCase
+  VERSION = "1.0.0"
+end

data/lib/exclusive_case.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "exclusive_case/version"
+require_relative "exclusive_case/case_builder"
+
+# ExclusiveCase provides exhaustive case statement functionality to prevent bugs
+# from unhandled cases when new values are added to a system.
+#
+# @example Basic usage
+#   exhaustive_case letter do
+#     on('A') { "handle A" }
+#     on('B') { "handle B" }
+#     on('C') { "handle C" }
+#   end
+#
+# @example With validation using 'of' parameter
+#   exhaustive_case letter, of: ['A', 'B', 'C'] do
+#     on('A') { "handle A" }
+#     on('B') { "handle B" }
+#     on('C') { "handle C" }
+#   end
+module ExclusiveCase
+  # Generic Error class for the gem
+  class Error < StandardError; end
+
+  # Indicates that an unknown input was passed into the system.
+  #
+  # Correct this by changing the input or know allowed values
+  class UnhandledCaseError < Error; end
+
+  # Indicates that a case was declared that is not in the allowed 'of' list
+  class InvalidCaseError < Error; end
+
+  # Indicates that one or more cases from the initial value list was not
+  # implemented
+  class MissingCaseError < Error; end
+
+  def exhaustive_case(value, of: nil, &block)
+    builder = CaseBuilder.new(value, of)
+    builder.instance_eval(&block)
+    builder.execute
+  end
+end

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: exclusive_case
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Ajay Sharma
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: A Ruby gem that provides exhaustive case statement functionality to prevent
+  bugs from unhandled cases when new values are added to a system.
+email:
+- aj@ajsharma.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- ".ruby-version"
+- CHANGELOG.md
+- LICENSE
+- README.md
+- Rakefile
+- exclusive_case.gemspec
+- lib/exclusive_case.rb
+- lib/exclusive_case/case_builder.rb
+- lib/exclusive_case/version.rb
+homepage: https://github.com/ajsharma/exclusive_case
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/ajsharma/exclusive_case
+  source_code_uri: https://github.com/ajsharma/exclusive_case
+  changelog_uri: https://github.com/ajsharma/exclusive_case/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Exhaustive case statements for Ruby to prevent unhandled cases
+test_files: []