hash_deep_diff 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3aab07a4c397dbc84845d5f0faff052bbae89eb8be4bf24a5ed9df0d5129c3da
-  data.tar.gz: 2ea89b301d808655625e0fa6a9c5028b9d194bba3c4dc54cf1f5c6859c59fc6f
+  metadata.gz: ddbaa8e8f12ba99330973c609c00ab710e9fa39b369797b80dd46f24aa6740e1
+  data.tar.gz: 6a5954a960ca0876cdb9e28f3e535be687de5596ed07be61581102b75b178ab4
 SHA512:
-  metadata.gz: f0a05ee023dbbd4d8551b5065a57a65b645ca3b0a864eace0de91b10ec08da77b0a15df6422af0f5ce0afd4459ca141e227398f9560198f6d350963fac1a99f0
-  data.tar.gz: 279185ca8464992a65f2fff626b6ee90f44ac7b7e98706e34443390ad24457961b642e5b2ebee10c4c8e3e5c72b7bfee454dd644f8f7ef68db5872c426137dc7
+  metadata.gz: af66a50e5a7eb848c96b757e8e37a4d767868de6fd96ebfd4f528085111e2fe1c9e39215b8514d534d33f94cfc4c024c5c2bba1813acad729fa906e18eee796a
+  data.tar.gz: 358e25298ee3c42ea469e44113fe62935ec8f564c4111c52e170bd25764d99cc4b71c42d154689ad2a9c54ff21f9359dad57cfbd450677853eb60655b90aecf4

data/Guardfile

@@ -25,8 +25,8 @@ end
 guard :minitest do
   # with Minitest::Unit
   watch(%r{^test/(.*)/?test_(.*)\.rb$})
-  # watch(%r{^lib/(.*/)?([^/]+)\.rb$})     { |m| "test/#{m[1]}test_#{m[2]}.rb" }
-  watch(%r{^lib/(.*/)?([^/]+)\.rb$})     { 'test' }
+  watch(%r{^lib/hash_deep_diff/(.*/)?([^/]+)\.rb$}) { |m| "test/unit/#{m[1]}test_#{m[2]}.rb" }
+  # watch(%r{^lib/(.*/)?([^/]+)\.rb$})     { 'test' }
   watch(%r{^test/test_helper\.rb$})      { 'test' }
   watch(%r{^test/support/.*$})           { 'test' }
 end

data/README.md

