equatable 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f4686bc5781675b06cad4c4479ead3c786731eeb
-  data.tar.gz: d31b12f2ead5f8b02b4e141a379f2c47c534fad7
+  metadata.gz: 620108deec179ffaf691b2ff6f81495405cf0fa2
+  data.tar.gz: 0a5465d39e4ae3acf50061a6f98e1b4d4a19742e
 SHA512:
-  metadata.gz: 78dff5b3c98ee0bfba57d3c96b12d5a2b5434b0c72a5168afa0713a36464e7e50bc0fdee611d2308089692f41f033a3223004fad39eb54d1cc67a0946860fde3
-  data.tar.gz: 7d24be6e59e61d5a7a563c87d450e464c57cfbcd7731e61450990c7f2a122253fdc7501323342c16ac31bd04919da8170799e9b2ea31764e72eded6fbc573086
+  metadata.gz: e1d9f0e3655edc3d5dfbd85acb490ab6c8e7b13b64b626eccc7c25783a40a7b9fa54c6afbd8d8546bf316bc5e590071e0af3de40c1c0616a71671573b8942d2d
+  data.tar.gz: fc8e67901755723eb5d2c4d3b948d7b789f6685d414593634a837735f5d212b12dc22193ab0b2bd770a5e77dd6ded19ccd22dcfb4209d6b828366d0fc5f11b20

data/.rspec

@@ -1,2 +1,2 @@
 --color
--f s
+--format documentation

data/Gemfile

@@ -3,7 +3,7 @@ source 'https://rubygems.org'
 gemspec
 
 group :development do
-  gem 'rake',  '~> 10.1.0'
-  gem 'rspec', '~> 2.12.0'
+  gem 'rake',  '~> 10.3.2'
+  gem 'rspec', '~> 3.1.0'
   gem 'yard',  '~> 0.8.7'
 end

data/README.md

@@ -27,32 +27,63 @@ Or install it yourself as:
 It is assumed that your objects are value objects and the only values that affect equality comparison are the ones specified by your attribute readers. Each attribute reader should be a significant field in determining objects values.
 
 ```ruby
-class Value
+class Point
   include Equatable
 
-  attr_reader :value
+  attr_reader :x, :y
 
-  def initialize(value)
-    @value = value
+  def initialize(x, y)
+    @x, @y = x, y
   end
 end
 
-val1 = Value.new(11)
-val2 = Value.new(11)
-val3 = Value.new(13)
+point_1 = Point.new(1, 1)
+point_2 = Point.new(1, 1)
+point_3 = Point.new(1, 2)
 
-val1 == val2            # => true
-val1.hash == val2.hash  # => true
-val1 eql? val2          # => true
+point_1 == point_2            # => true
+point_1.hash == point_2.hash  # => true
+point_1.eql?(point_2)         # => true
+point_1.equal?(point_2)       # => false
 
-val1 == val3            # => false
-val1.hash == val3.hash  # => false
-val1 eql? val3          # => false
+point_1 == point_3            # => false
+point_1.hash == point_3.hash  # => false
+point_1.eql?(point_3)         # => false
+point_1.equal?(point_3)       # => false
+
+point_1.inspect  # => "#<Point x=1 y=1>"
 ```
 
+## Attributes
+
 It is important that the attribute readers should allow for performing deterministic computations on class instances. Therefore you should avoid specifying attributes that depend on unreliable resources like IP address that require network access.
 
-Note that adding an extra attribute reader to a subclass will violate the equivalence contract.
+## Subtypes
+
+**Equatable** ensures that any important property of a type holds for its subtypes. However, please note that adding an extra attribute reader to a subclass will violate the equivalence contract, namely, the superclass will be equal to the subclass but reverse won't be true. For example:
+
+```ruby
+class ColorPoint < Point
+  attr_reader :color
+
+  def initialize(x, y, color)
+    super(x, y)
+    @color = color
+  end
+end
+
+point = Point.new(1, 1)
+color_point = ColorPoint.new(1, 1, :red)
+
+point == color_point            # => true
+color_point == point            # => false
+
+point.hash == color_point.hash  # => false
+point.eql?(color_point)         # => false
+point.equal?(color_point)       # => false
+```
+
+The `ColorPoint` class demonstrates that extending a class with extra value property does not preserve the `equals` contract.
 
 ## Contributing
 

