Merge nil values or keep the original via an option

For some people, it's unexpected that explicitly merging in a nil will
not overwrite an existing value.
`DeepMerge::deep_merge({:a => nil}, {:a => 1})`

Currently, we retain the 1 value.
My expectation is we'd get a nil value.

Since changing this is a change in behavior, and possibly not desirable,
I'm exposing an option to opt-in to this new behavior.

Note, this is related to danielsdeleo#20 and can be confusing to see the difference.
This commit handles merging a nil value into an existing destination via
an option.
PR danielsdeleo#20 handles NOT merging a value into an already nil destination.

lib/deep_merge/core.rb

@@ -94,10 +94,12 @@ def self.deep_merge!(source, dest, options = {})
     extend_existing_arrays = options[:extend_existing_arrays] || false
     # request that arrays keep duplicate elements
     keep_array_duplicates = options[:keep_array_duplicates] || false
+    # request that nil values are discarded
+    discard_nil_values = options.fetch(:discard_nil_values, true)
 
     di = options[:debug_indent] || ''
     # do nothing if source is nil
-    return dest if source.nil?
+    return dest if discard_nil_values && source.nil?
     # if dest doesn't exist, then simply copy source to it
     if !(dest) && overwrite_unmergeable
       dest = source; return dest

test/test_deep_merge.rb

@@ -630,7 +630,22 @@ def test_deep_merge
     DeepMerge::deep_merge!(hash_src, hash_dst, {:keep_array_duplicates => true})
     assert_equal({"item" => ["1", "2", "2", "3"]}, hash_dst)
 
-
-
+    # discard nil value by default
+    hash_src = {"item" => nil}
+    hash_dst = {"item" => 'existing'}
+    DeepMerge::deep_merge!(hash_src, hash_dst)
+    assert_equal({"item" => 'existing'}, hash_dst)
+
+    # discard nil value via discard_nil_values => true
+    hash_src = {"item" => nil}
+    hash_dst = {"item" => 'existing'}
+    DeepMerge::deep_merge!(hash_src, hash_dst, {:discard_nil_values => true})
+    assert_equal({"item" => 'existing'}, hash_dst)
+
+    # keep nil value via discard_nil_values => false
+    hash_src = {"item" => nil}
+    hash_dst = {"item" => 'existing'}
+    DeepMerge::deep_merge!(hash_src, hash_dst, {:discard_nil_values => false})
+    assert_equal({"item" => nil}, hash_dst)
   end # test_deep_merge
 end