hashdiff 0.0.2 → 0.0.3

data/.travis.yml

@@ -1,8 +1,11 @@
+language: ruby
 rvm:
   - 1.8.7
   - 1.9.2
+  - 1.9.3
   - rbx
   - rbx-2.0
   - ree
   - jruby
   - ruby-head
+script: "bundle exec rake spec"

data/.yardopts

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

data/README.md

@@ -9,15 +9,28 @@ HashDiff is tested on following platforms:
 
 - 1.8.7
 - 1.9.2
+- 1.9.3
 - rbx
 - rbx-2.0
 - ree
 - jruby
 - ruby-head
 
+Usage
+------------
+If you're using bundler, add following:
+
+    gem 'hashdiff'
+
+Or, you can run `gem install hashdiff`, then add following line to your ruby file which uses HashDiff:
+
+    require 'hashdiff'
+
 Quick Start
 -----------
 
+You can find full docs here: [Documentation](http://rubydoc.info/gems/hashdiff)
+
 ### Diff
 
 Two simple hash:
@@ -41,7 +54,7 @@ Array in hash:
     a = {a:[{x:2, y:3, z:4}, {x:11, y:22, z:33}], b:{x:3, z:45}}
     b = {a:[{y:3}, {x:11, z:33}], b:{y:22}}
 
-    diff = HashDiff.best_diff(a, b) # best_diff will try to match similar objects in array in order to generate the smallest change set
+    diff = HashDiff.best_diff(a, b)
     diff.should == [['-', 'a[0].x', 2], ['-', 'a[0].z', 4], ['-', 'a[1].y', 22], ['-', 'b.x', 3], ['-', 'b.z', 45], ['+', 'b.y', 22]]
 
 ### Patch

data/lib/hashdiff/diff.rb

@@ -1,6 +1,22 @@
 module HashDiff
 
-  # try to make the best diff that generates the smallest change set
+  # Best diff two objects, which tries to generate the smallest change set.
+  #
+  # HashDiff.best_diff is only meaningful in case of comparing two objects which includes similar objects in array.
+  #
+  # @param [Arrary, Hash] obj1
+  # @param [Arrary, Hash] obj2
+  #
+  # @return [Array] an array of changes.
+  #   e.g. [[ '+', 'a.b', '45' ], [ '-', 'a.c', '5' ], [ '~', 'a.x', '45', '63']]
+  #
+  # @example
+  #   a = {'x' => [{'a' => 1, 'c' => 3, 'e' => 5}, {'y' => 3}]}
+  #   b = {'x' => [{'a' => 1, 'b' => 2, 'e' => 5}] }
+  #   diff = HashDiff.best_diff(a, b)
+  #   diff.should == [['-', 'x[0].c', 3], ['+', 'x[0].b', 2], ['-', 'x[1].y', 3], ['-', 'x[1]', {}]]
+  #
+  # @since 0.0.1
   def self.best_diff(obj1, obj2)
     diffs_1 = diff(obj1, obj2, "", 0.3)
     diffs_2 = diff(obj1, obj2, "", 0.5)
@@ -10,30 +26,36 @@ module HashDiff
     diffs = diffs.size < diffs_3.size ? diffs : diffs_3
   end
 
-  # compute the diff of two hashes, return an array of changes
-  # e.g. [[ '+', 'a.b', '45' ], [ '-', 'a.c', '5' ], [ '~', 'a.x', '45', '63']]
+  # Compute the diff of two hashes
+  #
+  # @param [Arrary, Hash] obj1
+  # @param [Arrary, Hash] obj2
+  # @param [float] similarity A value > 0 and <= 1.
+  #   This parameter should be ignored in common usage.
+  #   Similarity is only meaningful if there're similar objects in arrays. See {best_diff}.
+  #
+  # @return [Array] an array of changes.
+  #   e.g. [[ '+', 'a.b', '45' ], [ '-', 'a.c', '5' ], [ '~', 'a.x', '45', '63']]
+  #
+  # @example
+  #   a = {"a" => 1, "b" => {"b1" => 1, "b2" =>2}}
+  #   b = {"a" => 1, "b" => {}}
   #
-  # NOTE: diff will treat nil as [], {} or "" in comparison according to different context.
-  # 
+  #   diff = HashDiff.diff(a, b)
+  #   diff.should == [['-', 'b.b1', 1], ['-', 'b.b2', 2]]
+  #
+  # @since 0.0.1
   def self.diff(obj1, obj2, prefix = "", similarity = 0.8)
+    if obj1.nil? and obj2.nil?
+      return []
+    end
+
     if obj1.nil?
-      if obj2.is_a?(Array)
-        return diff([], obj2, prefix, similarity)
-      elsif obj2.is_a?(Hash)
-        return diff({}, obj2, prefix, similarity)
-      else
-        return diff('', obj2, prefix, similarity)
-      end
+      return [['-', prefix, nil]] + changed(obj2, '+', prefix)
     end
 
     if obj2.nil?
-      if obj1.is_a?(Array)
-        return diff(obj1, [], prefix, similarity)
-      elsif obj1.is_a?(Hash)
-        return diff(obj1, {}, prefix, similarity)
-      else
-        return diff(obj1, '', prefix, similarity)
-      end
+      return changed(obj1, '-', prefix) + [['+', prefix, nil]]
     end
 
     if !(obj1.is_a?(Array) and obj2.is_a?(Array)) and !(obj1.is_a?(Hash) and obj2.is_a?(Hash)) and !(obj1.is_a?(obj2.class) or obj2.is_a?(obj1.class))
@@ -90,6 +112,8 @@ module HashDiff
     result
   end
 
+  # @private
+  #
   # diff array using LCS algorithm
   def self.diff_array(a, b, similarity = 0.8)
     change_set = []

data/lib/hashdiff/lcs.rb

@@ -1,5 +1,6 @@
 module HashDiff
-
+  # @private
+  #
   # caculate array difference using LCS algorithm
   # http://en.wikipedia.org/wiki/Longest_common_subsequence_problem
   def self.lcs(a, b, similarity = 0.8)

data/lib/hashdiff/patch.rb

@@ -1,22 +1,27 @@
 # 
-# This class provides methods to diff two hash, patch and unpatch hash
+# This module provides methods to diff two hash, patch and unpatch hash
 #
 module HashDiff
 
-  # apply changes to object
+  # Apply patch to object
   #
-  # changes: [[ '+', 'a.b', '45' ], [ '-', 'a.c', '5' ], [ '~', 'a.x', '45', '63']]
-  def self.patch(hash, changes)
+  # @param [Hash, Array] obj the object to be patchted, can be an Array of a Hash
+  # @param [Array] changes e.g. [[ '+', 'a.b', '45' ], [ '-', 'a.c', '5' ], [ '~', 'a.x', '45', '63']]
+  #
+  # @return the object after patch
+  #
+  # @since 0.0.1
+  def self.patch!(obj, changes)
     changes.each do |change|
       parts = decode_property_path(change[1])
       last_part = parts.last
 
-      dest_node = node(hash, parts[0, parts.size-1])
+      dest_node = node(obj, parts[0, parts.size-1])
 
       if change[0] == '+'
         if dest_node == nil
           parent_key = parts[parts.size-2]
-          parent_node = node(hash, parts[0, parts.size-2])
+          parent_node = node(obj, parts[0, parts.size-2])
           if last_part.is_a?(Fixnum)
             dest_node = parent_node[parent_key] = []
           else
@@ -40,13 +45,18 @@ module HashDiff
       end
     end
 
-    hash
+    obj
   end
 
-  # undo changes from object.
+  # Unpatch an object
+  #
+  # @param [Hash, Array] obj the object to be unpatchted, can be an Array of a Hash
+  # @param [Array] changes e.g. [[ '+', 'a.b', '45' ], [ '-', 'a.c', '5' ], [ '~', 'a.x', '45', '63']]
+  #
+  # @return the object after unpatch
   #
-  # changes: [[ '+', 'a.b', '45' ], [ '-', 'a.c', '5' ], [ '~', 'a.x', '45', '63']]
-  def self.unpatch(hash, changes)
+  # @since 0.0.1
+  def self.unpatch!(hash, changes)
     changes.reverse_each do |change|
       parts = decode_property_path(change[1])
       last_part = parts.last

data/lib/hashdiff/util.rb

@@ -1,5 +1,7 @@
 module HashDiff
 
+  # @private
+  #
   # return an array of added properties
   # e.g. [[ '+', 'a.b', 45 ], [ '-', 'a.c', 5 ]]
   def self.changed(obj, sign, prefix = "")
@@ -35,6 +37,8 @@ module HashDiff
     results
   end
 
+  # @private
+  #
   # judge whether two objects are similar
   def self.similiar?(a, b, similarity = 0.8)
     count_a = count_nodes(a)
@@ -48,6 +52,8 @@ module HashDiff
     end
   end
 
+  # @private
+  #
   # count total nodes for an object
   def self.count_nodes(obj)
     return 0 unless obj
@@ -66,6 +72,8 @@ module HashDiff
     count
   end
 
+  # @private
+  #
   # decode property path into an array
   #
   # e.g. "a.b[3].c" => ['a', 'b', 3, 'c']
@@ -85,6 +93,8 @@ module HashDiff
     parts.flatten
   end
 
+  # @private
+  #
   # get the node of hash by given path parts
   def self.node(hash, parts)
     temp = hash

data/lib/hashdiff/version.rb

@@ -1,3 +1,3 @@
 module HashDiff
-  VERSION = '0.0.2'
+  VERSION = '0.0.3'
 end

data/spec/hashdiff/diff_spec.rb

@@ -67,13 +67,12 @@ describe HashDiff do
     diff.should == [['-', 'b[1]', 2], ['-', 'b[0]', 1]]
   end
 
-  # treat nil as empty array
   it "should be able to diff value changes: array <=> nil" do
     a = {"a" => 1, "b" => [1, 2]}
     b = {"a" => 1, "b" => nil}
 
     diff = HashDiff.diff(a, b)
-    diff.should == [['-', 'b[1]', 2], ['-', 'b[0]', 1]]
+    diff.should == [['-', 'b[1]', 2], ['-', 'b[0]', 1], ['-', 'b', []], ['+', 'b', nil]]
   end
 
   it "should be able to diff value chagnes: remove array completely" do
@@ -100,13 +99,12 @@ describe HashDiff do
     diff.should == [['-', 'b.b1', 1], ['-', 'b.b2', 2]]
   end
 
-  # treat nil as empty hash
   it "should be able to diff value changes: hash <=> nil" do
     a = {"a" => 1, "b" => {"b1" => 1, "b2" =>2}}
     b = {"a" => 1, "b" => nil}
 
     diff = HashDiff.diff(a, b)
-    diff.should == [['-', 'b.b1', 1], ['-', 'b.b2', 2]]
+    diff.should == [['-', 'b.b1', 1], ['-', 'b.b2', 2], ['-', 'b', {}], ['+', 'b', nil]]
   end
 
   it "should be able to diff similar objects in array" do

data/spec/hashdiff/patch_spec.rb

@@ -6,11 +6,11 @@ describe HashDiff do
     b = {"a"=>3, "c"=>11, "d"=>45, "e"=>100, "f"=>200, "g"=>300}
     diff = HashDiff.diff(a, b)
 
-    HashDiff.patch(a, diff).should == b
+    HashDiff.patch!(a, diff).should == b
 
     a = {"a"=>3, "c"=>11, "d"=>45, "e"=>100, "f"=>200}
     b = {"a"=>3, "c"=>11, "d"=>45, "e"=>100, "f"=>200, "g"=>300}
-    HashDiff.unpatch(b, diff).should == a
+    HashDiff.unpatch!(b, diff).should == a
   end
 
   it "should be able to patch value type changes" do
@@ -18,11 +18,11 @@ describe HashDiff do
     b = {"a" => {"a1" => 1, "a2" => 2}}
     diff = HashDiff.diff(a, b)
 
-    HashDiff.patch(a, diff).should == b
+    HashDiff.patch!(a, diff).should == b
 
     a = {"a" => 3}
     b = {"a" => {"a1" => 1, "a2" => 2}}
-    HashDiff.unpatch(b, diff).should == a
+    HashDiff.unpatch!(b, diff).should == a
   end
 
   it "should be able to patch value array <=> []" do
@@ -30,11 +30,11 @@ describe HashDiff do
     b = {"a" => 1, "b" => []}
     diff = HashDiff.diff(a, b)
 
-    HashDiff.patch(a, diff).should == b
+    HashDiff.patch!(a, diff).should == b
 
     a = {"a" => 1, "b" => [1, 2]}
     b = {"a" => 1, "b" => []}
-    HashDiff.unpatch(b, diff).should == a
+    HashDiff.unpatch!(b, diff).should == a
   end
 
   it "should be able to patch value array <=> nil" do
@@ -42,12 +42,11 @@ describe HashDiff do
     b = {"a" => 1, "b" => nil}
     diff = HashDiff.diff(a, b)
 
-    # NOTE: nil is treated as [] in this context
-    HashDiff.patch(a, diff).should == {"a" => 1, "b" => []}
+    HashDiff.patch!(a, diff).should == b
 
     a = {"a" => 1, "b" => [1, 2]}
     b = {"a" => 1, "b" => nil}
-    HashDiff.unpatch(b, diff).should == a
+    HashDiff.unpatch!(b, diff).should == a
   end
 
   it "should be able to patch array value removal" do
@@ -55,11 +54,11 @@ describe HashDiff do
     b = {"a" => 1}
     diff = HashDiff.diff(a, b)
 
-    HashDiff.patch(a, diff).should == b
+    HashDiff.patch!(a, diff).should == b
 
     a = {"a" => 1, "b" => [1, 2]}
     b = {"a" => 1}
-    HashDiff.unpatch(b, diff).should == a
+    HashDiff.unpatch!(b, diff).should == a
   end
 
   it "should be able to patch hash value removal" do
@@ -67,11 +66,11 @@ describe HashDiff do
     b = {"a" => 1}
     diff = HashDiff.diff(a, b)
 
-    HashDiff.patch(a, diff).should == b
+    HashDiff.patch!(a, diff).should == b
 
     a = {"a" => 1, "b" => {"b1" => 1, "b2" =>2}}
     b = {"a" => 1}
-    HashDiff.unpatch(b, diff).should == a
+    HashDiff.unpatch!(b, diff).should == a
   end
 
   it "should be able to patch value hash <=> {}" do
@@ -79,11 +78,11 @@ describe HashDiff do
     b = {"a" => 1, "b" => {}}
     diff = HashDiff.diff(a, b)
 
-    HashDiff.patch(a, diff).should == b
+    HashDiff.patch!(a, diff).should == b
 
     a = {"a" => 1, "b" => {"b1" => 1, "b2" =>2}}
     b = {"a" => 1, "b" => {}}
-    HashDiff.unpatch(b, diff).should == a
+    HashDiff.unpatch!(b, diff).should == a
   end
 
   it "should be able to patch value hash <=> nil" do
@@ -91,12 +90,11 @@ describe HashDiff do
     b = {"a" => 1, "b" => nil}
     diff = HashDiff.diff(a, b)
 
-    # NOTE: nil will be taken as {} in the context
-    HashDiff.patch(a, diff).should == {"a" => 1, "b" => {}}
+    HashDiff.patch!(a, diff).should == b
 
     a = {"a" => 1, "b" => {"b1" => 1, "b2" =>2}}
     b = {"a" => 1, "b" => nil}
-    HashDiff.unpatch(b, diff).should == a
+    HashDiff.unpatch!(b, diff).should == a
   end
 
   it "should be able to patch value nil removal" do
@@ -104,11 +102,11 @@ describe HashDiff do
     b = {"a" => 1}
     diff = HashDiff.diff(a, b)
 
-    HashDiff.patch(a, diff).should == b
+    HashDiff.patch!(a, diff).should == b
 
     a = {"a" => 1, "b" => nil}
     b = {"a" => 1}
-    HashDiff.unpatch(b, diff).should == a
+    HashDiff.unpatch!(b, diff).should == a
   end
 
   it "should be able to patch similar objects between arrays" do
@@ -116,11 +114,11 @@ describe HashDiff do
     b = [1, {'a' => 1, 'b' => 2, 'c' => 3, 'e' => 5}]
 
     diff = HashDiff.diff(a, b)
-    HashDiff.patch(a, diff).should == b
+    HashDiff.patch!(a, diff).should == b
 
     a = [{'a' => 1, 'b' => 2, 'c' => 3, 'd' => 4, 'e' => 5}, 3]
     b = [1, {'a' => 1, 'b' => 2, 'c' => 3, 'e' => 5}]
-    HashDiff.unpatch(b, diff).should == a
+    HashDiff.unpatch!(b, diff).should == a
   end
 
   it "should be able to patch similar & equal objects between arrays" do
@@ -128,11 +126,11 @@ describe HashDiff do
     b = [1, {'a' => 1, 'b' => 2, 'c' => 3, 'e' => 5}]
 
     diff = HashDiff.diff(a, b)
-    HashDiff.patch(a, diff).should == b
+    HashDiff.patch!(a, diff).should == b
 
     a = [{'a' => 1, 'b' => 2, 'c' => 3, 'd' => 4, 'e' => 5}, {'x' => 5, 'y' => 6, 'z' => 3}, 1]
     b = [1, {'a' => 1, 'b' => 2, 'c' => 3, 'e' => 5}]
-    HashDiff.unpatch(b, diff).should == a
+    HashDiff.unpatch!(b, diff).should == a
   end
 
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hashdiff
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-22 00:00:00.000000000Z
+date: 2012-06-03 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &8876060 !ruby/object:Gem::Requirement
+  requirement: &14927020 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,10 +21,10 @@ dependencies:
         version: '2.0'
   type: :development
   prerelease: false
-  version_requirements: *8876060
+  version_requirements: *14927020
 - !ruby/object:Gem::Dependency
   name: yard
-  requirement: &8874480 !ruby/object:Gem::Requirement
+  requirement: &14926640 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *8874480
+  version_requirements: *14926640
 - !ruby/object:Gem::Dependency
   name: bluecloth
-  requirement: &8859740 !ruby/object:Gem::Requirement
+  requirement: &14926180 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,7 +43,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *8859740
+  version_requirements: *14926180
 description: ! ' HashDiff is a diff lib to compute the smallest difference between
   two hashes. '
 email:
@@ -55,6 +55,7 @@ files:
 - .gitignore
 - .rspec
 - .travis.yml
+- .yardopts
 - Gemfile
 - Gemfile.lock
 - README.md