update README

Author: markburns

README.md

@@ -2,17 +2,40 @@
 
 This allows you to get detailed error messages on exactly where your heavily nested hashes differ
 
-## Installation
+### Example
+```ruby
+actual   = {b: {c: 1, [{d: {e: 'actual_value'}}]}}
+expected = {b: {c: 5, [{d: {e: 'expected_value'}}]}}
+
+aggregate_failures do
+  expect_deep_matching(actual, expected)
+end
+```
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+#### Fails with
 
-Install the gem and add to the application's Gemfile by executing:
+```
+  Got 2 failures from failure aggregation block
+  1) Expected nested hash key at 'b.c'
+        to eq
+        # 5,
+        but got
+        1
+  2) Expected nested hash key at 'b.[0].d.e'
+        to eq
+        # 'expected_value',
+        but got
+        'actual_value'
+```
 
-    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+Note, only keys in the expected hash are checked.  If the actual hash has extra keys, they are ignored.
+In this way it acts somewhat like `expect(actual).to match(hash_including(expected))`
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+## Installation
 
-    $ gem install UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+```
+gem 'deep_matching'
+```
 
 ## Usage
 

spec/deep_matching_spec.rb

@@ -42,7 +42,7 @@
     expect_failure(actual, expected, path: 'b.c.2.d', expected_value: '"expected"', got: '"actual"')
   end
 
-  it 'produces multiple failure messages' do
+  it 'produces multiple failure messages when used with aggregate_failures' do
     actual   = {a: 1, b: {c: [1, 2, {d: 'actual'  }]}}
     expected = {a: 2, b: {c: [1, 2, {d: 'expected'}]}}
 
@@ -74,14 +74,6 @@
     FAILURE
   end
 
-  def expect_in_message(message, expected)
-    expect(message).to include(expected.chomp.gsub(/^\s+/, ''))
-  end
-
-  def expect_success(actual, expected)
-    expect_deep_matching(actual, expected)
-  end
-
   def expect_multiple_failures(actual, expected)
     @raised_messages = []
 
@@ -94,6 +86,15 @@ def expect_multiple_failures(actual, expected)
     @raised_messages << e.message
   end
 
+
+  def expect_in_message(message, expected)
+    expect(message).to include(expected.chomp.gsub(/^\s+/, ''))
+  end
+
+  def expect_success(actual, expected)
+    expect_deep_matching(actual, expected)
+  end
+
   def expect_failure(actual, expected, expected_failure)
     expected_value = expected_failure[:expected_value]
     got = expected_failure[:got]