@@ -36,8 +36,19 @@ HashDeepDiff::Comparison.new(left, right).report
 - left[a] = a
 + left[a] = b
 ```
-please see [Documentation](https://rdoc.info/gems/hash_deep_diff) for
-more info
+please see [Documentation](https://rdoc.info/gems/hash_deep_diff/HashDeepDiff/Comparison) for
+more information 
+
+## Customization
+
+You can implement and use your own reporting engines with the default `HashDeepDiff::Delta` objects as a source of the report. In order to do so implement your own version of the reporting engine (example can be found [here](https://github.com/bpohoriletz/hash_deep_diff/tree/main/lib/hash_deep_diff/reports)) and inject it into a `Comparison`
+
+```ruby
+left = { a: :a }
+right = { a: :b }
+
+HashDeepDiff::Comparison.new(left, right, reporting_engine: CustomEngine).report
+```
 
 ## Contributing
 

data/hash_deep_diff.gemspec

@@ -22,6 +22,7 @@ Gem::Specification.new do |spec|
     spec.metadata['allowed_push_host'] = 'https://rubygems.org/'
 
     spec.metadata['homepage_uri'] = spec.homepage
+    spec.metadata['documentation_uri'] = 'https://rdoc.info/gems/hash_deep_diff'
     spec.metadata['source_code_uri'] = 'https://github.com/bpohoriletz/hash_deep_diff'
     spec.metadata['changelog_uri'] = 'https://github.com/bpohoriletz/hash_deep_diff/blob/main/CHANGELOG.md'
     spec.metadata['rubygems_mfa_required'] = 'true'
@@ -47,6 +48,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'minitest', '~> 5.15.0'
   spec.add_development_dependency 'minitest-focus', '~> 1.3.1'
   spec.add_development_dependency 'minitest-reporters', '~> 1.5.0'
+  spec.add_development_dependency 'naught', '~> 1.1.0'
   spec.add_development_dependency 'rake', '~> 10.5.0'
   spec.add_development_dependency 'rubocop', '~> 1.26.1'
   spec.add_development_dependency 'rubocop-minitest', '~> 0.18.0'

data/lib/hash_deep_diff/comparison.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative 'delta'
+require_relative 'factories/comparison'
 
 module HashDeepDiff
   # Representation of the recursive difference between two hashes
@@ -11,12 +11,12 @@ module HashDeepDiff
   #
   # Examples:
   #   - { one: :a } compared with { one: :b } does not have nesting so we compare keys and values
-  #   - { one: { two: :a, zero: z } } compared with { one: { two: :b, three: :c } } has nesting, so is represented as
+  #   - { one: { two: :a, zero: :z } } compared with { one: { two: :b, three: :c } } has nesting, so is represented as
   #     - { two: :a } compared with { two: :b, three: :c }, as there is no more nesting we compare keys and values
   #       and have the following comparisons
   #       { one: { two: :a } } compared to { one: { two: :b } } - value was changed
   #         i.e :a vas replaced with :b on path [:one, :two]
-  #       { one: { zero: z } } compared to NO_VALUE - value was deleted
+  #       { one: { zero: :z } } compared to NO_VALUE - value was deleted
   #         i.e :z vas replaced with NO_VALUE on path [:one, :zero]
   #       NO_VALUE compared to { one: { three: :c } } compared - value was added
   #         i.e NO_VALUE vas replaced with :c on path [:one, :three]
@@ -35,70 +35,116 @@ module HashDeepDiff
   #     @value={:left=>HashDeepDiff::NO_VALUE, :right=>:c}>
   #  ]
   class Comparison
+    extend Forwardable
     # @!attribute [r] left
     #    @return [Hash] original version of the Hash
     # @!attribute [r] right
     #    @return [Hash] Hash that the original is compared to
     # @!attribute [r] path
-    #    @return [Array<Object>] to a compared Hashes (is empty for top-level comparison)
-    attr_reader :left, :right, :path
+    #    @return [Array<Object>] subset of keys from original Hashes to fetch compared values
+    #    (is empty for top-level comparison)
+    attr_reader :reporting_engine, :delta_engine
+
+    def_delegators :comparison_factory, :comparison
 
     # @return [String]
     def report
-      diff.join("\n")
+      diff.map { |simple_delta| reporting_engine.new(delta: simple_delta).to_s }.join
     end
 
     # @return [Array<HashDeepDiff::Delta>]
     def diff
-      comparison.flat_map do |delta|
-        # if there are nested hashes we need to compare them furter
-        # if no we return difference between values (HashDeepDiff::Delta)
-        delta.complex? ? self.class.new(delta.left, delta.right, delta.path).diff : delta
-      end
+      return [] if left == right
+
+      deltas.flat_map { |new_delta| new_delta.simple? ? new_delta : inward_comparison(new_delta) }
+    end
+
+    # @param [Object] key the key which value we're currently comparing
+    def left(key = NO_VALUE)
+      return NO_VALUE if @left == NO_VALUE
+      return @left if key == NO_VALUE
+
+      @left[key] || NO_VALUE
+    end
+
+    # @param [Object] key the key which value we're currently comparing
+    def right(key = NO_VALUE)
+      return NO_VALUE if @right == NO_VALUE
+      return @right if key == NO_VALUE
+
+      @right[key] || NO_VALUE
     end
 
     private
 
-    # @param [Hash] left original version of the hash
-    # @param [Hash] right new version of the hash
+    attr_reader :path
+
+    # @param [Object] original original version
+    # @param [Object] changed new version
     # @param [Array] prefix keys to fetch current comparison (not empty for nested comparisons)
-    def initialize(left, right, prefix = [])
-      @left = left.to_hash
-      @right = right.to_hash
+    def initialize(original, changed, prefix = [], reporting_engine: Reports::Diff, delta_engine: Delta)
+      @left = original
+      @right = changed
       @path = prefix.to_ary
+      @reporting_engine = reporting_engine
+      @delta_engine = delta_engine
     end
 
+    # {Comparison} broken down into array of {Delta}
     # @return [Array<HashDeepDiff::Delta>]
-    def comparison
+    def deltas
+      return [delta] if common_keys.empty?
+
       common_keys.each_with_object([]) do |key, memo|
         next if values_equal?(key)
 
-        memo << Delta.new(path: path + [key], value: { left: value_left(key), right: value_right(key) })
+        memo << delta(key: key)
+      end
+    end
+
+    # depending on circumstances will return necessary comparisons
+    # @return [Array<HashDeepDiff::Delta>]
+    def inward_comparison(complex_delta)
+      if complex_delta.partial?
+        [
+          complex_delta.placebo,
+          comparison(delta: complex_delta, modifier: :right).diff,
+          comparison(delta: complex_delta, modifier: :left).diff
+        ].compact.flatten
+        # TOFIX add test an drop flatten
+      else
+        comparison(delta: complex_delta).diff
       end
     end
 
     # @param [Object] key the key which value we're currently comparing
     # @return [Bool]
     def values_equal?(key)
-      value_right(key).instance_of?(value_left(key).class) && (value_right(key) == value_left(key))
+      right(key).instance_of?(left(key).class) && (right(key) == left(key))
     end
 
-    # Original value
-    # @param [Object] key the key which value we're currently comparing
-    def value_left(key)
-      left[key] || NO_VALUE
+    # All keys from both original and compared objects
+    # @return [Array]
+    def common_keys
+      keys = []
+      keys += left.keys if left.respond_to?(:keys)
+      keys += right.keys if right.respond_to?(:keys)
+
+      keys.uniq
     end
 
-    # Value we compare to
-    # @param [Object] key the key which value we're currently comparing
-    def value_right(key)
-      right[key] || NO_VALUE
+    # @return [HashDeepDiff::Factories::Comparison]
+    def comparison_factory
+      HashDeepDiff::Factories::Comparison.new(reporting_engine: reporting_engine)
     end
 
-    # All keys from both original and compared objects
-    # @return [Array]
-    def common_keys
-      (left.keys + right.keys).uniq
+    # factory function
+    # @return [HashDeepDiff::Delta]
+    def delta(key: NO_VALUE)
+      change_key = path
+      change_key += [key] unless key == NO_VALUE
+
+      HashDeepDiff::Delta.new(change_key: change_key, value: { left: left(key), right: right(key) })
     end
   end
 end

data/lib/hash_deep_diff/delta.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
-require_relative 'acts_as_hash'
-require_relative 'report'
+require 'forwardable'
 
 module HashDeepDiff
   # Representation of the diff of two values
@@ -10,74 +9,83 @@ module HashDeepDiff
   #   - diff of { a: a } and { a: b } is { a: { left: a, right: b } }
   #   - diff of {} and { a: b } is { a: { left: HashDeepDiff::NO_VALUE, right: b } }
   class Delta
-    include ActsAsHash
+    extend Forwardable
 
-    # Visual representation of additions and deletiond at given +path+
-    # @return [String]
-    def to_str
-      [deletion, addition].compact.join("\n")
+    def_delegators :to_hash, :==, :each_with_object, :each_key, :[],
+                   :to_a, :empty?, :keys
+    attr_reader :change_key
+
+    # an indication that nested Hash was deleted/added
+    # @return [HashDeepDiff::Delta, NilClass]
+    def placebo
+      return nil unless partial?
+
+      placebo = simple_left? ? { left: NO_VALUE, right: {} } : { left: {}, right: NO_VALUE }
+
+      self.class.new(change_key: change_key, value: placebo)
     end
 
-    # Returns true if we have nested Hashes
+    # true if at least one of the values is a Hash
     # @return [Bool]
-    def complex?
-      left.respond_to?(:to_hash) && right.respond_to?(:to_hash)
+    def partial?
+      !composite? && !simple?
     end
 
-    # Keys needed to fetch values that we're comparing
-    # @return [Array]
-    def path
-      @prefix + [@delta.keys.first]
+    # true if both valus are Hashes
+    # @return [Bool]
+    def composite?
+      !simple_left? && !simple_right?
+    end
+
+    # true if none of the values is a Hash
+    # @return [Bool]
+    def simple?
+      simple_left? && simple_right?
     end
 
     # Original value
     def left
-      @value[:left]
+      value[:left]
     end
 
     # Value we compare to
     def right
-      @value[:right]
+      value[:right]
     end
 
-    # See {#to_str}
-    def to_s
-      to_str
+    # see {#to_hash}
+    # @return [Hash]
+    def to_h
+      to_hash
+    end
+
+    # @return [Hash]
+    def to_hash
+      { change_key[-1] => value }
     end
 
     private
 
-    # @param [Array, Object] path list of keys to fetch values we're comparing
+    attr_reader :value
+
+    # @param [Array] change_key list of keys to fetch values we're comparing
     # @param [Hash<(:left, :right), Object>] value +Hash+ object with two keys - :left and :right,
     #   that represents compared original value (at :left) and value we compare to (at :right)
-    def initialize(path:, value:)
-      # TOFIX this may prohibit usage of hashes with Array keys
-      # TOFIX extract path to a separate object
-      if path.respond_to?(:to_ary)
-        @delta = { path[-1] => value }
-        @value = value
-        @prefix = path[0..-2]
-      else
-        @delta = { path => value }
-        @value = value
-        @prefix = []
-      end
+    def initialize(change_key:, value:)
+      @value = value
+      @change_key = change_key
     end
 
-    # Visual representation of additions
-    # @return [NillClass, String]
-    def deletion
-      return nil if left == NO_VALUE
-
-      Report.new(path: path, value: left, mode: Report::Mode::DELETION)
+    # Returns true if left value has no nested Hashes
+    # @return [Bool]
+    def simple_left?
+      !left.respond_to?(:to_hash)
     end
 
-    # Visual representation of deletions
-    # @return [NillClass, String]
-    def addition
-      return nil if right == NO_VALUE
-
-      Report.new(path: path, value: right)
+    # Returns true if right value has no nested Hashes
+    # @return [Bool]
+    def simple_right?
+      !right.respond_to?(:to_hash)
     end
   end
 end

data/lib/hash_deep_diff/factories/comparison.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+module HashDeepDiff
+  # factories
+  module Factories
+    # Factory for {HashDeepDiff::Comparison}
+    class Comparison
+      extend Forwardable
+      def_delegators :delta, :left, :right, :change_key
+
+      # factory function
+      # @return [Comparison]
+      def comparison(delta:, modifier: nil)
+        @delta = delta
+
+        case modifier
+        when nil
+          full_compare
+        when :left
+          compare_left
+        when :right
+          compare_right
+        end
+      end
+
+      private
+
+      attr_reader :reporting_engine, :delta
+
+      def initialize(reporting_engine:)
+        @reporting_engine = reporting_engine
+      end
+
+      # compare two hashes
+      def full_compare
+        HashDeepDiff::Comparison.new(left, right, change_key,
+                                     delta_engine: delta.class,
+                                     reporting_engine: reporting_engine)
+      end
+
+      # compare Hash with nothing (deletion)
+      def compare_left
+        HashDeepDiff::Comparison.new(left, NO_VALUE, change_key,
+                                     delta_engine: delta.class,
+                                     reporting_engine: reporting_engine)
+      end
+
+      # compare nothing with Hash (addition)
+      def compare_right
+        HashDeepDiff::Comparison.new(NO_VALUE, right, change_key,
+                                     delta_engine: delta.class,
+                                     reporting_engine: reporting_engine)
+      end
+    end
+  end
+end

data/lib/hash_deep_diff/reports/base.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module HashDeepDiff
+  # Different reporting enjines for {Delta}
+  module Reports
+    # Abstract Class
+    class Base
+      # see {#to_str}
+      # @return [String]
+      def to_s
+        to_str
+      end
+
+      # A report on additions and deletions
+      # @return [String]
+      def to_str
+        original + replacement
+      end
+
+      private
+
+      attr_reader :old_val, :new_val, :change_key
+
+      # @param [Delta] delta diff to report
+      def initialize(delta:)
+        @change_key = delta.change_key.to_ary
+        @old_val = delta.left
+        @new_val = delta.right
+      end
+
+      # old value
+      def original
+        raise AbstractMethodError
+      end
+
+      # new value
+      def replacement
+        raise AbstractMethodError
+      end
+    end
+  end
+end

data/lib/hash_deep_diff/reports/diff.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module HashDeepDiff
+  # Different reporting enjines for {Delta}
+  module Reports
+    # Visual representation of the {Delta} as diff
+    class Diff < Base
+      private
+
+      # old value
+      # @return [String]
+      def original
+        return '' if old_val == NO_VALUE
+
+        return "#{deletion}#{path} = #{old_val}\n"
+      end
+
+      # new value
+      # @return [String]
+      def replacement
+        return '' if new_val == NO_VALUE
+
+        return "#{addition}#{path} = #{new_val}\n"
+      end
+
+      # Visual representation of keys from compared objects needed to fetch the compared values
+      # @return [String]
+      def path
+        change_key.map { |key| "[#{key}]" }.join
+      end
+
+      # visual indication of addition
+      # @return [String]
+      def addition
+        '+left'
+      end
+
+      # visual indication of deletion
+      # @return [String]
+      def deletion
+        '-left'
+      end
+    end
+  end
+end

data/lib/hash_deep_diff/version.rb

@@ -2,5 +2,5 @@
 
 module HashDeepDiff
   # Version of a gem
-  VERSION = '0.5.0'
+  VERSION = '0.6.0'
 end

data/lib/hash_deep_diff.rb

@@ -1,10 +1,16 @@
 # frozen_string_literal: true
 
 require 'hash_deep_diff/version'
+require 'hash_deep_diff/reports/diff'
+require 'hash_deep_diff/delta'
 require 'hash_deep_diff/comparison'
 
 # Global namespace
 module HashDeepDiff
   # value was not found
   NO_VALUE = Class.new(NilClass)
+  # Abstract method
+  AbstractMethodError = Class.new(NoMethodError)
+  # Any error
+  Error = Class.new(StandardError)
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hash_deep_diff
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Bohdan Pohorilets
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-04-18 00:00:00.000000000 Z
+date: 2022-04-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -122,6 +122,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 1.5.0
+- !ruby/object:Gem::Dependency
+  name: naught
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.1.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.1.0
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -209,10 +223,11 @@ files:
 - bin/yri
 - hash_deep_diff.gemspec
 - lib/hash_deep_diff.rb
-- lib/hash_deep_diff/acts_as_hash.rb
 - lib/hash_deep_diff/comparison.rb
 - lib/hash_deep_diff/delta.rb
-- lib/hash_deep_diff/report.rb
+- lib/hash_deep_diff/factories/comparison.rb
+- lib/hash_deep_diff/reports/base.rb
+- lib/hash_deep_diff/reports/diff.rb
 - lib/hash_deep_diff/version.rb
 homepage: https://github.com/bpohoriletz/hash_deep_diff
 licenses:
@@ -220,6 +235,7 @@ licenses:
 metadata:
   allowed_push_host: https://rubygems.org/
   homepage_uri: https://github.com/bpohoriletz/hash_deep_diff
+  documentation_uri: https://rdoc.info/gems/hash_deep_diff
   source_code_uri: https://github.com/bpohoriletz/hash_deep_diff
   changelog_uri: https://github.com/bpohoriletz/hash_deep_diff/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'

data/lib/hash_deep_diff/acts_as_hash.rb

@@ -1,31 +0,0 @@
-# frozen_string_literal: true
-
-require 'forwardable'
-
-module HashDeepDiff
-  # This module includes behavior that is needed to use instances of Delta instead of Hash
-  # in this gem
-  module ActsAsHash
-    # @param [Object] base a hook that is invoked when module is included in a class
-    def self.included(base)
-      base.extend Forwardable
-      base.def_delegators :@delta, :==, :each_with_object, :each_key, :[],
-                          :to_a, :empty?, :keys
-      base.include InstanceMethods
-    end
-
-    # We assume that the class will initialize instance variable +@delta+ that will return
-    # a representation of an instance of a class as a +Hash+ object
-    module InstanceMethods
-      # a +Hash+ representation of an object
-      def to_h
-        to_hash
-      end
-
-      # a +Hash+ representation of an object
-      def to_hash
-        @delta
-      end
-    end
-  end
-end

data/lib/hash_deep_diff/report.rb

@@ -1,53 +0,0 @@
-# frozen_string_literal: true
-
-module HashDeepDiff
-  # Visual representation of the difference between two values
-  class Report
-    # We have two cases
-    #   * added - when value on the left is missing
-    #   * deleted - when the value on the right is missing
-    module Mode
-      # for additions
-      ADDITION = '+left'
-      # for deletions
-      DELETION = '-left'
-    end
-
-    # A report with all additions and deletions
-    # @return [String]
-    def to_str
-      if @value.respond_to?(:to_hash) && !@value.empty?
-        [@mode, diff_prefix, ' = ', "{}\n"].join +
-          @value.keys.map do |key|
-            Report.new(path: @path + [key], value: @value[key], mode: @mode)
-          end.join("\n")
-      else
-        [@mode, diff_prefix, ' = ', @value.to_s].join
-      end
-    end
-
-    # A report with all additions and deletions
-    # @return [String]
-    def to_s
-      to_str
-    end
-
-    private
-
-    # @param [Array] path Keys from compared objects to fetch the compared values
-    # @param [Object] value value from a  compared object at +@path+
-    # @param [Mode::ADDITION, Mode::DELETION] mode
-    def initialize(path:, value:, mode: Mode::ADDITION)
-      @path = path.to_ary
-      @value = value
-      @mode = mode
-    end
-
-    # Visual representation of keys from compared objects needed to fetch the compared values
-    # @return [String]
-    def diff_prefix
-      # TOFIX poor naming
-      @path.map { |key| "[#{key}]" }.join
-    end
-  end
-end