refinements 14.5.0 → 14.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 730d2c8e3fd694a24d88c05755eec1599b26002fd7317131c795e5752ed16fb5
-  data.tar.gz: 5611e41668a0570ae5944569bee6b54e7b47176a37831ba8817c20c63edb2840
+  metadata.gz: 9d163c074a4394a9a24c358a571a7679e20667bcdf1321d2e62e39419f4b07f2
+  data.tar.gz: 1cbe04caef72d6b58c580f4cb2b255421cc12fe7b9f56187aa13537b3ae10638
 SHA512:
-  metadata.gz: 4314a271e2c4ab6f0c5d4d0f2e4c56d13b68b4e7d5f11b46ffb3e477f1a7770d44c0a670e7fee640cec6f2df74daee191eaf5b764a379b7c17a9e0011328fd20
-  data.tar.gz: 1eca09b429c622b3365b6cf5d2905313cebffa45264ac25684bba65332f70e58934c301655ee6651f96a3c5c59df526aeeb50e4aa5e02e126f0db1f7c8795d15
+  metadata.gz: b5e5ec861754742185981115feeaf58f32d79eb3c85bff1e59ae839815d6723d4e9a9b2a22c85a3bbf016386385b952b55c741c4654e98aa0a95caee5694e8b7
+  data.tar.gz: c8abd9681ea04eb860b796f0e96e35f7954700c54d0c11a0bf8f2fab0d0385e05f9ad235b0592daaad5476088b5d6fa27492fea1cb64672fe1605cfa80e43e4a

data/README.adoc

@@ -463,10 +463,10 @@ Any object that _is not_ the same type will have a `nil` value as shown in the l
 
 ===== .utc
 
-Answers new DateTime object for current UTC date/time.
-
 ⚠️ This method (and refinement) is deprecated and will be removed in the next major release.
 
+Answers new DateTime object for current UTC date/time.
+
 [source,ruby]
 ----
 DateTime.utc # "#<DateTime: 2019-12-31T18:17:00+00:00 ((2458849j,65820s,181867000n),+0s,2299161j)>"
@@ -534,10 +534,34 @@ Merges deeply nested hashes together without mutating itself.
 
 [source,ruby]
 ----
-example = {a: "A", b: {one: "One", two: "Two"}}
+example = {demo: {one: "One"}}
+
+example.deep_merge demo: {one: 1}  # {demo: {one: 1}}
+example                            # {demo: {one: "One"}}
+----
+
+Nested arrays are concatenated:
 
-example.deep_merge b: {one: 1}  # {a: "A", b: {one: 1, two: "Two"}}
-example                         # {a: "A", b: {one: "One", two: "Two"}}
+[source,ruby]
+----
+{demo: [1, 2]}.deep_merge(demo: [3, 4])
+# {demo: [1, 2, 3, 4]}
+----
+
+Arrays are concatenated by index so ensure both arrays are in the same order when needing to merge nested arrays and/or hashes. If the other array has more elements which are not arrays or hashes, they will be appended. Example:
+
+[source,ruby]
+----
+{demo: [1, [2, 3], {a: 1}]}.deep_merge(demo: [:a, [4, 5], {a: :one, b: :two}, 6])
+# {
+#   demo: [
+#     1,
+#     [2, 3, 4, 5],
+#     {a: :one, b: :two},
+#     :a
+#     6
+#   ]
+# }
 ----
 
 ===== #deep_merge!
@@ -552,6 +576,8 @@ example.deep_merge! b: {one: 1}  # {a: "A", b: {one: 1, two: "Two"}}
 example                          # {a: "A", b: {one: 1, two: "Two"}}
 ----
 
+For more example, see `+#deep_merge+` above.
+
 ===== #deep_stringify_keys
 
 Answers string keys of a nested hash without mutating itself. Does not handle nested arrays, though.
@@ -616,6 +642,52 @@ one.diff Object.new  # {:a=>[1, nil], :b=>[2, nil], :c=>[3, nil]}
 
 Any object that _is not_ the same type will have a `nil` value as shown in the last two examples. Two hashes with the same keys but defined in different order behave as if they had the same key order.
 
+===== #expand_keys
+
+Allows you to expand flat keys into a nested hash. This is the reverse of `+#flatten_keys+`.
+
+[source,ruby]
+----
+{"a.a" => 0, "a.b.one" => 1, "a.b.two" => 2}.expand_keys
+
+# {
+#   "a" => {
+#     "a" => 0,
+#     "b" => {
+#       "one" => 1,
+#       "two" => 2
+#     }
+#   }
+# }
+
+{"a_a" => 0, "a_b_one" => 1, "a_b_two" => 2}.expand_keys delimiter: "_"
+
+# {
+#   "a" => {
+#     "a" => 0,
+#     "b" => {
+#       "one" => 1,
+#       "two" => 2
+#     }
+#   }
+# }
+----
+
+Parent values -- which are not hashes -- are ignored when a nested child hash exists. Example:
+
+[source,ruby]
+----
+{"a" => 0, "a.b" => 1, "a.b.one" => :test}.expand_keys
+
+# {
+#   "a" => {
+#     "b" => {
+#       "one" => :test
+#     }
+#   }
+# }
+----
+
 ===== #fetch_deep
 
 Fetches a nested value by combining the behavior of `#fetch` and `#dig` into a single method. This works with nested arrays too. Examples:
