hash_deep_diff 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 965ed70dc327febfcab65e1d8a9ae2511e06b117316a368140eae6a00dc8afba
-  data.tar.gz: f905ef6c174c729ec28f9d585db116deb32727276ae61b1e448f4c17917cbf47
+  metadata.gz: 3aab07a4c397dbc84845d5f0faff052bbae89eb8be4bf24a5ed9df0d5129c3da
+  data.tar.gz: 2ea89b301d808655625e0fa6a9c5028b9d194bba3c4dc54cf1f5c6859c59fc6f
 SHA512:
-  metadata.gz: 6669aa02e12598277b0d59e0abb1f173a1a28dfb5aa9770e5c209bde4972bb7e9166788dfcae30743fcc95050bf23104e768edae1ecec855f07b72fa704ad46a
-  data.tar.gz: d4f9fc51fc4acbaaf0228f84c8aa47e84cb1b17dbad6e45df7047df0cf086b7ff6deeab85de648ec5916174b0d12e1a982bac975d9a05ef65609714f23ab91dc
+  metadata.gz: f0a05ee023dbbd4d8551b5065a57a65b645ca3b0a864eace0de91b10ec08da77b0a15df6422af0f5ce0afd4459ca141e227398f9560198f6d350963fac1a99f0
+  data.tar.gz: 279185ca8464992a65f2fff626b6ee90f44ac7b7e98706e34443390ad24457961b642e5b2ebee10c4c8e3e5c72b7bfee454dd644f8f7ef68db5872c426137dc7

data/.yardopts

@@ -0,0 +1 @@
+--private

data/Guardfile

@@ -30,3 +30,7 @@ guard :minitest do
   watch(%r{^test/test_helper\.rb$})      { 'test' }
   watch(%r{^test/support/.*$})           { 'test' }
 end
+
+guard 'yard' do
+  watch(%r{lib/.+\.rb})
+end

data/README.md

@@ -36,6 +36,8 @@ 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
 
 ## Contributing
 

data/bin/yard

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'yard' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+bundle_binstub = File.expand_path("bundle", __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("yard", "yard")

data/bin/yardoc

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'yardoc' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+bundle_binstub = File.expand_path("bundle", __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("yard", "yardoc")

data/bin/yri

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'yri' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+bundle_binstub = File.expand_path("bundle", __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("yard", "yri")

data/hash_deep_diff.gemspec

@@ -43,6 +43,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'guard', '~> 2.18.0'
   spec.add_development_dependency 'guard-minitest', '~> 2.4.6'
   spec.add_development_dependency 'guard-rubocop', '~> 1.5.0'
+  spec.add_development_dependency 'guard-yard', '~> 2.2.1'
   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'

data/lib/hash_deep_diff/acts_as_hash.rb

@@ -3,22 +3,26 @@
 require 'forwardable'
 
 module HashDeepDiff
-  # This module includes behavior that is needed to use deltas instead of Hash inside this gem
+  # 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.include(InstanceMethods)
-      base.extend(Forwardable)
+      base.extend Forwardable
       base.def_delegators :@delta, :==, :each_with_object, :each_key, :[],
                           :to_a, :empty?, :keys
+      base.include InstanceMethods
     end
 
-    # Assumes that the class will include method delta that will return a representation of an
-    # instance of a class as a Hash
+    # 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
-        @delta
+        to_hash
       end
 
+      # a +Hash+ representation of an object
       def to_hash
         @delta
       end

data/lib/hash_deep_diff/comparison.rb

@@ -2,49 +2,101 @@
 
 require_relative 'delta'
 
-# :nodoc:
 module HashDeepDiff
-  # An instrument to build and report the difference between two hash-like objects
+  # Representation of the recursive difference between two hashes
+  # main parts are
+  # * path - empty for original hashes, otherwise path to values being compared
+  # * left - basically left.dig(path), left value of two being compared
+  # * right - basically right.dig(path), right value of two being compared
+  #
+  # 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
+  #     - { 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
+  #         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]
+  #  [
+  #    #<HashDeepDiff::Delta
+  #      @delta={:two=>{:left=>:a, :right=>:b}},
+  #      @prefix=[:one],
+  #      @value={:left=>:a, :right=>:b}>,
+  #    #<HashDeepDiff::Delta
+  #      @delta={:zero=>{:left=>:z, :right=>HashDeepDiff::NO_VALUE}},
+  #      @prefix=[:one],
+  #      @value={:left=>:z, :right=>HashDeepDiff::NO_VALUE}>,
+  #    #<HashDeepDiff::Delta
+  #     @delta={:three=>{:left=>HashDeepDiff::NO_VALUE, :right=>:c}},
+  #     @prefix=[:one],
+  #     @value={:left=>HashDeepDiff::NO_VALUE, :right=>:c}>
+  #  ]
   class Comparison
+    # @!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
 
-    def diff
-      deep_delta
-    end
-
+    # @return [String]
     def report
       diff.join("\n")
     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
+    end
+
     private
 
-    def initialize(left, right, path = [])
+    # @param [Hash] left original version of the hash
+    # @param [Hash] right new version of the hash
+    # @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
-      @path = path.to_ary
+      @path = prefix.to_ary
     end
 
-    def deep_delta
-      delta.flat_map do |diff|
-        if diff.complex?
-          self.class.new(diff.left, diff.right, diff.path).diff
-        else
-          diff
-        end
+    # @return [Array<HashDeepDiff::Delta>]
+    def comparison
+      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) })
       end
     end
 
