refinements 14.5.0 → 14.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 730d2c8e3fd694a24d88c05755eec1599b26002fd7317131c795e5752ed16fb5
-  data.tar.gz: 5611e41668a0570ae5944569bee6b54e7b47176a37831ba8817c20c63edb2840
+  metadata.gz: d986dc181b2c378adc82cc89841387a47286f58f5a3c87bb94d81d951934ab86
+  data.tar.gz: 5e4608408e3f89bf4ed72097deec34b0744b5ac939d837eecbd5b887616b9c83
 SHA512:
-  metadata.gz: 4314a271e2c4ab6f0c5d4d0f2e4c56d13b68b4e7d5f11b46ffb3e477f1a7770d44c0a670e7fee640cec6f2df74daee191eaf5b764a379b7c17a9e0011328fd20
-  data.tar.gz: 1eca09b429c622b3365b6cf5d2905313cebffa45264ac25684bba65332f70e58934c301655ee6651f96a3c5c59df526aeeb50e4aa5e02e126f0db1f7c8795d15
+  metadata.gz: 9a0628a9e07d1550af4e03bb39d80fe0494b429a58fb097095b46e25e93560bc4ff71ee79a4519709e3db6d036e8001f9c78c2551a6d3be38fa9d6ceee31396d
+  data.tar.gz: 3cd5c78b4a678c7b826366a8c61fcdab222a45c9b8dd103dd6e6f9529bc923c292181bf8ce698a86a6ac23f5bd17ddc9e707da9537dcc817f661e76c85ef253a

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 b: {one: 1}  # {a: "A", b: {one: 1, two: "Two"}}
-example                         # {a: "A", b: {one: "One", two: "Two"}}
+example.deep_merge demo: {one: 1}  # {demo: {one: 1}}
+example                            # {demo: {one: "One"}}
+----
+
+Nested arrays are concatenated:
+
+[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]
@@ -1062,13 +1136,13 @@ link:https://rubyapi.org/o/Dir.chdir#method-c-chdir[Dir.chdir] for details.
 
 [source,ruby]
 ----
-current = Pathname.pwd                  # "$HOME/demo" (Present Working Directory)
-custom = current.join("test").make_dir  # Pathname "$HOME/demo/test"
-custom.change_dir                       # "$HOME/demo/test" (Present Working Directory)
-current.change_dir                      # "$HOME/demo" (Present Working Directory)
-custom.change_dir { "example" }         # "example"
-custom.change_dir { |path| path }       # Pathname "$HOME/demo/test"
-Pathname.pwd                            # "$HOME/demo" (Present Working Directory)
+current = Pathname.pwd                # "$HOME/demo" (Present Working Directory)
+custom = current.join("test").mkpath  # Pathname "$HOME/demo/test"
+custom.change_dir                     # "$HOME/demo/test" (Present Working Directory)
+current.change_dir                    # "$HOME/demo" (Present Working Directory)
+custom.change_dir { "example" }       # "example"
+custom.change_dir { |path| path }     # Pathname "$HOME/demo/test"
+Pathname.pwd                          # "$HOME/demo" (Present Working Directory)
 ----
 
 ⚠️ This method is _not thread safe_ and suffers the same issues as found with native `Dir.chdir` functionality because the underlying native call is global. Use with care.
@@ -1203,6 +1277,8 @@ Pathname("/one/two").exist?          # false
 
 ===== #make_dir
 
+⚠️ This method is deprecated and will be removed in the next major release.
+
 Provides alternative `#mkdir` behavior by always answering itself (even when directory exists) and
 not throwing errors when directory does exist in order to ensure the pathname can be chained.
 
@@ -1250,9 +1326,9 @@ not throwing errors when directory does exist in order to ensure the pathname ca
 
 [source,ruby]
 ----
-Pathname("/test").make_dir.remove_dir.exist?  # false
-Pathname("/test").remove_dir                  # Pathname("/test")
-Pathname("/test").remove_dir.remove_dir       # Pathname("/test")
+Pathname("/test").mkpath.remove_dir.exist?  # false
+Pathname("/test").remove_dir                # Pathname("/test")
+Pathname("/test").remove_dir.remove_dir     # Pathname("/test")
 ----
 
 ===== #rewrite

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/lib/refinements/pathname.rb

@@ -46,7 +46,7 @@ module Refinements
         glob(pattern, flag).select(&:directory?)
       end
 
-      def empty = file? ? (truncate(0) and self) : rmtree.make_dir
+      def empty = file? ? (truncate(0) and self) : rmtree.mkpath
 
       def extensions = basename.to_s.split(/(?=\.)+/).tap(&:shift)
 
@@ -59,7 +59,12 @@ module Refinements
         self
       end
 
-      def make_dir = exist? ? self : (mkdir and self)
+      def make_dir
+        warn "`#{self.class}##{__method__}` is deprecated, use `mkpath` instead.",
+             category: :deprecated
+
+        mkpath
+      end
 
       def name = basename extname
 

data/refinements.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "refinements"
-  spec.version = "14.5.0"
+  spec.version = "14.6.1"
   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.1
 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.23
 specification_version: 4
 summary: A collection of core object refinements.
 test_files: []