refinements 7.12.0 → 7.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3df95fcb46ec44d2945b1eb3ab7dafd8ba6bb243973829d662e448ef74695302
-  data.tar.gz: 21d89890312770ec2c73387c05c44dc31b22de849e18c3db6b4248476ca8bbdf
+  metadata.gz: 27c7f3818bd1f3d0d3fc39cb4c8721097d5003176b54710888deba6d012b4f77
+  data.tar.gz: f607fea47fce94c11c3ab7dcc6603b169567133fbbe6ca76fb0af0c9fa0196e4
 SHA512:
-  metadata.gz: d0cb8fa10183e03737eab0ae1780b91e2e4ce994fd0945c7e2653bacd852dae85de474a073f4b1f6b8634e685059a54a0651b46ec567defd283cfb1491988e50
-  data.tar.gz: a3f2ea6940f0e8c74f41f43d28d34a71892d3ddcaaf295c64ce4761b120421f80c7833bd9b48d37a90e485c3b606c38adb71e8665cf9feecad35925da485628a
+  metadata.gz: da5ff60dc1e6d4055adc850bbe7aa48d02c148f17fb42c9e50f939d577d506097603c2790cf5ce040cce1cb8389e28ebd363d3318d1224d06df4fc6d36e56b3f
+  data.tar.gz: a5a96d51b0e95d1f603262ca8ce767969e3faca18645327f368d8ee03aed7d0fa27211d9e35a8af30bcc6ca86d6dad33d804a4c9f1b830789b39b06dc0791793

data/README.adoc