data/Rakefile

@@ -1,11 +1,6 @@
 # encoding: utf-8
 
 require "bundler/gem_tasks"
-require "rspec/core/rake_task"
-
-RSpec::Core::RakeTask.new(:spec) do |spec|
-  spec.pattern = FileList['spec/**/*_spec.rb']
-end
 
 FileList['tasks/**/*.rake'].each { |task| import task }
 

data/examples/point.rb

@@ -0,0 +1,48 @@
+$:.unshift File.join(File.dirname(__FILE__), '../lib')
+
+require 'equatable'
+
+class Point
+  include Equatable
+
+  attr_reader :x, :y
+
+  def initialize(x, y)
+    @x, @y = x, y
+  end
+end
+
+class ColorPoint < Point
+  attr_reader :color
+
+  def initialize(x, y, color)
+    super(x, y)
+    @color = color
+  end
+end
+
+point_1 = Point.new(1, 1)
+point_2 = Point.new(1, 1)
+point_3 = Point.new(2, 1)
+
+puts point_1 == point_2
+puts point_1.hash == point_2.hash
+puts point_1.eql?(point_2)
+puts point_1.equal?(point_2)
+
+puts point_1 == point_3
+puts point_1.hash == point_3.hash
+puts point_1.eql?(point_3)
+puts point_1.equal?(point_3)
+
+puts point_1.inspect
+
+point = Point.new(1, 1)
+color_point = ColorPoint.new(1, 1, :red)
+
+puts 'Subtypes'
+puts point == color_point
+puts color_point == point
+puts point.hash == color_point.hash
+puts point.eql?(color_point)
+puts point.equal?(color_point)

data/lib/equatable.rb

@@ -16,11 +16,9 @@ module Equatable
     super
     base.extend(self)
     base.class_eval do
-      define_comparison_attrs
       include Methods
       define_methods
     end
-    self
   end
 
   # Holds all attributes used for comparison.
@@ -41,7 +39,7 @@ module Equatable
   # @api public
   def attr_reader(*args)
     super
-    @comparison_attrs.concat(args)
+    comparison_attrs.concat(args)
   end
 
   # Copy the comparison_attrs into the subclass.
@@ -56,24 +54,25 @@ module Equatable
 
   private
 
-  # Define class instance #comparison_attrs as an empty array.
+  # Define all methods needed for ensuring object's equality.
   #
   # @return [undefined]
   #
   # @api private
-  def define_comparison_attrs
-    instance_variable_set('@comparison_attrs', [])
+  def define_methods
+    define_comparison_attrs
+    define_compare
+    define_hash
+    define_inspect
   end
 
-  # Define all methods needed for ensuring object's equality.
+  # Define class instance #comparison_attrs as an empty array.
   #
   # @return [undefined]
   #
   # @api private
-  def define_methods
-    define_compare
-    define_hash
-    define_inspect
+  def define_comparison_attrs
+    instance_variable_set('@comparison_attrs', [])
   end
 
   # Define a #compare? method to check if the receiver is the same
@@ -85,7 +84,7 @@ module Equatable
   def define_compare
     define_method(:compare?) do |comparator, other|
       klass = self.class
-      attrs = klass.comparison_attrs || []
+      attrs = klass.comparison_attrs
       attrs.all? do |attr|
         other.respond_to?(attr) && send(attr).send(comparator, other.send(attr))
       end
@@ -99,7 +98,7 @@ module Equatable
   def define_hash
     define_method(:hash) do
       klass = self.class
-      attrs = klass.comparison_attrs || []
+      attrs = klass.comparison_attrs
       ([klass] + attrs.map { |attr| send(attr) }).hash
     end
   end
@@ -113,8 +112,8 @@ module Equatable
   def define_inspect
     define_method(:inspect) do
       klass = self.class
