refinements 13.4.0 → 13.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17368920f8d6281ee6bc0f02adcbc94715f3fb5dd05996f782bd34f2b4161f30
-  data.tar.gz: 5ec445e38faecd830284b984b78536b2e4dd17a161e987a53cc629a71bafe84a
+  metadata.gz: c4f7a616f560224da3b786d73ad6f8f206c0aacba2b0701bbe91c5b8ecfec2c2
+  data.tar.gz: 9f166af1d48f1e00f0b8e3024f19fcfbd1cbbb8b8180bd798a69086455bc2079
 SHA512:
-  metadata.gz: 942ba159dd0648e91ff4f81ca4f3e4dd785bbff7496062a82d223e4bf8f60eed4e118cb0754daec81b7bc90b7325cb83f4cc8db4de2e36352e4d48949e01ad3c
-  data.tar.gz: 3f37095c6d6e497c9c52a7abb7692ad091bd70e63639a9329d0bf4b74cb653a37359812777579abdc85c7f0cee9b5d21b2a9457dc58b7dc2d67a38cb05d74f17
+  metadata.gz: 9044d5b55f7349284ae45ff1a98d3c34bb2d4e1511df391094bbef41b8cb8da1f4aae96703bf617c19483269881f1d9f04ba9ba42009868ef7abc5d7953332ac
+  data.tar.gz: fd593a7bb6cb5239618b5eedd077f50df25bcad1be4ec7ed2bc6ec7d8a87c3d2f6ada9c145a55fa802c3afa8ac2b74a773ffadb5fe3b26ae211e682b263c19db

data/README.adoc

@@ -611,6 +611,25 @@ 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.
 
+===== #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:
+
+[source,ruby]
+----
+demo = {a: {b: {c: [1, 2, 3]}}}
+
+demo.fetch_deep :a                            # {b: {c: [1, 2, 3]}}
+demo.fetch_deep :a, :b                        # {c: [1, 2, 3]}
+demo.fetch_deep :a, :b, :c                    # [1, 2, 3]
+demo.fetch_deep :a, :b, :c, 1                 # 2
+demo.fetch_deep(:a, :x, default: "fallback")  # "fallback"
+demo.fetch_deep(:a, :x) { "fallback" }        # "fallback"
+demo.fetch_deep                               # key not found: nil (KeyError)
+demo.fetch_deep :a, :bogus                    # key not found: :bogus (KeyError)
+demo.fetch_deep :a, :b, :c, :bogus            # Unable to find :bogus in [1, 2, 3]. (KeyError)
+----
+
 ===== #fetch_value
 
 Fetches value for exiting or missing key. Behavior is identical to `#fetch` except when the value of
@@ -1049,26 +1068,34 @@ Pathname.pwd                            # "$HOME/demo" (Present Working Director
 
 ⚠️ 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.
 
-===== #copy
+===== #clear
 
-Copies file from current location to new location while answering itself so it can be chained.
+Removes all child directories and files from path while answering itself.
 
 [source,ruby]
 ----
-Pathname("input.txt").copy Pathname("output.txt")  # Pathname("input.txt")
+root = Pathname("demo")
+root.join("a/path/to/a.txt").touch_deep
+root.join("b.txt").touch
+root.clear
+
+root.children  # []
+root.clear     # Pathname "demo"
 ----
 
-===== #deep_touch
+===== #copy
 
-Has all of the same functionality as the `#touch` method while being able to create ancestor
-directories no matter how deeply nested the file might be.
+Copies file from current location to new location while answering itself so it can be chained.
 
 [source,ruby]
 ----
-Pathname("a/b/c/d.txt").touch               # Pathname("a/b/c/d.txt")
-Pathname("a/b/c/d.txt").touch Time.now - 1  # Pathname("a/b/c/d.txt")
+Pathname("input.txt").copy Pathname("output.txt")  # Pathname("input.txt")
 ----
 
