equalizer 0.0.11 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: dcbcd58301e2a2cef28808c325df7a4c51eb7714
-  data.tar.gz: e0790eb41a358a41e568eb3393e35fb424c1abc5
+SHA256:
+  metadata.gz: 152edf98048a51f0c55c1f028dc3b4a6fe6322910eb397a3f9d7a9f0e37c6b1b
+  data.tar.gz: 42ba9d636346bf0fdbfe8bdf216b1a56c5f25847c3afdf91afbaea3740e97b1b
 SHA512:
-  metadata.gz: 6ef3745470a9bb334dfaa746c0246d4255f960fdcd9b4bac246ebcac5865e241ac415831a092c6997aec276db2fb0d77e8009fac76b46e694233ae99b0c92077
-  data.tar.gz: dc186fa2bd0482794f6f63c84db4f6bddee1eaf4c696ab8bae031e44e4656c1800430bc73b1ef1aeeb776b4343a8ec079e78efb4b85e09edb44f42c2c818a07b
+  metadata.gz: 4c599000f12a99e99fcf8f55a64dbf6075032c5e74ab3af5ab02dc0bc2152cfb3b7148c81ea43cd3850250eb4e4f7b3e2ccd32fc61c66e8faf2f52da6bac183a
+  data.tar.gz: 3a5919fb70d6b203eb574913abd78d65e943d2cfa7a5ea4d1582cfb87a99bca4876effc233f477b804d561338236050de18648ea65b10a369a5cdbe558f8eecb

data/.mutant.yml

@@ -0,0 +1,24 @@
+usage: opensource
+integration:
+  name: minitest
+includes:
+  - lib
+  - test
+requires:
+  - equalizer
+  - test_helper
+  - equalizer_test
+matcher:
+  subjects:
+    - "Equalizer*"
+mutation:
+  operators: full
+  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
+
+Layout/LineLength:
+  Max: 80
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Style/Documentation:
+  Enabled: true
+
+Naming/MethodParameterName:
+  Exclude:
+    - "test/**/*"

data/.yardopts

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

data/.yardstick.yml

@@ -1,2 +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/CHANGELOG.md

@@ -0,0 +1,148 @@
+# 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.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-03-20
+
+### Added
+
+- Pattern matching support via `deconstruct` and `deconstruct_keys`
+- Pretty print support via `pretty_print` and `pretty_print_instance_variables`
+- Input validation requiring at least one Symbol attribute
+- RBS type signatures
+- Steep type checking
+- Descriptive module names in ancestor chain (e.g., `Equalizer(x, y)`)
+- Sigstore gem signing on release
+
+### Changed
+
+- Rewritten from a `Module` subclass to a plain `module` with `Equalizer.new`
+  returning anonymous modules
+- Minimum Ruby version raised to 3.3
+- `hash` method now uses `[self.class, *deconstruct].hash` for improved clarity
+- `inspect` output format uses `Object#to_s` base with `@attr=value` pairs
+- Uses `public_send` instead of `__send__` for attribute access
+- Switched test framework from RSpec to Minitest
+- Replaced `Equalizer::Methods` module with `Equalizer::InstanceMethods`
+- Inlined `VERSION` constant (removed separate `version.rb` file)
+
+### Removed
+
+- `coerce` support in `==` method
+- `cmp?` private method (replaced with direct attribute comparisons)
+- `Equalizer::Methods` module (replaced by `Equalizer::InstanceMethods`)
+- devtools dependency
+
+## [0.0.11] - 2015-03-23
+
+### Changed
+
+- Kill all surviving mutations in Equalizer
+- Added mbj/devtools gem dependency
+- Added bundler caching and container-based CI builds
+- Fixed rspec deprecated API usage
+
+## [0.0.10] - 2015-03-20
+
+### Added
+
+- Support for Ruby 2.1 and 2.2
+
+### Fixed
+
+- Fixed use of coerce method
+
+### Changed
+
+- Updated RSpec dependency to ~> 3.0
+- Updated RuboCop dependency to >= 0.25
+- Updated SimpleCov dependency to >= 0.9
+
+### Removed
+
+- Dropped support for Ruby 1.9.2
+
+## [0.0.9] - 2013-12-23
+
+### Changed
+
+- Changed `#hash` method to use `Array#hash` for better uniformity
+- Refactored block to use a Method object
+- Removed devtools as a development dependency
+- Added supported Ruby versions section to README
+
+## [0.0.8] - 2013-12-02
+
+### Fixed
+
+- Fixed mutation in equality and equivalency methods
+- Fixed mutation in comparison method
+
+### Changed
+
+- Refactored explicit method to be an included hook method
+- Added spec for `Equalizer#included`
+- Changed spec to verify private attributes can be compared
+
+## [0.0.7] - 2013-08-22
+
+### Changed
+
+- Removed adamantium dependency
+- Removed unused backports dependency
+- Kill mutations in `Equalizer#define_cmp_method`
+- Added license to gemspec
+- Added mutant config and enabled mutation testing
+
+### Removed
+
+- Stopped testing Ruby 1.8
+
+## [0.0.5] - 2013-03-01
+
+### Changed
+
+- Bumped backports dependency to ~> 3.0, >= 3.0.3
+- Bumped yard dependency to ~> 0.8.5
+
+## [0.0.4] - 2013-02-16
+
+### Changed
+
+- Added encoding to all Ruby source files
+- Upgraded gem dependencies
+
+## [0.0.3] - 2013-01-20
+
+### Fixed
+
+- Fixed `#hash` and `#inspect` methods to have the expected arity
+
+## [0.0.2] - 2012-12-25
+
+### Changed
+
+- Changed `#==` to have stricter behavior for subtypes
+
+## [0.0.1] - 2012-11-22
+
+### Added
+
+- Initial release, extracted from veritas
+- Define equality (`==`), equivalence (`eql?`), hashing (`hash`), and
+  inspection (`inspect`) methods based on specified attributes
+
+[1.0.0]: https://github.com/dkubb/equalizer/compare/v0.0.11...v1.0.0
+[0.0.11]: https://github.com/dkubb/equalizer/compare/v0.0.10...v0.0.11
+[0.0.10]: https://github.com/dkubb/equalizer/compare/v0.0.9...v0.0.10
+[0.0.9]: https://github.com/dkubb/equalizer/compare/v0.0.8...v0.0.9
+[0.0.8]: https://github.com/dkubb/equalizer/compare/v0.0.7...v0.0.8
+[0.0.7]: https://github.com/dkubb/equalizer/compare/v0.0.5...v0.0.7
+[0.0.5]: https://github.com/dkubb/equalizer/compare/v0.0.4...v0.0.5
+[0.0.4]: https://github.com/dkubb/equalizer/compare/v0.0.3...v0.0.4
+[0.0.3]: https://github.com/dkubb/equalizer/compare/v0.0.2...v0.0.3
+[0.0.2]: https://github.com/dkubb/equalizer/compare/v0.0.1...v0.0.2
+[0.0.1]: https://github.com/dkubb/equalizer/releases/tag/v0.0.1