-      name = klass.name || klass.inspect
-      attrs = klass.comparison_attrs || []
+      name  = klass.name || klass.inspect
+      attrs = klass.comparison_attrs
       "#<#{name}#{attrs.map { |attr| " #{attr}=#{send(attr).inspect}" }.join}>"
     end
   end
@@ -144,7 +143,7 @@ module Equatable
     #
     # @api public
     def ==(other)
-      is_a?(other.class) && compare?(__method__, other)
+      other.is_a?(self.class) && compare?(__method__, other)
     end
   end # Methods
 end # Equatable

data/lib/equatable/version.rb

@@ -1,5 +1,5 @@
 # encoding: utf-8
 
 module Equatable
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
 end

data/spec/equatable/eql_spec.rb

@@ -1,4 +1,4 @@
-# -*- encoding: utf-8 -*-
+# encoding: utf-8
 
 require 'spec_helper'
 
@@ -25,30 +25,30 @@ describe Equatable, '#eql?' do
   context 'with the same object' do
     let(:other) { object }
 
-    it { should be_true }
+    it { is_expected.to eql(true) }
 
     it 'is symmetric' do
-      should eql(other.eql?(object))
+      is_expected.to eql(other.eql?(object))
     end
   end
 
   context 'with an equivalent object' do
     let(:other) { object.dup }
 
-    it { should be_true }
+    it { is_expected.to eql(true) }
 
     it 'is symmetric' do
-      should eql(other.eql?(object))
+      is_expected.to eql(other.eql?(object))
     end
   end
 
   context 'with an equivalent object of a subclass' do
     let(:other) { ::Class.new(klass).new(value) }
 
-    it { should be_false }
+    it { is_expected.to eql(false) }
 
     it 'is symmetric' do
-      should eql(other.eql?(object))
+      is_expected.to eql(other.eql?(object))
     end
   end
 end

data/spec/equatable/equal_spec.rb

@@ -1,4 +1,4 @@
-# -*- encoding: utf-8 -*-
+# encoding: utf-8
 
 require 'spec_helper'
 
@@ -27,56 +27,58 @@ describe Equatable, '#==' do
   context 'with the same object' do
     let(:other) { object }
 
-    it { should be_true }
+    it { is_expected.to eql(true) }
 
     it 'is symmetric' do
-      should eql(other == object)
+      is_expected.to eql(other == object)
     end
   end
 
   context 'with an equivalent object' do
     let(:other) { object.dup }
 
-    it { should be_true }
+    it { is_expected.to eql(true) }
 
     it 'is symmetric' do
-      should eql(other == object)
+      is_expected.to eql(other == object)
     end
   end
 
   context 'with an equivalent object of a subclass' do
     let(:other) { ::Class.new(klass).new(value) }
 
-    it { should be_false }
+    it { is_expected.to eql(true) }
 
     it 'is not symmetric' do
-      should_not eql(other == object)
+      # LSP, any equality for type should work for subtype but
+      # not the other way
+      is_expected.not_to eql(other == object)
     end
   end
 
   context 'with an equivalent object of a superclass' do
     let(:other) { super_klass.new(value) }
 
-    it { should be_true }
+    it { is_expected.to eql(false) }
 
     it 'is not symmetric' do
-      should_not eql(other == object)
+      is_expected.not_to eql(other == object)
     end
   end
 
   context 'with an object with a different interface' do
     let(:other) { Object.new }
 
-    it { should be_false }
+    it { is_expected.to eql(false) }
   end
 
   context 'with an object of another class' do
     let(:other) { Class.new.new }
 
-    it { should be_false }
+    it { is_expected.to eql(false) }
 
     it 'is symmetric' do
-      should eql(other == object)
+      is_expected.to eql(other == object)
     end
   end
 end

data/spec/equatable/include_spec.rb

@@ -1,9 +1,9 @@
-# -*- encoding: utf-8 -*-
+# encoding: utf-8
 
 require 'spec_helper'
 
 describe Equatable, '#include' do
-  let(:name) { 'Value' }
+  let(:name)   { 'Value' }
   let(:object) { described_class }
 
   context 'without attributes' do
@@ -12,33 +12,37 @@ describe Equatable, '#include' do
     subject { klass.new }
 
     before {
-      klass.stub(:name).and_return name
+      allow(klass).to receive(:name).and_return(name)
       klass.send(:include, object)
     }
 
