equitable 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e534220f01acc864d7c2207df2357e64e1629bf52ed12f1819710cd6aebfffa2
+  data.tar.gz: '079708acf5302fffd47cf41ad4a546fc71e84b73d16229c0001faa8fb4b1c66b'
+SHA512:
+  metadata.gz: 22271dd2594bcaa8083313171f5aa3cd190131a9f3b8632360e25069ea490cec7578e4dfd03ae558a63e2f5d34af9034b0280229543853da2295a0d54a73f256
+  data.tar.gz: 9017cba0ec0cd5aef2b9f04e4277df95cef3c714abf5d4d4f200ee4f5048bda0de58108d999d93a2c2fb8dee26534bbd7826926df1bcddbc430ecfee26d54521

data/.mutant.yml

@@ -0,0 +1,23 @@
+usage: opensource
+integration:
+  name: minitest
+includes:
+  - lib
+  - test
+requires:
+  - equitable
+  - test_helper
+  - equitable_test
+matcher:
+  subjects:
+    - "Equitable*"
+mutation:
+  timeout: 10.0
+  ignore_patterns:
+    # module_eval's __LINE__ + 1 argument only affects debugging metadata
+    - send{selector=module_eval}
+coverage_criteria:
+  test_result: true
+  process_abort: true
+environment_variables:
+  MUTANT: "true"

data/.rubocop.yml

@@ -0,0 +1,28 @@
+inherit_gem:
+  standard: config/base.yml
+  standard-performance: config/base.yml
+
+plugins:
+  - rubocop-minitest
+  - rubocop-performance
+  - rubocop-rake
+
+AllCops:
+  TargetRubyVersion: 3.3
+  NewCops: enable
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Style/Documentation:
+  Enabled: true
+
+Minitest/MultipleAssertions:
+  Max: 4
+
+Naming/MethodParameterName:
+  Exclude:
+    - "test/**/*"

data/.yardopts

@@ -0,0 +1,4 @@
+--markup markdown
+--no-private
+--protected
+lib/**/*.rb

data/.yardstick.yml