data/LICENSE

@@ -1,21 +1,21 @@
-Copyright (c) 2009-2013 Dan Kubb
-Copyright (c) 2012 Markus Schirp (packaging)
+MIT License
 
-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:
+Copyright (c) 2009-2026 Dan Kubb, Markus Schirp, Piotr Solnica, Erik Berlin
 
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
+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 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.
+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

@@ -1,69 +1,316 @@
-equalizer
-=========
+# Equalizer
 
-Module to define equality, equivalence and inspection methods
+[![Gem Version](https://img.shields.io/gem/v/equalizer)](https://rubygems.org/gems/equalizer)
+[![Test](https://github.com/dkubb/equalizer/actions/workflows/test.yml/badge.svg)](https://github.com/dkubb/equalizer/actions/workflows/test.yml)
+[![Quality](https://github.com/dkubb/equalizer/actions/workflows/quality.yml/badge.svg)](https://github.com/dkubb/equalizer/actions/workflows/quality.yml)
+[![Documentation](https://github.com/dkubb/equalizer/actions/workflows/yard.yml/badge.svg)](https://github.com/dkubb/equalizer/actions/workflows/yard.yml)
+[![Mutation Testing](https://github.com/dkubb/equalizer/actions/workflows/mutant.yml/badge.svg)](https://github.com/dkubb/equalizer/actions/workflows/mutant.yml)
 
-[![Gem Version](http://img.shields.io/gem/v/equalizer.svg)][gem]
-[![Build Status](http://img.shields.io/travis/dkubb/equalizer.svg)][travis]
-[![Dependency Status](http://img.shields.io/gemnasium/dkubb/equalizer.svg)][gemnasium]
-[![Code Climate](http://img.shields.io/codeclimate/github/dkubb/equalizer.svg)][codeclimate]
-[![Coverage Status](http://img.shields.io/coveralls/dkubb/equalizer.svg)][coveralls]
+Equalizer provides equality, equivalence, hashing, pattern matching, and
+inspection methods for Ruby objects based on explicitly specified attributes.
 
-[gem]: https://rubygems.org/gems/equalizer
-[travis]: https://travis-ci.org/dkubb/equalizer
-[gemnasium]: https://gemnasium.com/dkubb/equalizer
-[codeclimate]: https://codeclimate.com/github/dkubb/equalizer
-[coveralls]: https://coveralls.io/r/dkubb/equalizer
+Unlike approaches that automatically use all `attr_reader` attributes,
+Equalizer requires explicit specification of which attributes affect equality,
+giving you full control over comparison behavior.
 
-Examples
---------
+## Installation
 
-``` ruby
+Add this line to your application's Gemfile:
+
+```ruby
+gem "equalizer"
+```
+
+Or install it directly:
+
+```bash
+gem install equalizer
+```
+
+## Quick Start
+
+```ruby
+class Point
+  include Equalizer.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 Equalizer.new(:latitude, :longitude)
 
-  attr_reader :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
 
-  def initialize(latitude, longitude)
-    @latitude, @longitude = latitude, longitude
+Equalizer 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_a = GeoLocation.new(1, 2)
-point_b = GeoLocation.new(1, 2)
-point_c = GeoLocation.new(2, 2)
+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.
 
-point_a.inspect    # => "#<GeoLocation latitude=1 longitude=2>"
+#### `eql?` (Equivalence)
 
-point_a == point_b           # => true
-point_a.hash == point_b.hash # => true
-point_a.eql?(point_b)        # => true
-point_a.equal?(point_b)      # => false
+Returns `true` only if both objects are instances of the **exact same class**,
+and all specified attributes are equal using `eql?`:
 
-point_a == point_c           # => false
-point_a.hash == point_c.hash # => false
-point_a.eql?(point_c)        # => false
-point_a.equal?(point_c)      # => false
+```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)
 ```
 
-Supported Ruby Versions
------------------------
+### Hashing
 
-This library aims to support and is [tested against][travis] the following Ruby
-implementations:
+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. Equalizer 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
+
+Equalizer 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
 
-* Ruby 1.8.7
-* Ruby 1.9.3
-* Ruby 2.0.0
-* Ruby 2.1
-* Ruby 2.2
-* [JRuby][]
-* [Rubinius][]
-* [Ruby Enterprise Edition][ree]
+Use `deconstruct_keys` for hash-style pattern matching:
 
-[jruby]: http://jruby.org/
-[rubinius]: http://rubini.us/
-[ree]: http://www.rubyenterpriseedition.com/
+```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
+
+Equalizer customizes `inspect` to show only the attributes used for equality:
+
+```ruby
+class User
+  include Equalizer.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.
+
+To keep the original `inspect` and `pretty_print` methods, pass `inspect: false`:
+
+```ruby
+class Person < Struct.new(:id, :name)
+  include Equalizer.new(:id, inspect: false)
+end
+
+amy = Person.new(1, "Amy")
+amy.inspect
+# => "#<struct Person id=1, name=\"Amy\">"
+```
+
+### Clean Ancestor Chain
+
+The included module has a descriptive name in the ancestor chain:
+
+```ruby
+Point.ancestors
+# => [Point, Equalizer(x, y), Object, Kernel, BasicObject]
+```
+
+## Nested Equalizer Objects
+
+Equalizer objects can be nested and will compare correctly:
+
+```ruby
+class Line
+  include Equalizer.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]
+> Equalizer validates arguments at include time. Errors will be raised
+> immediately if you pass invalid arguments.
+
+Equalizer validates its arguments:
+
+```ruby
+# At least one attribute is required
+Equalizer.new()
+# => ArgumentError: at least one attribute is required
+
+# Attributes must be Symbols
+Equalizer.new("name")
+# => ArgumentError: attribute must be a Symbol, got String
+```
+
+## Supported Ruby Versions
+
+This library aims to support and is [tested against][test] the following Ruby
+implementations:
+
+* Ruby 3.3
+* Ruby 3.4
+* Ruby 4.0
 
 If something doesn't work on one of these versions, it's a bug.
 
@@ -79,20 +326,15 @@ patches in a timely fashion. If critical issues for a particular implementation
 exist at the time of a major release, support for that Ruby version may be
 dropped.
 
-Credits
--------
+[test]: https://github.com/dkubb/equalizer/actions/workflows/test.yml
+
+## Credits
 
 * Dan Kubb ([dkubb](https://github.com/dkubb))
-* Piotr Solnica ([solnic](https://github.com/solnic))
 * Markus Schirp ([mbj](https://github.com/mbj))
-* Erik Michaels-Ober ([sferik](https://github.com/sferik))
-
-Contributing
--------------
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+* Piotr Solnica ([solnic](https://github.com/solnic))
+* Erik Berlin ([sferik](https://github.com/sferik))
 
-Copyright
----------
+## License
 
-Copyright &copy; 2009-2013 Dan Kubb. See LICENSE for details.
+The gem is available as open source under the terms of the [MIT License](LICENSE).