-    it { should respond_to :compare? }
+    it { is_expected.to respond_to(:compare?) }
 
-    it { should be_instance_of klass }
+    it { is_expected.to be_instance_of(klass) }
+
+    it 'has no attribute names' do
+      expect(klass.comparison_attrs).to eq([])
+    end
 
     describe '#inspect' do
-      it { subject.inspect.should eql('#<Value>') }
+      it { expect(subject.inspect).to eql('#<Value>') }
     end
 
     describe '#hash' do
-      it { subject.hash.should eql([klass].hash) }
+      it { expect(subject.hash).to eql([klass].hash) }
     end
 
     describe '#eql?' do
       context 'when objects are similar' do
         let(:other) { subject.dup }
 
-        it { subject.eql?(other).should be_true }
+        it { expect(subject.eql?(other)).to eql(true) }
       end
 
       context 'when objects are different' do
-        let(:other) { stub('other') }
+        let(:other) { double('other') }
 
-        it { subject.eql?(other).should be_false }
+        it { expect(subject.eql?(other)).to eql(false) }
       end
     end
 
@@ -46,26 +50,26 @@ describe Equatable, '#include' do
       context 'when objects are similar' do
         let(:other) { subject.dup }
 
-        it { (subject == other).should be_true }
+        it { expect(subject == other).to eql(true) }
       end
 
       context 'when objects are different' do
-        let(:other) { stub('other') }
+        let(:other) { double('other') }
 
-        it { (subject == other)}
+        it { expect(subject == other).to eql(false) }
       end
     end
 
     context 'equivalence relation' do
-      let(:other) { subject.dup }
+      let(:other)   { subject.dup }
       let(:another) { other.dup }
 
       it 'is not equal to nil reference' do
-         expect(subject.eql?(nil)).to be_false
+        expect(subject.eql?(nil)).to eql(false)
       end
 
       it 'is reflexive' do
-        expect(subject.eql?(subject)).to be_true
+        expect(subject.eql?(subject)).to eql(true)
       end
 
       it 'is symmetric' do
@@ -92,35 +96,37 @@ describe Equatable, '#include' do
       end
     }
 
-    before {
-      klass.stub(:name).and_return name
-    }
+    before { allow(klass).to receive(:name).and_return(name) }
 
     subject { klass.new(value) }
 
     it 'dynamically defines #hash method' do
-      klass.method_defined?(:hash).should be_true
+      expect(klass.method_defined?(:hash)).to eql(true)
     end
 
     it 'dynamically defines #inspect method' do
-      klass.method_defined?(:inspect).should be_true
+      expect(klass.method_defined?(:inspect)).to eql(true)
     end
 
-    it { should respond_to :compare? }
+    it { is_expected.to respond_to(:compare?) }
+
+    it { is_expected.to respond_to(:eql?) }
 
-    it { should respond_to :eql? }
+    it 'has comparison attribute names' do
+      expect(klass.comparison_attrs).to eq([:value])
+    end
 
     describe '#eql?' do
       context 'when objects are similar' do
         let(:other) { subject.dup }
 
-        it { subject.eql?(other).should be_true }
+        it { expect(subject.eql?(other)).to eql(true) }
       end
 
       context 'when objects are different' do
-        let(:other) { stub('other') }
+        let(:other) { double('other') }
 
-        it { subject.eql?(other).should be_false }
+        it { expect(subject.eql?(other)).to eql(false) }
       end
     end
 
@@ -128,34 +134,34 @@ describe Equatable, '#include' do
       context 'when objects are similar' do
         let(:other) { subject.dup }
 
-        it { (subject == other).should be_true }
+        it { expect(subject == other).to eql(true) }
       end
 
       context 'when objects are different' do
-        let(:other) { stub('other') }
+        let(:other) { double('other') }
 
-        it { (subject == other).should be_false }
+        it { expect(subject == other).to eql(false) }
       end
     end
 
     describe '#inspect' do
