easy_diff 0.0.7 → 1.0.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    YWUyMjFiNjI3ODUzYjhjNjI0N2YyODczNDU3MTNlMmExZGI3NWI4Ng==
+    YjI1YzlmNmU5NDk3YzBhMWVmNjIzMDI0YTc2NDM0ZDU0ZmFiZTM4Mg==
   data.tar.gz: !binary |-
-    NDk4MzAzNzVmZTJhMzc5M2VlMDVmMmE1Mjg1MjAxYjkwN2E3ZGQwYQ==
+    MjhiNTJhNDBjZjRmMmYyMzkxNDY3YWI5YWFkODEwNWQ4ZTkyMWZkNg==
 SHA512:
   metadata.gz: !binary |-
-    NWFjNTYxNDJiNzQ1MmIwZDdmZDAxMzE4NTc5M2FhNGUxY2Q5ZmZiMzRjMmMx
-    MmRmZDEzYWE1YWZjZWE1OGVlYzZiODc2ZDA4ZmQ5M2UxNjgyZmVkMmU3OThi
-    ODhmM2VkODdkYTQyNGY4MTM1YTExNzRiNzQwNDAwZjgxNjNiNWU=
+    YzU3NDkzYTRjN2E5OWZjZTNmYWQ2MGVjZjg2ZWJhZjk5NmVhMzYzMjRiYmM2
+    ZDM4YWRmNWM0MzUzOWY0ZTI2YmFkNzU0ZGZmNDA2OGFmMWQyOTdiOTQ1MzVl
+    ZTI3ZTlmMDdmZTFiY2E3NGFmODY4MDliNzFjMzEwNDZlMzkyOGU=
   data.tar.gz: !binary |-
-    NWZiYjcyZGViOGZiZjYzZTZiYWVkMDA4MTU3YjczYmJjZDYyYmM1Mjg5YTE4
-    NzUxOWVjOGVlZjUzZTRhMTBiYzlhMGJmMjdlZDRhMDgyYTIwMDEyNWQ0NWRl
-    NmQ1ZTE4YWQwZWJlY2Q0MjcwMTExY2U0ZWNlOWE5ZmQ0YWNkYjg=
+    NTdjZDE4ZmUwNmQyZDczOGNjYTYzMzY4NDVhZmM2MzU4NzQ5YmE4MDYyZTYz
+    NjliMjg5MGVhZGMxM2QxNGJkMWQyOGNiNGVmMDJiNTYyNjVjYTQyMjQ3NTBm
+    M2Y5MGNkZjM4NWY2MWMzMDRhYTQ5OWIzMTU0ZjZiN2IxZDkzZjQ=

data/README.rdoc

@@ -1,19 +1,104 @@
 = easy_diff
 
 Easy Diff enhances the functionality of Hash, allowing recursive diff, merge, and unmerge of arbitrarily constructed hashes.