+===== #deep_touch
+
+⚠️ This method is deprecated and will be removed in Version 14.0.0. Please use `#touch_deep` instead.
+
 ===== #delete
 
 Deletes file or directory and answers itself so it can be chained.
@@ -1251,6 +1278,17 @@ Pathname("example.txt").touch               # Pathname("example.txt")
 Pathname("example.txt").touch Time.now - 1  # Pathname("example.txt")
 ----
 
+===== #touch_deep
+
+Has all of the same functionality as the `#touch` method while being able to create ancestor
+directories no matter how deeply nested the path might be.
+
+[source,ruby]
+----
+Pathname("a/b/c/d.txt").touch_deep               # Pathname("a/b/c/d.txt")
+Pathname("a/b/c/d.txt").touch_deep Time.now - 1  # Pathname("a/b/c/d.txt")
+----
+
 ===== #write
 
 Writes to file and answers itself so it can be chained. See `IO.write` for details on additional
@@ -1410,6 +1448,30 @@ Answers a title string with proper capitalization of each word.
 "ThisIsAnExample".titleize  # "This Is An Example"
 ----
 
+===== #trim_end
+
+Answers the trimmed end of a string (non-mutated) for given length with optional delimiter and/or overflow.
+
+The delimiter is the second positional parameter (optional) and is `nil` by default. A custom string or regular expression can be used to customize behavior.
+
+The trailer is an optional keyword parameter that is an ellipsis (i.e. `"..."`) by default. The trailer can be a custom or empty string. The string length of the trailer is added to the length of the string being trimmed, so keep this in mind when setting length.
+
+[source,ruby]
+----
+demo = "It was the best of times"
+length = demo.length
+
+demo.trim_end 9                          # "It was..."
+demo.trim_end 12                         # "It was th..."
+demo.trim_end length                     # "It was the best of times"
+demo.trim_end Float::INFINITY            # "It was the best of times"
+demo.trim_end 12, " "                    # "It was..."
+demo.trim_end 12, /\s/                   # "It was..."
+demo.trim_end 6, trailer: ""             # "It was"
+demo.trim_end 16, trailer: "... (more)"  # "It was... (more)"
+"demo".trim_end 3                        # "..."
+----
+
 ===== #truthy?
 
 Answers if string is truthy.
@@ -1425,27 +1487,7 @@ Answers if string is truthy.
 
 ===== #truncate
 
-Answers a truncated, non-mutated, string for given length with optional delimiter and/or overflow.
-
-The delimiter is the second positional parameter (optional) and is `nil` by default. A custom string or regular expression can be used to customize truncation behavior.
-
-The trailer is an optional keyword parameter that is an ellipsis (i.e. `"..."`) by default. The trailer can be a custom or empty string. The string length of the trailer is added to the length of the string being truncated, so keep this in mind when setting truncation length.
-
-[source,ruby]
-----
-demo = "It was the best of times"
-length = demo.length
-
-demo.truncate 9                          # "It was..."
-demo.truncate 12                         # "It was th..."
-demo.truncate length                     # "It was the best of times"
-demo.truncate Float::INFINITY            # "It was the best of times"
-demo.truncate 12, " "                    # "It was..."
-demo.truncate 12, /\s/                   # "It was..."
-demo.truncate 6, trailer: ""             # "It was"
-demo.truncate 16, trailer: "... (more)"  # "It was... (more)"
-"demo".truncate 3                        # "..."
-----
+⚠️ This method is deprecated and will be removed in Version 14.0.0. Please use `#trim_end` instead.
 
 ===== #to_bool
 
@@ -1540,37 +1582,11 @@ Any object that _is not_ the same type will have a `nil` value as shown in the l
 
 ===== #merge
 