@@ -853,6 +925,8 @@ example  # {name: "Jayne", email: "jd@example.com"}
 
 ===== #use
 
+⚠️ This method is deprecated and will be removed in the next major release.
+
 Uses the hash's keys as block arguments where the value of the block argument is equal to the value of the key found within the hash. Works best with hashes that use symbols for keys but falls back to string keys when symbol keys can't be found.
 
 [source,ruby]

data/lib/refinements/hash.rb

@@ -4,6 +4,7 @@ require "refinements/shared/many"
 
 module Refinements
   # Provides additional enhancements to the Hash primitive.
+  # rubocop:todo-next Metrics/ModuleLength
   module Hash
     refine ::Hash.singleton_class do
       def infinite = new { |nascence, lacuna| nascence[lacuna] = new(&nascence.default_proc) }
@@ -21,20 +22,20 @@ module Refinements
         compact!
       end
 
-      def deep_merge other
-        clazz = self.class
+      def deep_merge(other, &) = dup.deep_merge!(other, &)
 
-        merge other do |_key, this_value, other_value|
-          if this_value.is_a?(clazz) && other_value.is_a?(clazz)
-            this_value.deep_merge other_value
-          else
-            other_value
+      def deep_merge!(other, &)
+        klass = self.class
+
+        merge! other do |key, first, second|
+          if first.is_a?(klass) && second.is_a?(klass) then first.deep_merge(second, &)
+          elsif first.is_a?(::Array) && second.is_a?(::Array) then deep_concat(first, second, &)
+          elsif block_given? then yield key, first, second
+          else second
           end
         end
       end
 
-      def deep_merge!(other) = replace(deep_merge(other))
-
       def deep_stringify_keys = recurse(&:stringify_keys)
 
       def deep_stringify_keys! = replace(deep_stringify_keys)
@@ -44,11 +45,18 @@ module Refinements
       def deep_symbolize_keys! = replace(deep_symbolize_keys)
 
       def diff other
-        return differences_from other if other.is_a?(self.class) && keys.sort! == other.keys.sort!
+        return diff_array other if other.is_a?(self.class) && keys.sort! == other.keys.sort!
 
         each.with_object({}) { |(key, value), diff| diff[key] = [value, nil] }
       end
 
+      def expand_keys delimiter: "."
+        each.with_object({}) do |(key, value), all|
+          parts = String(key).split(delimiter).reverse
+          all.deep_merge! parts.reduce(value) { |accumulator, part| {part => accumulator} }
+        end
+      end
+
       def fetch_deep(*keys, default: NilClass, &)
         keys.reduce fallback(keys.shift, default, &) do |value, key|
           unless value.is_a?(::Hash) || (value.is_a?(::Array) && key.is_a?(::Integer))
@@ -104,6 +112,10 @@ module Refinements
       end
 
       def use &block
+        warn "`#{self.class}##{__method__}` is deprecated and will be removed " \
+             "in the next major version.",
+             category: :deprecated
+
         return [] unless block
 
         block.parameters
@@ -113,9 +125,28 @@ module Refinements
 
       private
 
-      def differences_from other
-        result = merge(other.to_h) { |_, one, two| [one, two].uniq }
-        result.select { |_, diff| diff.size == 2 }
+      def deep_concat(original, second, &)
+        first = original.dup
+        klass = self.class
+
+        second.each.with_index do |second_item, index|
+          first_item = first[index]
+
+          if first_item.is_a?(klass) && second_item.is_a?(klass)
+            first[index] = first_item.deep_merge!(second_item, &)
+          elsif second_item.is_a? ::Array
+            first[index] = deep_concat(first_item, second_item, &)
+          else
+            first.append(second_item).uniq!
+          end
+        end
+
+        first
+      end
+
+      def diff_array other
+        merged = merge(other.to_h) { |_, one, two| [one, two].uniq }
+        merged.select { |_, diff| diff.size == 2 }
       end
 
       def fallback(key, default, &)

data/refinements.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "refinements"
-  spec.version = "14.5.0"
+  spec.version = "14.6.0"
   spec.authors = ["Brooke Kuhlmann"]
   spec.email = ["brooke@alchemists.io"]
   spec.homepage = "https://alchemists.io/projects/refinements"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: refinements
 version: !ruby/object:Gem::Version
-  version: 14.5.0
+  version: 14.6.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -89,7 +89,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.21
+rubygems_version: 4.0.22
 specification_version: 4
 summary: A collection of core object refinements.
 test_files: []