-      it { subject.inspect.should eql('#<Value value=11>') }
+      it { expect(subject.inspect).to eql('#<Value value=11>') }
     end
 
     describe '#hash' do
-      it { subject.hash.should eql( ([klass] + [value]).hash) }
+      it { expect(subject.hash).to eql( ([klass] + [value]).hash) }
     end
 
     context 'equivalence relation' do
-      let(:other) { subject.dup }
+      let(:other)   { subject.dup }
       let(:another) { other.dup }
 
       it 'is not equal to nil reference' do
-         expect(subject.eql?(nil)).to be_false
+        expect(subject.eql?(nil)).to eql(false)
       end
 
       it 'is reflexive' do
-        expect(subject.eql?(subject)).to be_true
+        expect(subject.eql?(subject)).to eql(true)
       end
 
       it 'is symmetric' do

data/spec/equatable/subclass_spec.rb

@@ -1,4 +1,4 @@
-# -*- encoding: utf-8 -*-
+# encoding: utf-8
 
 require 'spec_helper'
 
@@ -20,31 +20,29 @@ describe Equatable, 'subclass' do
     }
     let(:subclass) { ::Class.new(klass) }
 
-    before {
-      klass.stub(:name).and_return name
-    }
-
     subject { subclass.new(value) }
 
-    it { subclass.superclass.should == klass }
+    before { allow(klass).to receive(:name).and_return(name) }
 
-    it { should respond_to :value }
+    it { expect(subclass.superclass).to eq(klass) }
+
+    it { is_expected.to respond_to(:value) }
 
     describe '#inspect' do
-      it { subject.inspect.should eql('#<Value value=11>') }
+      it { expect(subject.inspect).to eql('#<Value value=11>') }
     end
 
     describe '#eql?' do
       context 'when objects are similar' do
         let(:other) { subject.dup }
 
-        it { subject.eql?(other).should be_true }
+        it { expect(subject.eql?(other)).to eql(true) }
       end
 
       context 'when objects are different' do
-        let(:other) { stub('other') }
+        let(:other) { double('other') }
 
-        it { subject.eql?(other).should be_false }
+        it { expect(subject.eql?(other)).to eql(false) }
       end
     end
 
@@ -52,15 +50,14 @@ describe Equatable, 'subclass' do
       context 'when objects are similar' do
         let(:other) { subject.dup }
 
-        it { (subject == other).should be_true }
+        it { expect(subject == other).to eql(true) }
       end
 
       context 'when objects are different' do
-        let(:other) { stub('other') }
+        let(:other) { double('other') }
 
-        it { (subject == other)}
+        it { expect(subject == other).to eql(false) }
       end
     end
   end
-
 end

data/spec/spec_helper.rb

@@ -1,11 +1,10 @@
-require 'rubygems'
+# encoding: utf-8
 
-$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
-$LOAD_PATH.unshift(File.dirname(__FILE__))
-
-require 'rspec'
 require 'equatable'
 
 RSpec.configure do |config|
-  config.order = :rand
+  config.run_all_when_everything_filtered = true
+  config.filter_run :focus
+  config.order = 'random'
+  config.raise_errors_for_deprecations!
 end

data/tasks/spec.rake

@@ -0,0 +1,10 @@
+# encoding: utf-8
+
+begin
+  require "rspec/core/rake_task"
+  RSpec::Core::RakeTask.new(:spec) do |spec|
+    spec.pattern = 'spec/**{,/*/**}/*_spec.rb'
+  end
+rescue LoadError
+  $stderr.puts("Cannot load rspec task.")
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: equatable
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Piotr Murach
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-08-15 00:00:00.000000000 Z
+date: 2014-09-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -43,6 +43,7 @@ files:
 - README.md
 - Rakefile
 - equatable.gemspec
+- examples/point.rb
 - lib/equatable.rb
 - lib/equatable/version.rb
 - spec/equatable/eql_spec.rb
@@ -50,6 +51,7 @@ files:
 - spec/equatable/include_spec.rb
 - spec/equatable/subclass_spec.rb
 - spec/spec_helper.rb
+- tasks/spec.rake
 homepage: http://github.com/peter-murach/equatable
 licenses: []
 metadata: {}