-Merges multiple attributes without mutating itself and supports any object that responds to `#to_h`.
-Works regardless of whether the struct is constructed with positional or keyword arguments.
-
-[source,ruby]
-----
-example = Struct.new("Example", :a, :b, :c).new 1, 2, 3
-other = Struct.new("Other", :a, :b, :c).new 7, 8, 9
-
-example.merge a: 10                # #<struct Struct::Example a=10, b=2, c=3>
-example.merge a: 10, c: 30         # #<struct Struct::Example a=10, b=2, c=30>
-example.merge a: 10, b: 20, c: 30  # #<struct Struct::Example a=10, b=20, c=30>
-example.merge other                # #<struct Struct::Example a=7, b=8, c=9>
-example                            # #<struct Struct::Example a=1, b=2, c=3>
-----
+⚠️ This method is deprecated and will be removed in Version 14.0.0. Please use xref:_with[#with] instead.
 
 ===== #merge!
 
-Merges multiple attributes while mutating itself and supports any object that responds to `#to_h`.
-Works regardless of whether the struct is constructed with positional or keyword arguments.
-
-[source,ruby]
-----
-example = Struct.new("Example", :a, :b, :c).new 1, 2, 3
-other = Struct.new("Other", :a, :b, :c).new 7, 8, 9
-
-example.merge! a: 10                # #<struct Struct::Example a=10, b=2, c=3>
-example.merge! a: 10, c: 30         # #<struct Struct::Example a=10, b=2, c=30>
-example.merge! other                # #<struct Struct::Example a=7, b=8, c=9>
-example.merge! a: 10, b: 20, c: 30  # #<struct Struct::Example a=10, b=20, c=30>
-example                             # #<struct Struct::Example a=10, b=20, c=30>
-----
+⚠️ This method is deprecated and will be removed in Version 14.0.0. Please use xref:_with_2[#with!] instead.
 
 ===== #transmute
 
@@ -1610,7 +1626,35 @@ a                                    # #<struct Struct::A a=7, b=8, c=30>
 
 ===== #with
 
-An alias of `#merge` and identical in behavior (see `#merge` documentation for details). Allows you to use `Struct` and `Data` objects more interchangeably since they share the same method.
+Allows you to use `Struct` and `Data` objects more interchangeably by merging multiple attributes without mutating itself. Supports any object that responds to `#to_h`. Works regardless of whether the struct is constructed with positional or keyword arguments.
+
+[source,ruby]
+----
+example = Struct.new("Example", :a, :b, :c).new 1, 2, 3
+other = Struct.new("Other", :a, :b, :c).new 7, 8, 9
+
+example.with a: 10                # #<struct Struct::Example a=10, b=2, c=3>
+example.with a: 10, c: 30         # #<struct Struct::Example a=10, b=2, c=30>
+example.with a: 10, b: 20, c: 30  # #<struct Struct::Example a=10, b=20, c=30>
+example.with other                # #<struct Struct::Example a=7, b=8, c=9>
+example                           # #<struct Struct::Example a=1, b=2, c=3>
+----
+
+===== #with!
+
+Allows you to merge multiple attributes while mutating itself. Supports any object that responds to `#to_h`. Works regardless of whether the struct is constructed with positional or keyword arguments.
+
+[source,ruby]
+----
+example = Struct.new("Example", :a, :b, :c).new 1, 2, 3
+other = Struct.new("Other", :a, :b, :c).new 7, 8, 9
+
+example.with! a: 10                # #<struct Struct::Example a=10, b=2, c=3>
+example.with! a: 10, c: 30         # #<struct Struct::Example a=10, b=2, c=30>
+example.with! other                # #<struct Struct::Example a=7, b=8, c=9>
+example.with! a: 10, b: 20, c: 30  # #<struct Struct::Example a=10, b=20, c=30>
+example                            # #<struct Struct::Example a=10, b=20, c=30>
+----
 
 ==== Symbol
 

data/lib/refinements/hash.rb

@@ -49,6 +49,16 @@ module Refinements
         each.with_object({}) { |(key, value), diff| diff[key] = [value, nil] }
       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))