@@ -6,6 +6,8 @@
 
 [link=http://badge.fury.io/rb/refinements]
 image::https://badge.fury.io/rb/refinements.svg[Gem Version]
+[link=https://www.alchemists.io/projects/code_quality]
+image::https://img.shields.io/badge/code_style-alchemists-brightgreen.svg[Alchemists Style Guide]
 [link=https://circleci.com/gh/bkuhlmann/refinements]
 image::https://circleci.com/gh/bkuhlmann/refinements.svg?style=svg[Circle CI Status]
 
@@ -26,6 +28,7 @@ Enhances the following objects:
 * Pathname
 * String
 * StringIO
+* Structs
 
 == Requirements
 
@@ -73,6 +76,7 @@ require "refinements/ios"
 require "refinements/pathnames"
 require "refinements/strings"
 require "refinements/string_ios"
+require "refinements/structs"
 ----
 
 === Using
@@ -92,6 +96,7 @@ class Example
   using Refinements::Pathnames
   using Refinements::Strings
   using Refinements::StringIOs
+  using Refinements::Structs
 end
 ----
 
@@ -123,35 +128,35 @@ example.compress!  # => ["An", "Example"]
 example            # => ["An", "Example"]
 ----
 
-===== #include
+===== #excluding
 
-Adds given array or elements without mutating itself.
+Removes given array or elements without mutating itself.
 
 [source,ruby]
 ----
-[1, 2, 3].include [4, 5]  # => [1, 2, 3, 4, 5]
-[1, 2, 3].include 4, 5    # => [1, 2, 3, 4, 5]
+[1, 2, 3, 4, 5].excluding [4, 5]  # => [1, 2, 3]
+[1, 2, 3, 4, 5].excluding 4, 5    # => [1, 2, 3]
 ----
 
-===== #intersperse
+===== #including
 
-Inserts additional elements or array between all members of given array.
+Adds given array or elements without mutating itself.
 
 [source,ruby]
 ----
-[1, 2, 3].intersperse :a         # => [1, :a, 2, :a, 3]
-[1, 2, 3].intersperse :a, :b     # => [1, :a, :b, 2, :a, :b, 3]
-[1, 2, 3].intersperse %i[a b c]  # => [1, :a, :b, :c, 2, :a, :b, :c, 3]
+[1, 2, 3].including [4, 5]  # => [1, 2, 3, 4, 5]
+[1, 2, 3].including 4, 5    # => [1, 2, 3, 4, 5]
 ----
 
-===== #exclude
+===== #intersperse
 
-Removes given array or elements without mutating itself.
+Inserts additional elements or array between all members of given array.
 
 [source,ruby]
 ----
-[1, 2, 3, 4, 5].exclude [4, 5]  # => [1, 2, 3]
-[1, 2, 3, 4, 5].exclude 4, 5    # => [1, 2, 3]
+[1, 2, 3].intersperse :a         # => [1, :a, 2, :a, 3]
+[1, 2, 3].intersperse :a, :b     # => [1, :a, :b, 2, :a, :b, 3]
+[1, 2, 3].intersperse %i[a b c]  # => [1, :a, :b, :c, 2, :a, :b, :c, 3]
 ----
 
 ===== #mean
@@ -235,106 +240,10 @@ Answers new hash where every top-level missing key has the same default value.
 [source,ruby]
 ----
 example = Hash.with_default ""
-example[:a] # => ""
+example[:a]  # => ""
 
 example = Hash.with_default []
-example[:b] # => []
-----
-
-===== #except
-
-Answers new hash with given keys removed without mutating itself.
-
-[source,ruby]
-----
-example = {a: 1, b: 2, c: 3}
-example.except :a, :b  # => {c: 3}
-example                # => {a: 1, b: 2, c: 3}
-----
-
-===== #except!
-
-Answers new hash with given keys removed while mutating itself.
-
-[source,ruby]
-----
-example = {a: 1, b: 2, c: 3}
-example.except! :a, :b  # => {c: 3}
-example                 # => {c: 3}
-----
-
-===== #flatten_keys
-
-Flattens nested keys as top-level keys without mutating itself. Does not handle nested arrays,
-though.
-
-[source,ruby]
-----
-{a: {b: 1}}.flatten_keys prefix: :test  # => {test_a_b: 1}
-{a: {b: 1}}.flatten_keys delimiter: :|  # => {:"a|b" => 1}
-
-{a: {b: 1}}.flatten_keys cast: :to_s            # => {"a_b" => 1}
-{"a" => {"b" => 1}}.flatten_keys cast: :to_sym  # => {a_b: 1}
-
-example = {a: {b: 1}}
-example.flatten_keys  # => {a_b: 1}
-example               # => {a: {b: 1}}
-----
-
-===== #flatten_keys!
-
-Flattens nested keys as top-level keys while mutating itself. Does not handle nested arrays,
-though.
-
-[source,ruby]
-----
-example = {a: {b: 1}}
-example.flatten_keys!  # => {a_b: 1}
-example                # => {a_b: 1}
-----
-
-===== #stringify_keys
-
-Converts keys to strings without mutating itself.
-
-[source,ruby]
-----
-example = {a: 1, b: 2}
-example.stringify_keys  # => {"a" => 1, "b" => 2}
-example                 # => {a: 1, b: 2}
-----
-
-===== #stringify_keys!
-
-Converts keys to strings while mutating itself.
-
-[source,ruby]
-----
-example = {a: 1, b: 2}
-example.stringify_keys!  # => {"a" => 1, "b" => 2}
-example                  # => {"a" => 1, "b" => 2}
-----
-
-===== #symbolize_keys
-
-Converts keys to symbols without mutating itself.
-
-[source,ruby]
-----
-example = {"a" => 1, "b" => 2}
-example.symbolize_keys  # => {a: 1, b: 2}
-example                 # => {"a" => 1, "b" => 2}
-----
-
-===== #symbolize_keys!
-
-Converts keys to symbols while mutating itself.
-
-[source,ruby]
-----
-example = {"a" => 1, "b" => 2}
-example.symbolize_keys!  # => {a: 1, b: 2}
-example                  # => {a: 1, b: 2}
+example[:b]  # => []
 ----
 
 ===== #deep_merge
@@ -403,6 +312,58 @@ example.deep_symbolize_keys!  # => {a: {b: 1}}
 example                       # => {a: {b: 1}}
 ----
 
+===== #except
+
+Answers new hash with given keys removed without mutating itself.
+
+[source,ruby]
+----
+example = {a: 1, b: 2, c: 3}
+example.except :a, :b  # => {c: 3}
+example                # => {a: 1, b: 2, c: 3}
+----
+
+===== #except!
+
+Answers new hash with given keys removed while mutating itself.
+
+[source,ruby]
+----
+example = {a: 1, b: 2, c: 3}
+example.except! :a, :b  # => {c: 3}
+example                 # => {c: 3}
+----
+
+===== #flatten_keys
+
+Flattens nested keys as top-level keys without mutating itself. Does not handle nested arrays,
+though.
+
+[source,ruby]
+----
+{a: {b: 1}}.flatten_keys prefix: :test  # => {test_a_b: 1}
+{a: {b: 1}}.flatten_keys delimiter: :|  # => {:"a|b" => 1}
+
+{a: {b: 1}}.flatten_keys cast: :to_s            # => {"a_b" => 1}
+{"a" => {"b" => 1}}.flatten_keys cast: :to_sym  # => {a_b: 1}
+
+example = {a: {b: 1}}
+example.flatten_keys  # => {a_b: 1}
+example               # => {a: {b: 1}}
+----
+
+===== #flatten_keys!
+
+Flattens nested keys as top-level keys while mutating itself. Does not handle nested arrays,
+though.
+
+[source,ruby]
+----
+example = {a: {b: 1}}
+example.flatten_keys!  # => {a_b: 1}
+example                # => {a_b: 1}
+----
+
 ===== #recurse
 
 Recursively iterates over the hash and any hash value by applying the given block to it. Does not
@@ -459,6 +420,50 @@ example.reverse_merge! a: 0, c: 3  # => {a: 1, b: 2, c: 3}
 example                            # => {a: 1, b: 2, c: 3}
 ----
 
+===== #stringify_keys
+
+Converts keys to strings without mutating itself.
+
+[source,ruby]
+----
+example = {a: 1, b: 2}
+example.stringify_keys  # => {"a" => 1, "b" => 2}
+example                 # => {a: 1, b: 2}
+----
+
+===== #stringify_keys!
+
+Converts keys to strings while mutating itself.
+
+[source,ruby]
+----
+example = {a: 1, b: 2}
+example.stringify_keys!  # => {"a" => 1, "b" => 2}
+example                  # => {"a" => 1, "b" => 2}
+----
+
+===== #symbolize_keys
+
+Converts keys to symbols without mutating itself.
+
+[source,ruby]
+----
+example = {"a" => 1, "b" => 2}
+example.symbolize_keys  # => {a: 1, b: 2}
+example                 # => {"a" => 1, "b" => 2}
+----
+
+===== #symbolize_keys!
+
+Converts keys to symbols while mutating itself.
+
+[source,ruby]
+----
+example = {"a" => 1, "b" => 2}
+example.symbolize_keys!  # => {a: 1, b: 2}
+example                  # => {a: 1, b: 2}
+----
+
 ===== #use
 
 Passes each hash value as a block argument for further processing.
@@ -466,7 +471,7 @@ Passes each hash value as a block argument for further processing.
 [source,ruby]
 ----
 example = {unit: "221B", street: "Baker Street", city: "London", country: "UK"}
-example.use { |unit, street| "#{unit} #{street}" } # => "221B Baker Street"
+example.use { |unit, street| "#{unit} #{street}" }  # => "221B Baker Street"
 ----
 
 ==== IO
@@ -479,23 +484,8 @@ block, you'll need to close the stream manually.
 
 [source,ruby]
 ----
-io = IO.void
-io.closed? # => false
-
-io = IO.void { |void| void.write "nevermore" }
-io.closed? # => true
-----
-
-===== #squelch
-
-Temporarily ignores any reads/writes for current stream for all code executed within the block. When
-not given a block, it answers itself.
-
-[source,ruby]
-----
-io = IO.new IO.sysopen(Pathname("test.txt").to_s, "w+")
-io.squelch { io.write "Test" }
-io.reread # => ""
+io = IO.void                                    # => #<IO:fd 20>
+io = IO.void { |void| void.write "nevermore" }  # => #<IO:(closed)>
 ----
 
 ===== #redirect
@@ -508,11 +498,8 @@ answered instead.
 io = IO.new IO.sysopen(Pathname("test.txt").to_s, "w+")
 other = IO.new IO.sysopen(Pathname("other.txt").to_s, "w+")
 
-io.redirect other # => `io`
-
-io.redirect(other) { |stream| stream.write "test" }
-  .close    # => ""
-other.close # => "test"
+io.redirect other                                    # => #<IO:fd 20>
+io.redirect(other) { |stream| stream.write "test" }  # => #<IO:fd 21>
 ----
 
 ===== #reread
@@ -528,45 +515,134 @@ io.reread    # => "This is a test."
 io.reread 4  # => "This"
 
 buffer = "".dup
-io.reread(buffer: buffer)
-buffer # => "This is a test."
+io.reread(buffer: buffer)  # => "This is a test."
+buffer                     # => "This is a test."
+----
+
+===== #squelch
+
+Temporarily ignores any reads/writes for code executed within a block. Answers itself without any
+arguments or when given a block.
+
+[source,ruby]
+----
+io = IO.new IO.sysopen(Pathname("test.txt").to_s, "w+")
+io.squelch                      # => #<IO:fd 20>
+io.squelch { io.write "Test" }  # => #<IO:fd 20>
+io.reread                       # => ""
 ----
 
 ==== Pathname
 
 ===== Pathname
 
-Enhances the conversion function -- refined from `Kernel` -- which casts `nil` into a pathname in
-order to avoid: `TypeError (no implicit conversion of nil into String)`. The pathname is still
-invalid but at least you have an instance of `Pathname`, which behaves like a _Null Object_, that
-can still be used to construct a valid path.
+Enhances the `Kernel` conversion function which casts `nil` into a pathname in order to avoid:
+`TypeError (no implicit conversion of nil into String)`. The pathname remains invalid but at least
+you have an instance of `Pathname`, which behaves like a _Null Object_, that can be used to
+construct a valid path.
 
 [source,ruby]
 ----
 Pathname(nil) # => Pathname("")
 ----
 
-===== #name
+===== .home
 
-Answers file name without extension.
+Answers user home directory.
 
 [source,ruby]
 ----
-Pathname("example.txt").name # => Pathname("example")
+Pathname.home  # => Pathname "/Users/bkuhlmann"
+----
+
+===== .make_temp_dir
+
+Wraps `Dir.mktmpdir` with the following behavior (see
+link:https://rubyapi.org/o/Dir.mktmpdir#method-c-mktmpdir[Dir.mktmpdir] for details):
+
+* *Without Block* - Answers a newly created Pathname instance which is not automatically cleaned up.
+* *With Block*  Yields a Pathname instance, answers result of given block, and automatidally cleans
+  up temporary directory after block exits.
+
+The following examples use truncated temporary directories for illustration purposes only. In
+reality, these paths will be longer depending on which operating system you are using.
+
+[source,ruby]
+----
+Pathname.make_temp_dir                                       # => Pathname:/var/folders/T/temp-20200101-16940-r8
+Pathname.make_temp_dir prefix: "prefix-"                     # => Pathname:/var/folders/T/prefix-20200101-16940-r8
+Pathname.make_temp_dir suffix: "-suffix"                     # => Pathname:/var/folders/T/temp-20200101-16940-r8-suffix
+Pathname.make_temp_dir prefix: "prefix-", suffix: "-suffix"  # => Pathname:/var/folders/T/prefix-20200101-16940-r8-suffix
+Pathname.make_temp_dir root: "/example"                      # => Pathname:/example/temp-20200101-16940-r8
+Pathname.make_temp_dir { "I am a block result" }             # => "I am a block result"
+Pathname.make_temp_dir { |path| path.join "sub_dir" }        # => Pathname:/var/folders/T/temp-20200101-16940-r8/sub_dir
+----
+
+===== .require_tree
+
+Requires all files in given root path and corresponding nested tree structure. All files are sorted
+before being required to ensure consistent behavior. Example:
+
+[source,rby]
+----
+# Before
+Dir[File.join(__dir__, "support/shared_contexts/**/*.rb")].sort.each { |path| require path }
+
+# After
+Pathname.require_tree __dir__, "support/shared_contexts/**/*.rb"
+----
+
+The following are further examples of potential usage:
+
+[source,ruby]
+----
+# Requires all files in root directory and below.
+Pathname.require_tree __dir__
+
+# Requires all files in `/test/**/*.rb` and below.
+Pathname.require_tree "/test"
+
+# Requires all files in RSpec shared examples directory structure.
+Pathname.require_tree Bundler.root.join("spec"), "support/shared_examples/**/*.rb"
+----
+
+===== .root
+
+Answers operating system root path.
+
+[source,ruby]
+----
+Pathname.root  # => Pathname "/"
+----
+
+===== #change_dir
+
+Wraps `Dir.chdir` behavior by changing to directory of current path. See
+link:https://rubyapi.org/o/Dir.chdir#method-c-chdir[Dir.chdir] for details.
+
+[source,ruby]
+----
+Pathname.pwd                           # => "/"
+Pathname("/test").make_dir.change_dir  # => Pathname "/test"
+Pathname.pwd                           # => "/test"
+
+Pathname.pwd                                         # => "/"
+Pathname("/test").make_dir.change_dir { "example" }  # => "example"
+Pathname.pwd                                         # => "/"
 ----
 
 ===== #copy
 
-Copies file from current location to new location.
+Copies file from current location to new location while answering itself so it can be chained.
 
 [source,ruby]
 ----
-Pathname("input.txt").copy Pathname("output.txt")
+Pathname("input.txt").copy Pathname("output.txt")  # => Pathname("input.txt")
 ----
 
 ===== #directories
 
-Answers all or filtered directories for current path.
+Answers all directories or filtered directories for current path.
 
 [source,ruby]
 ----
@@ -581,12 +657,12 @@ Answers file extensions as an array.
 
 [source,ruby]
 ----
-Pathname("example.txt.erb").extensions # => [".txt", ".erb"]
+Pathname("example.txt.erb").extensions  # => [".txt", ".erb"]
 ----
 
 ===== #files
 
-Answers all or filtered files for current path.
+Answers all files or filtered files for current path.
 
 [source,ruby]
 ----
@@ -608,6 +684,48 @@ Pathname("/%placeholder%/some/%placeholder%").gsub("%placeholder%", "test")
 # => Pathname("/test/some/test")
 ----
 
+===== #make_ancestors
+
+Ensures all ancestor directories are created for a path.
+
+[source,ruby]
+----
+Pathname("/one/two").make_ancestors  # => Pathname("/one/two")
+Pathname("/one").exist?              # => true
+Pathname("/one/two").exist?          # => false
+----
+
+===== #make_dir
+
+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.
+
+[source,ruby]
+----
+Pathname("/one").make_dir           # => Pathname("/one")
+Pathname("/one").make_dir.make_dir  # => Pathname("/one")
+----
+
+===== #make_path
+
+Provides alternative `#mkpath` behavior by always answering itself (even when full path exists) and
+not throwing errors when directory does exist in order to ensure the pathname can be chained.
+
+[source,ruby]
+----
+Pathname("/one/two/three").make_path            # => Pathname("/one/two/three")
+Pathname("/one/two/three").make_path.make_path  # => Pathname("/one/two/three")
+----
+
+===== #name
+
+Answers file name without extension.
+
+[source,ruby]
+----
+Pathname("example.txt").name # => Pathname("example")
+----
+
 ===== #relative_parent
 
 Answers relative path from parent directory. This is a complement to `#relative_path_from`.
@@ -617,26 +735,37 @@ Answers relative path from parent directory. This is a complement to `#relative_
 Pathname("/one/two/three").relative_parent("/one") # => Pathname "two"
 ----
 
-===== #make_ancestors
+===== #remove_dir
 
-Ensures all ancestor directories are created for a path.
+Provides alternative `#rmdir` behavior by always answering itself (even when full path exists) and
+not throwing errors when directory does exist in order to ensure the pathname can be chained.
 
 [source,ruby]
 ----
-Pathname("/one/two").make_ancestors
-Pathname("/one").exist?      # => true
-Pathname("/one/two").exist?  # => false
+Pathname("/test").make_dir.remove_dir.exist?  # => false
+Pathname("/test").remove_dir                  # => Pathname("/test")
+Pathname("/test").remove_dir.remove_dir       # => Pathname("/test")
 ----
 
-===== #mkdir
+===== #remove_tree
 
-Modifies default behavior by always answering itself (even when directory exists) and not throwing
-errors when directory exists.
+Provides alternative `#rmtree` behavior by always answering itself (even when full path exists) and
+not throwing errors when directory does exist in order to ensure the pathname can be chained.
 
 [source,ruby]
 ----
-Pathname("/one").mkdir        # => Pathname("/one")
-Pathname("/one").mkdir.mkdir  # => Pathname("/one")
+parent_path = Pathname "/one"
+child_path = parent_path.join "two"
+
+child_path.make_path
+child_path.remove_tree  # => Pathname "/one/two"
+child_path.exist?       # => false
+paremt_path.exist?      # => true
+
+child_path.make_path
+parent_path.remove_tree  # => Pathname "/one"
+child_path.exist?        # => false
+parent_path.exist?       # => false
 ----
 
 ===== #rewrite
@@ -646,7 +775,8 @@ immediate writing back to the same file.
 
 [source,ruby]
 ----
-Pathname("/test.txt").rewrite { |content| content.sub "[placeholder]", "example" }
+Pathname("/test.txt").rewrite                                           # => Pathname("/test.txt")
+Pathname("/test.txt").rewrite { |body| body.sub "[token]", "example" }  # => Pathname("/test.txt")
 ----
 
 ===== #touch
@@ -655,31 +785,23 @@ Updates access and modification times for path. Defaults to current time.
 
 [source,ruby]
 ----
-Pathname("example.txt").touch
-Pathname("example.txt").touch at: Time.now - 1
+Pathname("example.txt").touch                   # => Pathname("example.txt")
+Pathname("example.txt").touch at: Time.now - 1  # => Pathname("example.txt")
 ----
 
-==== String
+===== #write
 
-===== #first
-
-Answers first character of a string or first set of characters if given a number.
+Writes to file and answers itself so it can be chained. See `IO.write` for details on additional
+options.
 
 [source,ruby]
 ----
-"example".first    # => "e"
-"example".first 4  # => "exam"
+Pathname("example.txt").write "test"             # => Pathname("example.txt")
+Pathname("example.txt").write "test", offset: 1  # => Pathname("example.txt")
+Pathname("example.txt").write "test", mode: "a"  # => Pathname("example.txt")
 ----
 
-===== #last
-
-Answers last character of a string or last set of characters if given a number.
-
-[source,ruby]
-----
-"instant".last    # => "t"
-"instant".last 3  # => "ant"
-----
+==== String
 
 ===== #blank?
 
@@ -690,13 +812,13 @@ Answers `true`/`false` based on whether string is blank, `<space>`, `\n`, `\t`,
 " \n\t\r".blank? # => true
 ----
 
-===== #up
+===== #camelcase
 
-Answers string with only first letter upcased.
+Answers a camelcased string.
 
 [source,ruby]
 ----
-"example".up # => "Example"
+"this_is_an_example".camelcase # => "ThisIsAnExample"
 ----
 
 ===== #down
@@ -708,6 +830,16 @@ Answers string with only first letter downcased.
 "EXAMPLE".down # => "eXAMPLE"
 ----
 
+===== #first
+
+Answers first character of a string or first set of characters if given a number.
+
+[source,ruby]
+----
+"example".first    # => "e"
+"example".first 4  # => "exam"
+----
+
 ===== #indent
 
 Answers string indented by two spaces by default.
@@ -721,13 +853,14 @@ Answers string indented by two spaces by default.
 "example".indent 3, padding: " "  # => "   example"
 ----
 
-===== #camelcase
+===== #last
 
-Answers a camelcased string.
+Answers last character of a string or last set of characters if given a number.
 
 [source,ruby]
 ----
-"this_is_an_example".camelcase # => "ThisIsAnExample"
+"instant".last    # => "t"
+"instant".last 3  # => "ant"
 ----
 
 ===== #snakecase
@@ -761,6 +894,15 @@ Answers string as a boolean.
 "example".to_bool  # => false
 ----
 
+===== #up
+
+Answers string with only first letter upcased.
+
+[source,ruby]
+----
+"example".up # => "Example"
+----
+
 ==== String IO
 
 ===== #reread
@@ -776,8 +918,52 @@ io.reread    # => "This is a test."
 io.reread 4  # => "This"
 
 buffer = "".dup
-io.reread(buffer: buffer)
-buffer # => "This is a test."
+io.reread(buffer: buffer)  # => "This is a test."
+buffer                     # => "This is a test."
+----
+
+==== Struct
+
+===== #merge
+
+Merges multiple attributes without mutating itself.
+
+[source,ruby]
+----
+Example = Struct.new :a, :b, :c
+example = Example[1, 2, 3]
+example.merge a: 10                # => #<struct a=10, b=2, c=3>
+example.merge a: 10, c: 30         # => #<struct a=10, b=2, c=30>
+example.merge a: 10, b: 20, c: 30  # => #<struct a=10, b=20, c=30>
+example                            # => #<struct a=1, b=2, c=3>
+
+Example = Struct.new :a, :b, :c, keyword_init: true
+example = Example[a: 1, b: 2, c: 3]
+example.merge a: 10                # => #<struct a=10, b=2, c=3>
+example.merge a: 10, c: 30         # => #<struct a=10, b=2, c=30>
+example.merge a: 10, b: 20, c: 30  # => #<struct a=10, b=20, c=30>
+example                            # => #<struct a=1, b=2, c=3>
+----
+
+===== #merge!
+
+Merges multiple attributes while mutating itself.
+
+[source,ruby]
+----
+Example = Struct.new :a, :b, :c
+example = Example[1, 2, 3]
+example.merge! a: 10                # => #<struct a=10, b=2, c=3>
+example.merge! a: 10, c: 30         # => #<struct a=10, b=2, c=30>
+example.merge! a: 10, b: 20, c: 30  # => #<struct a=10, b=20, c=30>
+example                             # => #<struct a=10, b=20, c=30>
+
+Example = Struct.new :a, :b, :c, keyword_init: true
+example = Example[a: 1, b: 2, c: 3]
+example.merge! a: 10                # => #<struct a=10, b=2, c=3>
+example.merge! a: 10, c: 30         # => #<struct a=10, b=2, c=30>
+example.merge! a: 10, b: 20, c: 30  # => #<struct a=10, b=20, c=30>
+example                             # => #<struct a=10, b=20, c=30>
 ----
 
 == Development

data/lib/refinements.rb

@@ -10,3 +10,4 @@ require "refinements/ios"
 require "refinements/pathnames"
 require "refinements/strings"
 require "refinements/string_ios"
+require "refinements/structs"

data/lib/refinements/arrays.rb

@@ -11,7 +11,21 @@ module Refinements
         replace compress
       end
 
+      def exclude *elements
+        warn "[DEPRECATION]: #exclude is deprecated, use #excluding instead."
+        excluding(*elements)
+      end
+
+      def excluding *elements
+        self - elements.flatten
+      end
+
       def include *elements
+        warn "[DEPRECATION]: #include is deprecated, use #including instead."
+        including(*elements)
+      end
+
+      def including *elements
         self + elements.flatten
       end
 
@@ -19,10 +33,6 @@ module Refinements
         product([elements]).tap(&:pop).flatten.push last
       end
 
-      def exclude *elements
-        self - elements.flatten
-      end
-
       def mean
         size.zero? ? 0 : sum(0) / size
       end

data/lib/refinements/hashes.rb

@@ -13,49 +13,6 @@ module Refinements
     end
 
     refine Hash do
-      def except *keys
-        reject { |key, _value| keys.include? key }
-      end
-
-      def except! *keys
-        replace except(*keys)
-      end
-
-      # :reek:TooManyStatements
-      def flatten_keys prefix: nil, delimiter: "_", cast: :to_sym
-        fail StandardError, "Unknown cast: #{cast}." unless %i[to_sym to_s].include? cast
-
-        reduce({}) do |flat, (key, value)|
-          flat_key = prefix ? "#{prefix}#{delimiter}#{key}" : key
-
-          next flat.merge flat_key.public_send(cast) => value unless value.is_a? self.class
-
-          flat.merge(
-            recurse { value.flatten_keys prefix: flat_key, delimiter: delimiter, cast: cast }
-          )
-        end
-      end
-
-      def flatten_keys! prefix: nil, delimiter: "_", cast: :to_sym
-        replace flatten_keys(prefix: prefix, delimiter: delimiter, cast: cast)
-      end
-
-      def stringify_keys
-        reduce({}) { |hash, (key, value)| hash.merge key.to_s => value }
-      end
-
-      def stringify_keys!
-        replace stringify_keys
-      end
-
-      def symbolize_keys
-        reduce({}) { |hash, (key, value)| hash.merge key.to_sym => value }
-      end
-
-      def symbolize_keys!
-        replace symbolize_keys
-      end
-
       def deep_merge other
         clazz = self.class
 
@@ -88,8 +45,35 @@ module Refinements
         replace deep_symbolize_keys
       end
 
+      def except *keys
+        reject { |key, _value| keys.include? key }
+      end
+
+      def except! *keys
+        replace except(*keys)
+      end
+
+      # :reek:TooManyStatements
+      def flatten_keys prefix: nil, delimiter: "_", cast: :to_sym
+        fail StandardError, "Unknown cast: #{cast}." unless %i[to_sym to_s].include? cast
+
+        reduce({}) do |flat, (key, value)|
+          flat_key = prefix ? "#{prefix}#{delimiter}#{key}" : key
+
+          next flat.merge flat_key.public_send(cast) => value unless value.is_a? self.class
+
+          flat.merge(
+            recurse { value.flatten_keys prefix: flat_key, delimiter: delimiter, cast: cast }
+          )
+        end
+      end
+
+      def flatten_keys! prefix: nil, delimiter: "_", cast: :to_sym
+        replace flatten_keys(prefix: prefix, delimiter: delimiter, cast: cast)
+      end
+
       def recurse &block
-        return self unless block_given?
+        return self unless block
 
         transform = yield self
 
@@ -118,8 +102,24 @@ module Refinements
         replace reverse_merge(other)
       end
 
+      def stringify_keys
+        reduce({}) { |hash, (key, value)| hash.merge key.to_s => value }
+      end
+
+      def stringify_keys!
+        replace stringify_keys
+      end
+
+      def symbolize_keys
+        reduce({}) { |hash, (key, value)| hash.merge key.to_sym => value }
+      end
+
+      def symbolize_keys!
+        replace symbolize_keys
+      end
+
       def use &block
-        return [] unless block_given?
+        return [] unless block
 
         block.parameters
              .map { |(_type, key)| self[key] }

data/lib/refinements/identity.rb

@@ -5,7 +5,7 @@ module Refinements
   module Identity
     NAME = "refinements"
     LABEL = "Refinements"
-    VERSION = "7.12.0"
+    VERSION = "7.16.0"
     VERSION_LABEL = "#{LABEL} #{VERSION}"
   end
 end

data/lib/refinements/ios.rb

@@ -14,10 +14,6 @@ module Refinements
     end
 
     refine IO do
-      def squelch &block
-        self.class.void.then { |void| redirect(void, &block) }
-      end
-
       def redirect other
         return self unless block_given?
 
@@ -30,6 +26,10 @@ module Refinements
       def reread length = nil, buffer: nil
         tap(&:rewind).read length, buffer
       end
+
+      def squelch &block
+        self.class.void.then { |void| redirect(void, &block) }
+      end
     end
   end
 end

data/lib/refinements/pathnames.rb

@@ -12,9 +12,27 @@ module Refinements
       end
     end
 
+    refine Pathname.singleton_class do
+      def home
+        new ENV["HOME"]
+      end
+
+      def make_temp_dir prefix: "temp-", suffix: nil, root: nil
+        Dir.mktmpdir([prefix, suffix], root) { |path| block_given? ? yield(new path) : new(path) }
+      end
+
+      def require_tree root, pattern = "**/*.rb"
+        new(root).files(pattern).each { |path| require path.to_s }
+      end
+
+      def root
+        new "/"
+      end
+    end
+
     refine Pathname do
-      def name
-        basename extname
+      def change_dir &block
+        block ? Dir.chdir(self, &block) : (Dir.chdir self and self)
       end
 
       def copy to
@@ -39,6 +57,28 @@ module Refinements
         self.class.new to_s.gsub(pattern, replacement)
       end
 
+      def make_ancestors
+        dirname.mkpath
+        self
+      end
+
+      def make_dir
+        exist? ? self : mkdir and self
+      end
+
+      def make_path
+        mkpath
+        self
+      end
+
+      def mkdir
+        exist? ? self : super and self
+      end
+
+      def name
+        basename extname
+      end
+
       def relative_parent root_dir
         relative_path_from(root_dir).parent
       end
@@ -49,26 +89,28 @@ module Refinements
         relative_parent root_dir
       end
 
-      def make_ancestors
-        dirname.mkpath
-        self
+      def remove_dir
+        exist? ? (rmdir and self) : self
       end
 
-      # rubocop:disable Style/RedundantSelf
-      def mkdir
-        self.exist? ? self : super and self
+      def remove_tree
+        rmtree if exist?
+        self
       end
-      # rubocop:enable Style/RedundantSelf
 
       def rewrite
         read.then { |content| write yield(content) if block_given? }
-        self
       end
 
       def touch at: Time.now
         exist? ? utime(at, at) : write("")
         self
       end
+
+      def write content, offset: nil, **options
+        super content, offset, **options
+        self
+      end
     end
   end
 end

data/lib/refinements/strings.rb

@@ -12,42 +12,33 @@ module Refinements
     end
 
     refine String do
-      def first number = 0
-        return self if empty?
-
-        max = Integer number
+      def blank?
+        match?(/\A\s*\z/)
+      end
 
-        return self[0] if max.zero?
-        return "" if max.negative?
+      def camelcase
+        return up unless match? DELIMITERS
 
-        self[..(max - 1)]
+        split(%r(\s*-\s*|\s*/\s*|\s*:+\s*)).then { |parts| combine parts, :up, "::" }
+                                           .then { |text| text.split(/\s*_\s*|\s+/) }
+                                           .then { |parts| combine parts, :up }
       end
 
-      def last number = 0
+      def down
         return self if empty?
 
-        min = Integer number
-
-        return self[size - 1] if min.zero?
-        return "" if min.negative?
-
-        self[(min + 1)..]
-      end
-
-      def blank?
-        match?(/\A\s*\z/)
+        first.downcase + self[1, size]
       end
 
-      def up
+      def first number = 0
         return self if empty?
 
-        first.upcase + self[1, size]
-      end
+        max = Integer number
 
-      def down
-        return self if empty?
+        return self[0] if max.zero?
+        return "" if max.negative?
 
-        first.downcase + self[1, size]
+        self[..(max - 1)]
       end
 
       def indent multiplier = 1, padding: "  "
@@ -56,12 +47,15 @@ module Refinements
         padding * multiplier + self
       end
 
-      def camelcase
-        return up unless match? DELIMITERS
+      def last number = 0
+        return self if empty?
 
-        split(%r(\s*-\s*|\s*/\s*|\s*:+\s*)).then { |parts| combine parts, :up, "::" }
-                                           .then { |text| text.split(/\s*_\s*|\s+/) }
-                                           .then { |parts| combine parts, :up }
+        min = Integer number
+
+        return self[size - 1] if min.zero?
+        return "" if min.negative?
+
+        self[(min + 1)..]
       end
 
       def snakecase
@@ -84,6 +78,12 @@ module Refinements
         %w[true yes on t y 1].include? downcase.strip
       end
 
+      def up
+        return self if empty?
+
+        first.upcase + self[1, size]
+      end
+
       private
 
       # :reek:DuplicateMethodCall

data/lib/refinements/structs.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Refinements
+  module Structs
+    refine Struct do
+      def merge **attributes
+        dup.merge! attributes
+      end
+
+      def merge! **attributes
+        to_h.merge(attributes).each { |key, value| self[key] = value }
+        self
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: refinements
 version: !ruby/object:Gem::Version
-  version: 7.12.0
+  version: 7.16.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -28,7 +28,7 @@ cert_chain:
   2XV8FRa7/JimI07sPLC13eLY3xd/aYTi85Z782KIA4j0G8XEEWAX0ouBhlXPocZv
   QWc=
   -----END CERTIFICATE-----
-date: 2020-11-04 00:00:00.000000000 Z
+date: 2020-11-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler-audit
@@ -36,14 +36,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.6'
+        version: '0.7'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.6'
+        version: '0.7'
 - !ruby/object:Gem::Dependency
   name: bundler-leak
   requirement: !ruby/object:Gem::Requirement
@@ -64,28 +64,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '14.2'
+        version: '14.8'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '14.2'
+        version: '14.8'
 - !ruby/object:Gem::Dependency
   name: git-lint
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '1.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '1.3'
 - !ruby/object:Gem::Dependency
   name: guard-rspec
   requirement: !ruby/object:Gem::Requirement
@@ -162,42 +162,42 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.9'
+        version: '3.10'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.9'
+        version: '3.10'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.89'
+        version: '1.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.89'
+        version: '1.3'
 - !ruby/object:Gem::Dependency
   name: rubocop-performance
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.5'
+        version: '1.8'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.5'
+        version: '1.8'
 - !ruby/object:Gem::Dependency
   name: rubocop-rake
   requirement: !ruby/object:Gem::Requirement
@@ -218,14 +218,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.39'
+        version: '2.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.39'
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -262,6 +262,7 @@ files:
 - lib/refinements/pathnames.rb
 - lib/refinements/string_ios.rb
 - lib/refinements/strings.rb
+- lib/refinements/structs.rb
 homepage: https://www.alchemists.io/projects/refinements
 licenses:
 - Apache-2.0