-This is perfect for people who need to do diffs on not only plain text files but also data as Hash or JSON objects. Unmerge
-is included with diff and merge to more easily allow versioning of arbitrary data.
+This is perfect for people who need to do diffs on not only plain text files but also data as Hash or JSON objects.
+Unmerge is included with diff and merge to more easily allow versioning of arbitrary data.
+
+There are a few caveats when using this gem:
+* Unmerge should be used before merge to properly transform one hash into another. It will still work in most cases if you don't, but some edge cases will break.
+* The order of elements within an array may be different when transforming one hash into another using unmerge and merge. There is currently no way to guarantee the order is untouched.
+
+== Quick Start Example
+
+  old_data = {
+    :id => 1,
+    :name => "Foo",
+    :tags => [
+      "pretend",
+      "i",
+      "am",
+      "good",
+      "at",
+      "examples"
+    ],
+    :config => {
+      :awesome => true,
+      :go_fast => false,
+      :actually_work => false
+    }
+  }
+
+  new_data = {
+    :id => 1,
+    :name => "Bar",
+    :description => "An awesome thingy I made."
+    :tags => [
+      "i",
+      "am",
+      "really",
+      "good"
+    ]
+    :config => {
+      :awesome => true,
+      :go_fast => true,
+      :actually_work => true
+    }
+  }
+
+  # Diff the two hashes to get what was removed and what was added.
+  removed, added = old_data.easy_diff(new_data)
+
+  # removed will equal
+  # {
+  #   :name => "Foo",
+  #   :tags => [
+  #     "pretend",
+  #     "at",
+  #     "examples"
+  #   ],
+  #   :config => {
+  #     :go_fast => false,
+  #     :actually_work => false
+  #   }
+  # }
+  #
+  #
+  # added will equal
+  # {
+  #   :name => "Bar",
+  #   :description => "An awesome thingy I made.",
+  #   :tags => [
+  #     "really"
+  #   ],
+  #   :config => {
+  #     :go_fast => true,
+  #     :actually_work => true
+  #   }
+  # }
+
+  # Now that we have the removed and added hashes, we can transform the old data into the new data or vice versa
+  transformed_old_data = old_data.easy_unmerge(added).easy_merge(removed)
+  transformed_new_data = new_data.easy_unmerge(removed).easy_merge(added)
+
+  # Let's see if there are any diffs between the transformed hashes and their respective counterparts
+
+  transformed_old_data.easy_diff(new_data)
+  #   => [{}, {}] # Two empty hashes, indicating no diffs.
+
+  transformed_new_data.easy_diff(old_data)
+  #   => [{}, {}] # Two empty hashes, indicating no diffs.
 
 == Install
 
   gem install easy_diff
 
-== Examples
+== Methods
 
 === Hash#easy_diff
 
-Takes another hash and recursively determines the differences between the two. This method returns two hashes.
+Takes another hash and recursively determines the differences between self and the other hash. This method returns two hashes.
 The first contains what has to be removed from self to create the second hash. The second contains what has to be added.