+            fail KeyError, "Unable to find #{key.inspect} in #{value.inspect}."
+          end
+
+          default == NilClass ? value.fetch(key, &) : value.fetch(key, default)
+        end
+      end
+
       def fetch_value(key, *default, &)
         fetch(key, *default, &) || (yield if block_given?) || default.first
       end
@@ -107,6 +117,10 @@ module Refinements
         result = merge(other.to_h) { |_, one, two| [one, two].uniq }
         result.select { |_, diff| diff.size == 2 }
       end
+
+      def fallback(key, default, &)
+        default == NilClass ? fetch(key, &) : fetch(key, default)
+      end
     end
   end
 end

data/lib/refinements/pathname.rb

@@ -30,13 +30,20 @@ module Refinements
         end
       end
 
+      def clear = children.each(&:rmtree) && self
+
       def copy to
         destination = to.directory? ? to.join(basename) : to
         ::IO.copy_stream self, destination
         self
       end
 
-      def deep_touch(...) = make_ancestors.touch(...)
+      def deep_touch(...)
+        warn "`#{self.class}##{__method__}` is deprecated, use `#touch_deep` instead.",
+             category: :deprecated
+
+        touch_deep(...)
+      end
 
       def delete = super && self
 
@@ -78,6 +85,8 @@ module Refinements
         self
       end
 
+      def touch_deep(...) = make_ancestors.touch(...)
+
       def write content, offset: nil, **options
         super content, offset, **options
         self

data/lib/refinements/string.rb

@@ -62,9 +62,7 @@ module Refinements
                                               .then { |parts| combine parts, :up, "/" }
       end
 
-      def truthy? = %w[true yes on t y 1].include? downcase.strip
-
-      def truncate to, delimiter = nil, trailer: "..."
+      def trim_end to, delimiter = nil, trailer: "..."
         return dup if length <= to
 
         offset = to - trailer.length
@@ -72,6 +70,15 @@ module Refinements
         "#{self[...maximum]}#{trailer}"
       end
 
+      def truthy? = %w[true yes on t y 1].include? downcase.strip
+
+      def truncate(...)
+        warn "`#{self.class}##{__method__}` is deprecated, use `#trim_end` instead.",
+             category: :deprecated
+
+        trim_end(...)
+      end
+
       # rubocop:disable Naming/PredicateMethod
       def to_bool
         warn "`#{self.class}##{__method__}` is deprecated, use `#truthy?` or `#falsey?` instead.",

data/lib/refinements/struct.rb

@@ -8,11 +8,18 @@ module Refinements
     refine ::Struct do
       import_methods Shared::Diff
 
-      def merge(...) = dup.merge!(...)
+      def merge(...)
+        warn "`#{self.class}##{__method__}` is deprecated, use `#with` instead.",
+             category: :deprecated
 
-      def merge! object = nil
-        to_h.merge!(**object.to_h).each { |key, value| self[key] = value }
-        self
+        with(...)
+      end
+
+      def merge!(...)
+        warn "`#{self.class}##{__method__}` is deprecated, use `#with!` instead.",
+             category: :deprecated
+
+        with!(...)
       end
 
       def transmute(...) = dup.transmute!(...)
@@ -22,7 +29,12 @@ module Refinements
         merge! object.to_h.slice(*mapping.keys).transform_keys!(mapping)
       end
 
-      alias_method :with, :merge
+      def with(...) = dup.with!(...)
+
+      def with! object = nil
+        to_h.merge!(**object.to_h).each { |key, value| self[key] = value }
+        self
+      end
     end
   end
 end

data/refinements.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "refinements"
-  spec.version = "13.4.0"
+  spec.version = "13.5.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: 13.4.0
+  version: 13.5.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -88,7 +88,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.0
+rubygems_version: 3.7.1
 specification_version: 4
 summary: A collection of core object refinements.
 test_files: []