@@ -0,0 +1,34 @@
+---
+threshold: 100
+require_exact_threshold: false
+rules:
+  ApiTag::Presence:
+    enabled: true
+    exclude: []
+  ApiTag::Inclusion:
+    enabled: true
+    exclude: []
+  ApiTag::ProtectedMethod:
+    enabled: true
+    exclude: []
+  ApiTag::PrivateMethod:
+    enabled: true
+    exclude: []
+  ExampleTag:
+    enabled: false
+    exclude: []
+  ReturnTag:
+    enabled: true
+    exclude: []
+  Summary::Presence:
+    enabled: true
+    exclude: []
+  Summary::Length:
+    enabled: true
+    exclude: []
+  Summary::Delimiter:
+    enabled: true
+    exclude: []
+  Summary::SingleLine:
+    enabled: true
+    exclude: []

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Erik Berlin
+
+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,296 @@
+# Equitable
+
+[![Gem Version](https://img.shields.io/gem/v/equitable)](https://rubygems.org/gems/equitable)
+[![Test](https://github.com/sferik/equitable/actions/workflows/test.yml/badge.svg)](https://github.com/sferik/equitable/actions/workflows/test.yml)
+[![Quality](https://github.com/sferik/equitable/actions/workflows/quality.yml/badge.svg)](https://github.com/sferik/equitable/actions/workflows/quality.yml)
+[![Documentation](https://github.com/sferik/equitable/actions/workflows/yard.yml/badge.svg)](https://github.com/sferik/equitable/actions/workflows/yard.yml)
+[![Mutation Testing](https://github.com/sferik/equitable/actions/workflows/mutant.yml/badge.svg)](https://github.com/sferik/equitable/actions/workflows/mutant.yml)
+
+Equitable provides equality, equivalence, hashing, pattern matching, and
+inspection methods for Ruby objects based on explicitly specified attributes.
+
+Unlike approaches that automatically use all `attr_reader` attributes,
+Equitable requires explicit specification of which attributes affect equality,
+giving you full control over comparison behavior.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "equitable"
+```
+
+Or install it directly:
+
+```bash
+gem install equitable
+```
+
+## Quick Start
+
+```ruby
+class Point
+  include Equitable.new(:x, :y)
+
+  attr_reader :x, :y
+
+  def initialize(x, y)
+    @x = x
+    @y = y
+  end
+end
+
+p1 = Point.new(1, 2)
+p2 = Point.new(1, 2)
+
+p1 == p2           # => true
+p1.eql?(p2)        # => true
+p1.hash == p2.hash # => true
+```
+
+## Features
+
+### Selective Attribute Comparison
+
+Only the attributes you specify are used for equality. Other instance variables
+are ignored:
+
+> [!TIP]
+> This is useful when you have attributes that shouldn't affect equality, like
+> timestamps, cached values, or display names.
+
+```ruby
+class GeoLocation
+  include Equitable.new(:latitude, :longitude)
+
+  attr_reader :latitude, :longitude, :name
+
+  def initialize(latitude, longitude, name = nil)
+    @latitude = latitude
+    @longitude = longitude
+    @name = name
+  end
+end
+
+home = GeoLocation.new(37.7786, -122.4407, "Home")
+work = GeoLocation.new(37.7786, -122.4407, "Work")
+
+home == work  # => true (name is not part of equality)
+```
+
+### Equality vs Equivalence
+
+Equitable provides two comparison methods with different semantics:
+
+#### `==` (Equality)
+
+Returns `true` if the other object is an instance of the same class **or a
+subclass**, and all specified attributes are equal using `==`:
+
+```ruby
+class ColoredPoint < Point
+  attr_reader :color
+
+  def initialize(x, y, color)
+    super(x, y)
+    @color = color
+  end
+end
+
+point = Point.new(1, 2)
+colored = ColoredPoint.new(1, 2, "red")
+
+point == colored   # => true (ColoredPoint is a subclass of Point)
+colored == point   # => false (Point is not a subclass of ColoredPoint)
+```
+
+> [!IMPORTANT]
+> In Ruby, the `==` operator is asymmetric when comparing across class
+> hierarchies. A parent class instance can equal a subclass instance, but not
+> vice versa.
+
+#### `eql?` (Equivalence)
+
+Returns `true` only if both objects are instances of the **exact same class**,
+and all specified attributes are equal using `eql?`:
+
+```ruby
+point = Point.new(1, 2)
+colored = ColoredPoint.new(1, 2, "red")
+
+point.eql?(colored)   # => false (different classes)
+colored.eql?(point)   # => false (different classes)
+
+point.eql?(Point.new(1, 2))  # => true (same class, same values)
+```
+
+### Hashing
+
+Objects that are `eql?` will have the same hash code, making them safe for use
+as Hash keys and in Sets:
+
+> [!NOTE]
+> Ruby's `Hash` and `Set` use `eql?` and `hash` together. Equitable ensures
+> these methods stay consistent—objects that are `eql?` always have matching
+> hash codes.
+
+```ruby
+require "set"
+
+p1 = Point.new(1, 2)
+p2 = Point.new(1, 2)
+
+# As Hash keys
+locations = {}
+locations[p1] = "first"
+locations[p2] = "second"
+locations.size  # => 1 (p1 and p2 are the same key)
+
+# In Sets
+set = Set.new
+set << p1
+set << p2
+set.size  # => 1
+```
+
+### Pattern Matching
+
+Equitable provides full support for Ruby's pattern matching syntax.
+
+> [!TIP]
+> Use array patterns `[x, y]` for positional matching when attribute order
+> matters. Use hash patterns `{x:, y:}` for named matching when you want
+> clarity or only need specific attributes.
+
+#### Array Patterns
+
+Use `deconstruct` for array-style pattern matching:
+
+```ruby
+point = Point.new(3, 4)
+
+case point
+in [0, 0]
+  puts "origin"
+in [x, 0]
+  puts "on x-axis at #{x}"
+in [0, y]
+  puts "on y-axis at #{y}"
+in [x, y]
+  puts "at (#{x}, #{y})"
+end
+# => "at (3, 4)"
+```
+
+#### Hash Patterns
+
+Use `deconstruct_keys` for hash-style pattern matching:
+
+```ruby
+point = Point.new(3, 4)
+
+case point
+in { x: 0, y: 0 }
+  puts "origin"
+in { x:, y: } if x == y
+  puts "on diagonal at #{x}"
+in { x:, y: }
+  puts "at (#{x}, #{y})"
+end
+# => "at (3, 4)"
+```
+
+#### Class Patterns
+
+Combine with class checks:
+
+```ruby
+case point
+in Point(x: 0, y: 0)
+  puts "origin point"
+in Point(x:, y:)
+  puts "point at (#{x}, #{y})"
+end
+```
+
+### Clean Inspect Output
+
+Equitable customizes `inspect` to show only the attributes used for equality:
+
+```ruby
+class User
+  include Equitable.new(:id)
+
+  attr_reader :id, :name, :email, :created_at
+
+  def initialize(id, name, email)
+    @id = id
+    @name = name
+    @email = email
+    @created_at = Time.now
+  end
+end
+
+user = User.new(42, "Alice", "alice@example.com")
+user.inspect
+# => "#<User:0x00007f... @id=42>"
+# Note: name, email, and created_at are not shown
+```
+
+> [!NOTE]
+> When debugging, remember that `inspect` only shows equality attributes. Use
+> `instance_variables` to see all instance variables if needed.
+
+### Clean Ancestor Chain
+
+The included module has a descriptive name in the ancestor chain:
+
+```ruby
+Point.ancestors
+# => [Point, Equitable(x, y), Object, Kernel, BasicObject]
+```
+
+## Nested Equitable Objects
+
+Equitable objects can be nested and will compare correctly:
+
+```ruby
+class Line
+  include Equitable.new(:start_point, :end_point)
+
+  attr_reader :start_point, :end_point
+
+  def initialize(start_point, end_point)
+    @start_point = start_point
+    @end_point = end_point
+  end
+end
+
+line1 = Line.new(Point.new(0, 0), Point.new(1, 1))
+line2 = Line.new(Point.new(0, 0), Point.new(1, 1))
+
+line1 == line2  # => true
+```
+
+## Error Handling
+
+> [!CAUTION]
+> Equitable validates arguments at include time. Errors will be raised
+> immediately if you pass invalid arguments.
+
+Equitable validates its arguments:
+
+```ruby
+# At least one attribute is required
+Equitable.new()
+# => ArgumentError: at least one attribute is required
+
+# Attributes must be Symbols
+Equitable.new("name")
+# => ArgumentError: attribute must be a Symbol, got String
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE).

data/Rakefile

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+require "standard/rake"
+require "rubocop/rake_task"
+require "yard"
+require "yardstick/rake/verify"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.warning = true
+end
+
+RuboCop::RakeTask.new(:rubocop) do |task|
+  task.options = %w[--display-cop-names]
+end
+
+YARD::Rake::YardocTask.new(:yard) do |t|
+  t.files = ["lib/**/*.rb"]
+  t.options = ["--no-private", "--markup", "markdown"]
+end
+
+Yardstick::Rake::Verify.new(:yardstick) do |verify|
+  verify.threshold = 100
+  verify.require_exact_threshold = false
+end
+
+desc "Run Steep type checker"
+task :steep do
+  sh "steep check"
+end
+
+desc "Run mutation testing"
+task :mutant do
+  ENV["MUTANT"] = "true"
+  sh "bundle exec mutant run"
+end
+
+desc "Run all quality checks"
+task quality: %i[rubocop steep yardstick]
+
+desc "Run all checks (tests, quality, mutation)"
+task default: %i[test quality mutant]

data/Steepfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+D = Steep::Diagnostic
+
+target :lib do
+  signature "sig"
+  check "lib"
+
+  configure_code_diagnostics(D::Ruby.strict)
+end

data/lib/equitable.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+# Equitable provides equality, equivalence, hashing, pattern matching, and
+# inspection methods for Ruby objects based on specified attributes.
+#
+# @example Basic usage
+#   class GeoLocation
+#     include Equitable.new(:latitude, :longitude)
+#
+#     attr_reader :latitude, :longitude, :name
+#
+#     def initialize(latitude, longitude, name = nil)
+#       @latitude = latitude
+#       @longitude = longitude
+#       @name = name
+#     end
+#   end
+#
+#   loc1 = GeoLocation.new(1.0, 2.0, "Home")
+#   loc2 = GeoLocation.new(1.0, 2.0, "Work")
+#   loc1 == loc2  # => true (name is not part of equality)
+#
+# @example Pattern matching
+#   case location
+#   in GeoLocation(latitude:, longitude:) then "#{latitude}, #{longitude}"
+#   in [lat, lon]                         then "coords: #{lat}, #{lon}"
+#   end
+#
+# @api public
+module Equitable
+  # The current version of the Equitable gem
+  VERSION = "1.0.0"
+
+  # Creates a module providing equality methods based on the given attributes
+  #
+  # @example Basic usage
+  #   class Point
+  #     include Equitable.new(:x, :y)
+  #     attr_reader :x, :y
+  #   end
+  #
+  # @param keys [Array<Symbol>] attribute names to use for equality
+  # @return [Module] a module to include in your class
+  # @raise [ArgumentError] if keys is empty or contains non-Symbols
+  #
+  # @api public
+  def self.new(*keys)
+    validate_keys!(keys)
+    build_module(keys.freeze)
+  end
+
+  # Validates that keys are non-empty and all Symbols
+  #
+  # @param keys [Array<Object>] the keys to validate
+  # @return [void]
+  # @raise [ArgumentError] if keys is empty or contains non-Symbols
+  #
+  # @api private
+  def self.validate_keys!(keys)
+    raise ArgumentError, "at least one attribute is required" if keys.empty?
+
+    invalid = keys.find { |key| !key.is_a?(Symbol) }
+    raise ArgumentError, "attribute must be a Symbol, got #{invalid.class}" if invalid
+  end
+  private_class_method :validate_keys!
+
+  # Instance methods mixed into classes that include an Equitable module
+  #
+  # @api private
+  module InstanceMethods
+    # Equality comparison allowing subclasses
+    #
+    # @param other [Object] object to compare
+    # @return [Boolean] true if other is_a? same class with equal attributes
+    def ==(other)
+      other.is_a?(self.class) && equitable_keys.all? { |key| public_send(key) == other.public_send(key) }
+    end
+
+    # Strict equality requiring exact class match
+    #
+    # @param other [Object] object to compare
+    # @return [Boolean] true if other is exact same class with eql? attributes
+    def eql?(other)
+      other.instance_of?(self.class) && equitable_keys.all? { |key| public_send(key).eql?(other.public_send(key)) }
+    end
+
+    # Hash code based on class and attribute values
+    #
+    # @return [Integer] hash code
+    def hash
+      [self.class, *deconstruct].hash
+    end
+
+    # Array deconstruction for pattern matching
+    #
+    # @return [Array] attribute values in order
+    def deconstruct
+      equitable_keys.map { |key| public_send(key) }
+    end
+
+    # Hash deconstruction for pattern matching
+    #
+    # @param requested [Array<Symbol>, nil] keys to include, or nil for all
+    # @return [Hash{Symbol => Object}] requested attribute key-value pairs
+    def deconstruct_keys(requested)
+      subset = requested.nil? ? equitable_keys : equitable_keys & requested
+      subset.to_h { |key| [key, public_send(key)] }
+    end
+
+    # String representation showing only equitable attributes
+    #
+    # @return [String] inspect output
+    def inspect
+      attrs = equitable_keys.map { |key| "@#{key}=#{public_send(key).inspect}" }.join(", ")
+      Object.instance_method(:to_s).bind_call(self).sub(/>\z/, " #{attrs}>")
+    end
+
+    # Pretty print output using PP's object formatting
+    #
+    # @param q [PP] pretty printer
+    # @return [void]
+    def pretty_print(q)
+      q.pp_object(self)
+    end
+
+    # Instance variables to display in pretty print output
+    #
+    # @return [Array<Symbol>] instance variable names
+    def pretty_print_instance_variables
+      equitable_keys.map { |key| :"@#{key}" }
+    end
+  end
+
+  # Builds the module with equality methods for the given keys
+  #
+  # @param keys [Array<Symbol>] attribute names (frozen)
+  # @return [Module] the configured module
+  #
+  # @api private
+  def self.build_module(keys)
+    Module.new do
+      include InstanceMethods
+
+      set_temporary_name("Equitable(#{keys.join(", ")})")
+
+      define_method(:equitable_keys) { keys }
+      private :equitable_keys
+    end
+  end
+  private_class_method :build_module
+end

data/sig/equitable.rbs

@@ -0,0 +1,57 @@
+# Type signatures for the Equitable gem
+#
+# Equitable provides equality, equivalence, hashing, and inspection methods
+# for Ruby objects based on specified attributes.
+
+module Equitable
+  # The current version of the Equitable gem.
+  VERSION: String
+
+  # Define equality methods for the given attributes.
+  #
+  # Creates a module that, when included, adds equality methods
+  # based on the specified attributes.
+  def self.new: (*Symbol keys) -> Module
+
+  # Private method to validate keys
+  def self.validate_keys!: (Array[untyped] keys) -> void
+
+  # Private method to build the module
+  def self.build_module: (Array[Symbol] keys) -> Module
+
+  # Instance methods mixed into classes that include an Equitable module.
+  # Assumes equitable_keys is provided by the dynamic module.
+  module InstanceMethods : _Equitable
+  end
+end
+
+# Interface for classes that include an Equitable module
+interface _Equitable
+  # Returns the attribute keys used for equality comparison (private).
+  def equitable_keys: () -> Array[Symbol]
+
+  # Equivalence check - allows subclass instances.
+  def ==: (untyped other) -> bool
+
+  # Strict equality check - requires exact same class.
+  def eql?: (untyped other) -> bool
+
+  # Generate a hash code based on class and attribute values.
+  def hash: () -> Integer
+
+  # Array deconstruction for pattern matching.
+  def deconstruct: () -> Array[untyped]
+
+  # Hash deconstruction for pattern matching.
+  def deconstruct_keys: (Array[Symbol]? requested) -> Hash[Symbol, untyped]
+
+  # Custom inspect output showing equitable attributes.
+  def inspect: () -> String
+
+  # Pretty print output using PP's object formatting.
+  def pretty_print: (untyped q) -> void
+
+  # Returns instance variable names for PP (pretty print).
+  def pretty_print_instance_variables: () -> Array[Symbol]
+end
+

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: equitable
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Erik Berlin
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Equitable provides a simple way to define equality (==), equivalence (eql?),
+  and hashing (hash) methods for Ruby objects based on specified attributes.
+  Includes pattern matching support and clean inspect output across Ruby versions.
+email:
+- sferik@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".mutant.yml"
+- ".rubocop.yml"
+- ".yardopts"
+- ".yardstick.yml"
+- LICENSE
+- README.md
+- Rakefile
+- Steepfile
+- lib/equitable.rb
+- sig/equitable.rbs
+homepage: https://github.com/sferik/equitable
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/sferik/equitable
+  source_code_uri: https://github.com/sferik/equitable
+  changelog_uri: https://github.com/sferik/equitable/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.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.4
+specification_version: 4
+summary: Define equality, equivalence, and hashing methods for Ruby objects
+test_files: []