+When diffing arrays, the order of the arrays is ignored and only the contents are compared.
 
   original = {
     :tags => ['a', 'b', 'c'],
@@ -54,7 +139,7 @@ The first contains what has to be removed from self to create the second hash. T
 
 === Hash#easy_merge
 
-Takes a hash and recursively merges it with self. Arrays are merged by the union operation and then sorted. Arrays of Hashes are sorted by invoking +#sort+ on each Hash to make them comparable.
+Takes a hash and recursively merges it with self. Arrays are merged by concatenation.
 
 Using Hash#easy_merge! will modify self instead of returning a new hash.
 
@@ -90,8 +175,9 @@ Using Hash#easy_merge! will modify self instead of returning a new hash.
 
 === Hash#easy_unmerge
 
-Takes a hash and recursively unmerges it with self. By unmerging, I mean it will remove all matching values from
-the hash. All matching elements will be removed in arrays as well and then the arrays will be sorted.
+Takes a hash and recursively unmerges it with self. Unmerging means it will remove all matching values from the hash.
+Arrays will be unmerged by removing matching values in a non-greedy manner (i.e. [1, 1, 1] unmerged with [1] is [1, 1] instead of []).
+
 Using Hash#easy_unmerge! will modify self instead of returning a new hash.
 
   original = {

data/VERSION

@@ -1 +1 @@
-0.0.7
+1.0.0

data/lib/easy_diff/core.rb

@@ -6,61 +6,63 @@ module EasyDiff
 
       if original.nil?
         added = modified.safe_dup
+
       elsif modified.nil?
         removed = original.safe_dup
+
       elsif original.is_a?(Hash) && modified.is_a?(Hash)
         removed = {}
         added   = {}
-        original_keys   = original.keys
-        modified_keys   = modified.keys
-        keys_in_common  = original_keys & modified_keys
-        keys_removed    = original_keys - modified_keys
-        keys_added      = modified_keys - original_keys
+
+        keys_in_common  = original.keys & modified.keys
+        keys_removed    = original.keys - modified.keys
+        keys_added      = modified.keys - original.keys
+
         keys_removed.each{ |key| removed[key] = original[key].safe_dup }
         keys_added.each{ |key| added[key] = modified[key].safe_dup }
+
         keys_in_common.each do |key|
           r, a = easy_diff original[key], modified[key]
-          removed[key] = r unless _blank?(r)
-          added[key] = a unless _blank?(a)
+          unless _blank?(r) && _blank?(a)
+            removed[key] = r
+            added[key] = a
+          end
         end
+
       elsif original.is_a?(Array) && modified.is_a?(Array)
-        removed = original - modified
-        added   = modified - original
+        removed = subtract_arrays(original, modified)
+        added   = subtract_arrays(modified, original)
+
       elsif original != modified
         removed   = original
         added     = modified
       end
+
       return removed, added
     end
 
     def self.easy_unmerge!(original, removed)
       if original.is_a?(Hash) && removed.is_a?(Hash)
-        original_keys  = original.keys
-        removed_keys   = removed.keys
-        keys_in_common = original_keys & removed_keys
-        keys_in_common.each{ |key| original.delete(key) if easy_unmerge!(original[key], removed[key]).nil? }
+        keys_in_common = original.keys & removed.keys
+        keys_in_common.each do |key|
+          if original[key] == removed[key]
+            original.delete(key)
+          else
+            easy_unmerge!(original[key], removed[key])
+          end
+        end
       elsif original.is_a?(Array) && removed.is_a?(Array)
-        original.reject!{ |e| removed.include?(e) }
-        original.sort_by! { |item|
-          item.is_a?(Hash) ? item.sort : item
-        }
-      elsif original == removed
-        original = nil
+        subtract_arrays!(original, removed)
       end
       original
     end
 
     def self.easy_merge!(original, added)
-      if added.nil?
-        return original
-      elsif original.is_a?(Hash) && added.is_a?(Hash)
+      if original.is_a?(Hash) && added.is_a?(Hash)
         added_keys = added.keys
         added_keys.each{ |key| original[key] = easy_merge!(original[key], added[key])}
       elsif original.is_a?(Array) && added.is_a?(Array)
-        original |=  added
-        original.sort_by! { |item|
-          item.is_a?(Hash) ? item.sort : item
-        }
+        original +=  added
       else
         original = added.safe_dup
       end
@@ -71,6 +73,7 @@ module EasyDiff
       Marshal::load(Marshal.dump(original))
     end
 
+    # Can't use regular empty? because that affects strings.
     def self._blank?(obj)
       if obj.is_a?(Hash) || obj.is_a?(Array)
         obj.empty?
@@ -78,5 +81,23 @@ module EasyDiff
         obj.nil?
       end
     end
+
+    # Regular array difference does not handle duplicate values in the way that is needed for this library.
+    # Examples:
+    #   subtract_arrays([1, 1, 2, 3], [1, 2]) => [1, 3]
+    #   subtract_arrays([3, 3, 3, 4], [3, 4, 5]) => [3, 3]
+    # Shamelessly stolen from http://stackoverflow.com/questions/3852755/ruby-array-subtraction-without-removing-items-more-than-once
+    def self.subtract_arrays! arr1, arr2
+      counts = arr2.inject(Hash.new(0)) { |h, v| h[v] += 1; h }
+      arr1.reject! { |e| counts[e] -= 1 unless counts[e].zero? }
+    end
+
+    # Non-destructive version of above method.
+    def self.subtract_arrays arr1, arr2
+      cloned_arr1 = easy_clone(arr1)
+      subtract_arrays!(cloned_arr1, arr2)
+
+      cloned_arr1
+    end
   end
 end

data/spec/easy_diff_spec.rb

@@ -1,180 +1,62 @@
-require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+require File.expand_path(File.dirname(__FILE__) + "/spec_helper")
+require 'yaml'
 
 describe EasyDiff do
-  before :each do
-    @original = {
-      :tags => ['a', 'b', 'c'],
-      :pos => {:x => '1', :y => '2'},
-      :some_str => "bla",
-      :some_int => 1,
-      :some_bool => false,
-      :extra_removed => "bye"
-    }
 
-    @modified = {
-      :tags => ['b', 'c', 'd'],
-      :pos => {:x => '3', :y => '2'},
-      :some_str => "bla",
-      :some_int => 2,
-      :some_bool => true,
-      :extra_added => "hi"
-    }
+  let(:no_diffs) do
+    [{},{}]
+  end
 
-    @removed = {
-      :tags => ['a'],
-      :pos => {:x => '1'},
-      :some_int => 1,
-      :some_bool => false,
-      :extra_removed => "bye"
+  it "should do a deep clone" do
+    original = {
+      "pos" => {:x => 1, :y => 2}
     }
 
-    @added = {
-      :tags => ['d'],
-      :pos => {:x => '3'},
-      :some_int => 2,
-      :some_bool => true,
-      :extra_added => "hi"
-    }
-  end
-  it "should compute easy_diff" do
-    removed, added = @original.easy_diff @modified
-    removed.should == @removed
-    added.should == @added
-  end
+    cloned = original.easy_clone
+    cloned.should == original
 
-  it "should compute easy_unmerge" do
-    unmerged = @modified.easy_unmerge @added
-    unmerged.should == {
-      :tags => ['b', 'c'],
-      :pos => {:y => '2'},
-      :some_str => "bla"
-    }
+    cloned["pos"].delete(:x)
+    cloned.should_not == original
   end
 
-  it "should compute easy_merge" do
-   merged = @original.easy_merge @added
-   merged.should == {
-     :tags => ['a', 'b', 'c', 'd'],
-     :pos => {:x => '3', :y => '2'},
-     :some_str => "bla",
-     :some_int => 2,
-     :some_bool => true,
-     :extra_removed => "bye",
-     :extra_added => "hi"
-   }
-   @original.should == {
-      :tags => ['a', 'b', 'c'],
-      :pos => {:x => '1', :y => '2'},
-      :some_str => "bla",
-      :some_int => 1,
-      :some_bool => false,
-      :extra_removed => "bye"
-    }
-  end
+  # Tests that are dependent on the inputted data. Please edit or add
+  # to the test_data.yml file if you have data that breaks the gem.
 
-  it "should stay the same" do
-    removed, added = @original.easy_diff @modified
-    unmerged = @modified.easy_unmerge added
-    original = unmerged.easy_merge removed
-    original.should == @original
-  end
+  test_data_file = File.expand_path(File.dirname(__FILE__) + "/test_data.yml")
+  test_data = YAML.load_file test_data_file
 
-  it "should do a deep clone" do
-    cloned = @original.easy_clone
-    cloned.should == @original
-    cloned[:tags] << 'd'
-    cloned[:pos][:x] = '2'
-    cloned.should == {
-      :tags => ['a', 'b', 'c', 'd'],
-      :pos => {:x => '2', :y => '2'},
-      :some_str => "bla",
-      :some_int => 1,
-      :some_bool => false,
-      :extra_removed => "bye"
-    }
-    @original.should == {
-      :tags => ['a', 'b', 'c'],
-      :pos => {:x => '1', :y => '2'},
-      :some_str => "bla",
-      :some_int => 1,
-      :some_bool => false,
-      :extra_removed => "bye"
-    }
-  end
+  test_data.each do |test_case|
+    describe "handling #{test_case["name"]}" do
+      let(:original) do
+        test_case["original"]
+      end
 
-  it "should not show empty hashes or arrays as diffs" do
-    @modified[:tags] = @original[:tags]
-    @modified[:pos] = @original[:pos]
-    @removed.delete :pos
-    @removed.delete :tags
-    @added.delete :pos
-    @added.delete :tags
-    removed, added = @original.easy_diff @modified
-    removed.should == @removed
-    added.should == @added
-  end
+      let(:modified) do
+        test_case["modified"]
+      end
 
-  it "should show added empty hashes as a diff" do
-    @original[:empty_array] = []
-    @modified[:empty_hash] = {}
-    @removed[:empty_array] = []
-    @added[:empty_hash] = {}
-    removed, added = @original.easy_diff @modified
-    removed.should == @removed
-    added.should == @added
-  end
+      it "should compute easy_diff correctly" do
+        removed, added = original.easy_diff modified
 
-  it "should only check empty? on Hashes and Arrays" do
-    original = {:possibly_empty_string => ""}
-    modified = {:possibly_empty_string => "not empty"}
-    removed, added = original.easy_diff modified
-    removed.should == {:possibly_empty_string => ""}
-    added.should == {:possibly_empty_string => "not empty"}
-  end
+        removed.should == test_case["expected_removed"]
+        added.should == test_case["expected_added"]
+      end
 
-  describe 'handling Arrays containing Hashes' do
-    let(:original) do
-      {
-        "key" => [
-          {"c" => "1"},
-          {"a" => "2"},
-          {"a" => "1"},
-        ]
-      }
-    end
+      it "should be able to progress original hash to modified hash with no computed diffs" do
+        removed, added = original.easy_diff modified
 
-    it "should merge properly" do
-      to_merge = {
-        "key" => [
-          {"b" => "2"},
-        ]
-      }
-
-      merged = original.easy_merge to_merge
-      merged.should == {
-        "key" => [
-          {"a" => "1"},
-          {"a" => "2"},
-          {"b" => "2"},
-          {"c" => "1"},
-        ]
-      }
-    end
+        progressed = original.easy_unmerge(removed).easy_merge(added)
+
+        modified.easy_diff(progressed).should == no_diffs
+      end
+
+      it "should be able to reverse modified hash to original hash with no computed diffs" do
+        removed, added = original.easy_diff modified
+
+        reversed = modified.easy_unmerge(added).easy_merge(removed)
 
-    it "should unmerge properly" do
-      to_unmerge = {
-        "key" => [
-          {"a" => "2"},
-        ]
-      }
-
-      unmerged = original.easy_unmerge to_unmerge
-      unmerged.should == {
-        "key" => [
-          {"a" => "1"},
-          {"c" => "1"},
-        ]
-      }
+        original.easy_diff(reversed).should == no_diffs
+      end
     end
   end
 end

data/spec/test_data.yml

@@ -0,0 +1,239 @@
+---
+- # Basic test cases on nested Hashes and Arrays
+  name: "simple cases with nested Hashes and Arrays"
+  original:
+    tags:
+      - "a"
+      - "b"
+      - "c"
+    pos:
+      x: "1"
+      y: "2"
+    some_str: "bla"
+    some_int: 1
+    some_bool: false
+    extra_removed: "bye"
+  modified:
+    tags:
+      - "b"
+      - "c"
+      - "d"
+    pos:
+      x: "3"
+      y: "2"
+    some_str: "bla"
+    some_int: 2
+    some_bool: true
+    extra_added: "hi"
+  expected_removed:
+    tags:
+      - "a"
+    pos:
+      x: "1"
+    some_int: 1
+    some_bool: false
+    extra_removed: "bye"
+  expected_added:
+    tags:
+      - "d"
+    pos:
+      x: "3"
+    some_int: 2
+    some_bool: true
+    extra_added: "hi"
+
+- # Test case where Arrays have duplicate values
+  name: "Arrays with duplicate values"
+  original:
+    key:
+      - 1
+      - 1
+      - 1
+      - 2
+      - 3
+      - 4
+  modified:
+    key:
+      - 1
+      - 3
+      - 4
+      - 4
+  expected_removed:
+    key:
+      - 1
+      - 1
+      - 2
+  expected_added:
+    key:
+      - 4
+
+- # Test case where nil values of Hashes are expected to be preserved
+  name: "Hashes with nil values"
+  original:
+    old_nil: ~
+    new_nil: "foo"
+    still_nil: ~
+    removed_nil: ~
+  modified:
+    old_nil: "bar"
+    new_nil: ~
+    still_nil: ~
+    added_nil: ~
+  expected_removed:
+    old_nil: ~
+    new_nil: "foo"
+    removed_nil: ~
+  expected_added:
+    old_nil: "bar"
+    new_nil: ~
+    added_nil: ~
+
+- # Test case where an empty Hash is compared to a Hash with one nil
+  # value in it.
+  name: "an empty Hash being compared to a Hash with a nil value"
+  original: {}
+  modified:
+    key: ~
+  expected_removed: {}
+  expected_added:
+    key: ~
+
+- # Test case where nil values of Arrays are expected to be preserved
+  name: "Arrays with nil values"
+  original:
+    key:
+      - 5
+      - "hi"
+  modified:
+    key:
+      - 5
+      - "hi"
+      - ~
+  expected_removed:
+    key: []
+  expected_added:
+    key:
+      - ~
+
+- # Test case where an empty Array is compared to an Array with one
+  # nil value in it.
+  name: "an empty Array being compared to an Array with a nil value"
+  original:
+    key: []
+  modified:
+    key:
+      - ~
+  expected_removed:
+    key: []
+  expected_added:
+    key:
+      - ~
+
+- # Test case where nested Hashes and Arrays that are identical are
+  # expected to not show up as empty Hashes and Arrays in diffs.
+  name: "matching nested Hashes and Arrays"
+  original:
+    hash:
+      foo: "bar"
+    array:
+      - 1
+      - 2
+      - 3
+    extra: "apples"
+  modified:
+    hash:
+      foo: "bar"
+    array:
+      - 1
+      - 2
+      - 3
+    extra: "oranges"
+  expected_removed:
+    extra: "apples"
+  expected_added:
+    extra: "oranges"
+
+- # Test case where empty Hashes and Arrays that are added or removed
+  # are expected to show up in diffs.
+  name: "empty Hashes and Arrays"
+  original:
+    foo: "bar"
+  modified:
+    empty_hash: {}
+    empty_array: []
+    foo: "bar"
+  expected_removed: {}
+  expected_added:
+    empty_hash: {}
+    empty_array: []
+
+-
+  name: "empty Strings"
+  original:
+    possibly_empty_string: ""
+  modified:
+    possibly_empty_string: "not empty"
+  expected_removed:
+    possibly_empty_string: ""
+  expected_added:
+    possibly_empty_string: "not empty"
+
+- # Test case where Arrays containing Hashes are expected to not
+  # cause an error.
+  name: "Arrays containing Hashes"
+  original:
+    key:
+      -
+        c: "1"
+      -
+        a: "2"
+      -
+        a: "1"
+  modified:
+    key:
+      -
+        c: "1"
+      -
+        b: "2"
+      -
+        a: "1"
+  expected_removed:
+    key:
+      -
+        a: "2"
+  expected_added:
+    key:
+      -
+        b: "2"
+
+- # Test case where Arrays containing Hashes with nils are expected
+  # to not cause an error.
+  name: "Arrays containing Hashes with nils"
+  original:
+    key:
+      -
+        a: "1"
+        b: "2"
+      -
+        a: ~
+        c: "2"
+      -
+        e: "5"
+  modified:
+    key:
+      -
+        a: "1"
+        b: "2"
+      -
+        a: ~
+        c: "2"
+      -
+        d: "4"
+  expected_removed:
+    key:
+      -
+        e: "5"
+  expected_added:
+    key:
+      -
+        d: "4"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: easy_diff
 version: !ruby/object:Gem::Version
-  version: 0.0.7
+  version: 1.0.0
 platform: ruby
 authors:
 - Abner Qian
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-01-07 00:00:00.000000000 Z
+date: 2016-01-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -92,6 +92,7 @@ files:
 - lib/easy_diff/safe_dup.rb
 - spec/easy_diff_spec.rb
 - spec/spec_helper.rb
+- spec/test_data.yml
 homepage: http://github.com/Blargel/easy_diff
 licenses:
 - MIT