-    def delta
-      common_keys.each_with_object([]) do |key, memo|
-        value_left = left[key] || NO_VALUE
-        value_right = right[key] || NO_VALUE
+    # @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))
+    end
 
-        next if value_right.instance_of?(value_left.class) && (value_right == value_left)
+    # Original value
+    # @param [Object] key the key which value we're currently comparing
+    def value_left(key)
+      left[key] || NO_VALUE
+    end
 
-        memo << Delta.new(path: path + [key], value: { left: value_left, right: value_right })
-      end
+    # Value we compare to
+    # @param [Object] key the key which value we're currently comparing
+    def value_right(key)
+      right[key] || NO_VALUE
     end
 
+    # All keys from both original and compared objects
+    # @return [Array]
     def common_keys
       (left.keys + right.keys).uniq
     end

data/lib/hash_deep_diff/delta.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'acts_as_hash'
+require_relative 'report'
 
 module HashDeepDiff
   # Representation of the diff of two values
@@ -11,36 +12,47 @@ module HashDeepDiff
   class Delta
     include ActsAsHash
 
+    # Visual representation of additions and deletiond at given +path+
+    # @return [String]
     def to_str
       [deletion, addition].compact.join("\n")
     end
 
+    # Returns true if we have nested Hashes
+    # @return [Bool]
     def complex?
       left.respond_to?(:to_hash) && right.respond_to?(:to_hash)
     end
 
-    # TOFIX poor naming
-    # overrides parameter in initializer
+    # Keys needed to fetch values that we're comparing
+    # @return [Array]
     def path
       @prefix + [@delta.keys.first]
     end
 
+    # Original value
     def left
       @value[:left]
     end
 
+    # Value we compare to
     def right
       @value[:right]
     end
 
+    # See {#to_str}
     def to_s
       to_str
     end
 
     private
 
+    # @param [Array, Object] path 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
@@ -52,29 +64,20 @@ module HashDeepDiff
       end
     end
 
+    # Visual representation of additions
+    # @return [NillClass, String]
     def deletion
       return nil if left == NO_VALUE
 
-      if left.respond_to?(:to_hash)
-        left.keys.map { |key| "-left#{diff_prefix}[#{key}] = #{left[key]}" }.join("\n")
-      else
-        "-left#{diff_prefix} = #{left}"
-      end
+      Report.new(path: path, value: left, mode: Report::Mode::DELETION)
     end
 
+    # Visual representation of deletions
+    # @return [NillClass, String]
     def addition
       return nil if right == NO_VALUE
 
-      if right.respond_to?(:to_hash)
-        right.keys.map { |key| "+left#{diff_prefix}[#{key}] = #{right[key]}" }.join("\n")
-      else
-        "+left#{diff_prefix} = #{right}"
-      end
-    end
-
-    # TOFIX poor naming
-    def diff_prefix
-      path.map { |key| "[#{key}]" }.join
+      Report.new(path: path, value: right)
     end
   end
 end

data/lib/hash_deep_diff/report.rb

@@ -0,0 +1,53 @@
+# 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

data/lib/hash_deep_diff/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module HashDeepDiff
-  VERSION = '0.4.1'
+  # Version of a gem
+  VERSION = '0.5.0'
 end

data/lib/hash_deep_diff.rb

@@ -3,7 +3,8 @@
 require 'hash_deep_diff/version'
 require 'hash_deep_diff/comparison'
 
+# Global namespace
 module HashDeepDiff
+  # value was not found
   NO_VALUE = Class.new(NilClass)
-  class Error < StandardError; end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hash_deep_diff
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Bohdan Pohorilets
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-04-17 00:00:00.000000000 Z
+date: 2022-04-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -66,6 +66,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 1.5.0
+- !ruby/object:Gem::Dependency
+  name: guard-yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.2.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.2.1
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -176,6 +190,7 @@ files:
 - ".github/workflows/ci.yml"
 - ".gitignore"
 - ".rubocop.yml"
+- ".yardopts"
 - CHANGELOG.md
 - Gemfile
 - Guardfile
@@ -189,11 +204,15 @@ files:
 - bin/rake
 - bin/rubocop
 - bin/setup
+- bin/yard
+- bin/yardoc
+- 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/version.rb
 homepage: https://github.com/bpohoriletz/hash_deep_diff
 licenses: