refinements 7.9.0 → 7.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ba7c2934d38986ae19d3a41bdc1305164ebe2355bb30afa925eebbeb9746f962
-  data.tar.gz: 1945d2226c6ca304aa9958635aab6a87880b66e43566691c3ab509f5b2e77f6b
+  metadata.gz: 4abbbd79616d97836ca58503bb4638e2638e14732e76e7c00b3f5c033f708edc
+  data.tar.gz: 516c79b5361a7512ca4e63c72303d8fb0d2cb85c693bc9aa13c36ef767580f10
 SHA512:
-  metadata.gz: 34e601f3bfe0ebe6b35ddf54dea67ef9c33d7436fae5103a2ce03106a34026f1920a6f06369ba2516ceb0a550bb6868fcd5491084cca5b6dd20ed746b4772a39
-  data.tar.gz: 8e4d5de5f29f28df044333dbaa34fb0a6d9b34911e3e911bd5593caf4dfeb52c0c0767f5a01d164542c54a4d936453b14f6131c055234a5911d73c80673c7d14
+  metadata.gz: 2f15aa4b466d6e610a2ffc45ad16285d27107c93a4260d214abcee42e66005951a5f2a708da6b04a28826ab3abd0a85ad0e1a707782b6ba5c51ef5cb0b705ec7
+  data.tar.gz: ec214191217bb870ca264fbfe3fa31d57b6c37c28e0f92806f779d3ea8400fbac11ee4aa38c82d6d10d7b07187a2360a7aa810ef802e6d219a217043cd76e69c

data/LICENSE.adoc

@@ -150,7 +150,7 @@ additional liability.
 
 END OF TERMS AND CONDITIONS
 
-Copyright link:https://www.alchemists.io[Alchemists].
+Copyright 2015 link:https://www.alchemists.io/team/brooke_kuhlmann[Brooke Kuhlmann].
 
 Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in
 compliance with the License. You may obtain a link:https://www.apache.org/licenses/LICENSE-2.0[copy]

data/README.adoc

@@ -6,10 +6,12 @@
 
 [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]
 
-A collection of refinements (enhancements) to core Ruby objects.
+A collection of refinements (enhancements) to primitive Ruby objects.
 
 toc::[]
 
@@ -22,6 +24,7 @@ Enhances the following objects:
 * DateTime
 * File
 * Hash
+* IO
 * Pathname
 * String
 * StringIO
@@ -34,8 +37,6 @@ Enhances the following objects:
 
 == Setup
 
-=== Production
-
 To install, run:
 
 [source,bash]
@@ -50,24 +51,6 @@ Add the following to your Gemfile file:
 gem "refinements"
 ----
 
-=== Development
-
-To contribute, run:
-
-[source,bash]
-----
-git clone https://github.com/bkuhlmann/refinements.git
-cd refinements
-bin/setup
-----
-
-You can also use the IRB console for direct access to all objects:
-
-[source,bash]
-----
-bin/console
-----
-
 == Usage
 
 === Requires
@@ -79,7 +62,7 @@ If all refinements are not desired, add the following to your `+Gemfile+` instea
 gem "refinements", require: false
 ----
 
-…then require the specific refinement, as needed. Example:
+...then require the specific refinement, as needed. Example:
 
 [source,ruby]
 ----
@@ -88,6 +71,7 @@ require "refinements/big_decimals"
 require "refinements/date_times"
 require "refinements/files"
 require "refinements/hashes"
+require "refinements/ios"
 require "refinements/pathnames"
 require "refinements/strings"
 require "refinements/string_ios"
@@ -95,7 +79,8 @@ require "refinements/string_ios"
 
 === Using
 
-Much like including/extending a module, you’ll need modify your object(s) to use the refinement(s):
+Much like including/extending a module, you’ll need to modify your object(s) to use the
+refinement(s):
 
 [source,ruby]
 ----
@@ -105,6 +90,7 @@ class Example
   using Refinements::DateTimes
   using Refinements::Files
   using Refinements::Hashes
+  using Refinements::IOs
   using Refinements::Pathnames
   using Refinements::Strings
   using Refinements::StringIOs
@@ -119,7 +105,7 @@ The following sections demonstrate how each refinement enriches your objects wit
 
 ===== #compress
 
-Removes `nil` and empty values without modifying itself.
+Removes `nil` and empty values without mutating itself.
 
 [source,ruby]
 ----
@@ -130,7 +116,7 @@ example           # => ["An", nil, "", "Example"]
 
 ===== #compress!
 
-Removes `nil` and empty values while modifying itself.
+Removes `nil` and empty values while mutating itself.
 
 [source,ruby]
 ----
@@ -139,24 +125,47 @@ example.compress!  # => ["An", "Example"]
 example            # => ["An", "Example"]
 ----
 
-===== #include
+===== #excluding
+
+Removes given array or elements without mutating itself.
+
+[source,ruby]
+----
+[1, 2, 3, 4, 5].excluding [4, 5]  # => [1, 2, 3]
+[1, 2, 3, 4, 5].excluding 4, 5    # => [1, 2, 3]
+----
+
+===== #including
 
-Adds given array or elements without modifying itself.
+Adds 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].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 modifying 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
+
+Answers mean/average all elements within an array.
+
+[source,ruby]
+----
+[].mean                 # => 0
+[5].mean                # => 5
+[1, 2, 3].mean          # => 2
+[1.25, 1.5, 1.75].mean  # => 1.5
 ----
 
 ===== #ring
@@ -234,127 +243,128 @@ example = Hash.with_default []
 example[:b] # => []
 ----
 
-===== #except
+===== #deep_merge
 
-Answers new hash with given keys removed without modifying itself.
+Merges deeply nested hashes together 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}
+example = {a: "A", b: {one: "One", two: "Two"}}
+example.deep_merge b: {one: 1}  # => {a: "A", b: {one: 1, two: "Two"}}
+example                         # => {a: "A", b: {one: "One", two: "Two"}}
 ----
 
-===== #except!
+===== #deep_merge!
 
-Answers new hash with given keys removed while modifying itself.
+Merges deeply nested hashes together while mutating itself.
 
 [source,ruby]
 ----
-example = {a: 1, b: 2, c: 3}
-example.except! :a, :b  # => {c: 3}
-example                 # => {c: 3}
+example = {a: "A", b: {one: "One", two: "Two"}}
+example.deep_merge! b: {one: 1}  # => {a: "A", b: {one: 1, two: "Two"}}
+example                          # => {a: "A", b: {one: 1, two: "Two"}}
 ----
 
-===== #flatten_keys
+===== #deep_stringify_keys
 
-Flattens nested keys as top-level keys without modifying itself. Does not handle nested arrays,
-though.
+Stringifies keys of nested hash 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}}
+example = {a: {b: 2}}
+example.deep_stringify_keys  # => {"a" => {"b" => 1}}
+example                      # => {a: {b: 2}}
 ----
 
-===== #flatten_keys!
+===== #deep_stringify_keys!
 
-Flattens nested keys as top-level keys while modifying itself. Does not handle nested arrays,
-though.
+Stringifies keys of nested hash 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}
+example = {a: {b: 2}}
+example.deep_stringify_keys!  # => {"a" => {"b" => 1}}
+example                       # => {"a" => {"b" => 1}}
 ----
 
-===== #symbolize_keys
+===== #deep_symbolize_keys
 
-Converts keys to symbols without modifying itself.
+Symbolizes keys of nested hash without mutating itself. Does not handle nested arrays, though.
 
 [source,ruby]
 ----
-example = {"a" => 1, "b" => 2}
-example.symbolize_keys  # => {a: 1, b: 2}
-example                 # => {"a" => 1, "b" => 2}
+example = {"a" => {"b" => 2}}
+example.deep_symbolize_keys  # => {a: {b: 1}}
+example                      # => {"a" => {"b" => 2}}
 ----
 
-===== #symbolize_keys!
+===== #deep_symbolize_keys!
 
-Converts keys to symbols while modifying itself.
+Symbolizes keys of nested hash while mutating itself. Does not handle nested arrays, though.
 
 [source,ruby]
 ----
-example = {"a" => 1, "b" => 2}
-example.symbolize_keys!  # => {a: 1, b: 2}
-example                  # => {a: 1, b: 2}
+example = {"a" => {"b" => 2}}
+example.deep_symbolize_keys!  # => {a: {b: 1}}
+example                       # => {a: {b: 1}}
 ----
 
-===== #deep_merge
+===== #except
 
-Merges deeply nested hashes together without modifying itself.
+Answers new hash with given keys removed without mutating itself.
 
 [source,ruby]
 ----
-example = {a: "A", b: {one: "One", two: "Two"}}
-example.deep_merge b: {one: 1}  # => {a: "A", b: {one: 1, two: "Two"}}
-example                         # => {a: "A", b: {one: "One", two: "Two"}}
+example = {a: 1, b: 2, c: 3}
+example.except :a, :b  # => {c: 3}
+example                # => {a: 1, b: 2, c: 3}
 ----
 
-===== #deep_merge!
+===== #except!
 
-Merges deeply nested hashes together while modifying itself.
+Answers new hash with given keys removed while mutating itself.
 
 [source,ruby]
 ----
-example = {a: "A", b: {one: "One", two: "Two"}}
-example.deep_merge! b: {one: 1}  # => {a: "A", b: {one: 1, two: "Two"}}
-example                          # => {a: "A", b: {one: 1, two: "Two"}}
+example = {a: 1, b: 2, c: 3}
+example.except! :a, :b  # => {c: 3}
+example                 # => {c: 3}
 ----
 
-===== #deep_symbolize_keys
+===== #flatten_keys
 
-Symbolizes keys of nested hash without modifying itself. Does not handle nested arrays, though.
+Flattens nested keys as top-level keys without mutating itself. Does not handle nested arrays,
+though.
 
 [source,ruby]
 ----
-example = {"a" => {"b" => 2}}
-example.deep_symbolize_keys  # => {a: {b: 1}}
-example                      # => {"a" => {"b" => 2}}
+{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}}
 ----
 
-===== #deep_symbolize_keys!
+===== #flatten_keys!
 
-Symbolizes keys of nested hash while modifying itself. Does not handle nested arrays, though.
+Flattens nested keys as top-level keys while mutating itself. Does not handle nested arrays,
+though.
 
 [source,ruby]
 ----
-example = {"a" => {"b" => 2}}
-example.deep_symbolize_keys!  # => {a: {b: 1}}
-example                       # => {a: {b: 1}}
+example = {a: {b: 1}}
+example.flatten_keys!  # => {a_b: 1}
+example                # => {a_b: 1}
 ----
 
 ===== #recurse
 
-Applies block to nested hash. Does not handle nested arrays, though.
+Recursively iterates over the hash and any hash value by applying the given block to it. Does not
+handle nested arrays, though.
 
 [source,ruby]
 ----
@@ -365,7 +375,7 @@ example.recurse(&:invert)          # => {{"b" => 1} => "a"}
 
 ===== #rekey
 
-Transforms keys per mapping (size of mapping can vary) without modifying itself.
+Transforms keys per mapping (size of mapping can vary) without mutating itself.
 
 [source,ruby]
 ----
@@ -376,7 +386,7 @@ example                            # => {a: 1, b: 2, c: 3}
 
 ===== #rekey!
 
-Transforms keys per mapping (size of mapping can vary) while modifying itself.
+Transforms keys per mapping (size of mapping can vary) while mutating itself.
 
 [source,ruby]
 ----
@@ -387,7 +397,7 @@ example                             # => {amber: 1, blue: 2, c: 3}
 
 ===== #reverse_merge
 
-Merges calling hash into passed in hash without modifying itself.
+Merges calling hash into passed in hash without mutating itself.
 
 [source,ruby]
 ----
@@ -398,7 +408,7 @@ example                           # => {a: 1, b: 2}
 
 ===== #reverse_merge!
 
-Merges calling hash into passed in hash while modifying itself.
+Merges calling hash into passed in hash while mutating itself.
 
 [source,ruby]
 ----
@@ -407,6 +417,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.
@@ -417,24 +471,97 @@ example = {unit: "221B", street: "Baker Street", city: "London", country: "UK"}
 example.use { |unit, street| "#{unit} #{street}" } # => "221B Baker Street"
 ----
 
+==== IO
+
+===== .void
+
+Answers an IO stream which points to `/dev/null` in order to ignore any reads or writes to the
+stream. When given a block, the stream will automatically close upon block exit. When not given a
+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
+----
+
+===== #redirect
+
+Redirects current stream to other stream when given a block. Without a block, the original stream is
+answered instead.
+
+[source,ruby]
+----
+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"
+----
+
+===== #reread
+
+Answers full stream by rewinding to beginning of stream and reading all content.
+
+[source,ruby]
+----
+io = IO.new IO.sysopen(Pathname("test.txt").to_s, "w+")
+io.write "This is a test."
+
+io.reread    # => "This is a test."
+io.reread 4  # => "This"
+
+buffer = "".dup
+io.reread(buffer: buffer)
+buffer # => "This is a test."
+----
+
+===== #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 # => ""
+----
+
 ==== Pathname
 
 ===== Pathname
 
-Conversion function (refined from `Kernel`) which can cast `nil` into a 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.
 
 [source,ruby]
 ----
 Pathname(nil) # => Pathname("")
 ----
 
-===== #name
+===== #change_dir
 
-Answers file name without extension.
+Inherits and wraps `Dir.chdir` behavior by changing to directory of current path. See
+link:https://rubyapi.org/2.7/o/s?q=Dir.chdir[Dir.chdir] for details.
 
 [source,ruby]
 ----
-Pathname("example.txt").name # => Pathname("example")
+Pathname.pwd                           # => "/"
+Pathname("/test").make_dir.change_dir  # => Pathname "/test"
+Pathname.pwd                           # => "/test"
+
+Pathname.pwd                                                        # => "/"
+Pathname("/test").make_dir.change_dir { # Implementation details }  # => Pathname "/test"
+Pathname.pwd                                                        # => "/"
 ----
 
 ===== #copy
@@ -490,6 +617,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").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`.
@@ -499,15 +668,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")
+----
+
+===== #remove_tree
+
+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]
+----
+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
@@ -532,60 +723,64 @@ Pathname("example.txt").touch at: Time.now - 1
 
 ==== String
 
-===== #first
+===== #blank?
 
-Answers first character of a string or first set of characters if given a number.
+Answers `true`/`false` based on whether string is blank, `<space>`, `\n`, `\t`, and/or `\r`.
 
 [source,ruby]
 ----
-"example".first    # => "e"
-"example".first 4  # => "exam"
+" \n\t\r".blank? # => true
 ----
 
-===== #last
+===== #camelcase
 
-Answers last character of a string or last set of characters if given a number.
+Answers a camelcased string.
 
 [source,ruby]
 ----
-"instant".last    # => "t"
-"instant".last 3  # => "ant"
+"this_is_an_example".camelcase # => "ThisIsAnExample"
 ----
 
-===== #blank?
+===== #down
 
-Answers `true`/`false` based on whether string is blank, `<space>`, `\n`, `\t`, and/or `\r`.
+Answers string with only first letter downcased.
 
 [source,ruby]
 ----
-" \n\t\r".blank? # => true
+"EXAMPLE".down # => "eXAMPLE"
 ----
 
-===== #up
+===== #first
 
-Answers string with only first letter upcased.
+Answers first character of a string or first set of characters if given a number.
 
 [source,ruby]
 ----
-"example".up # => "Example"
+"example".first    # => "e"
+"example".first 4  # => "exam"
 ----
 
-===== #down
+===== #indent
 
-Answers string with only first letter downcased.
+Answers string indented by two spaces by default.
 
 [source,ruby]
 ----
-"EXAMPLE".down # => "eXAMPLE"
+"example".indent                  # => "  example"
+"example".indent 0                # => "example"
+"example".indent -1               # => "example"
+"example".indent 2                # => "    example"
+"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
@@ -619,6 +814,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
@@ -638,6 +842,24 @@ io.reread(buffer: buffer)
 buffer # => "This is a test."
 ----
 
+== Development
+
+To contribute, run:
+
+[source,bash]
+----
+git clone https://github.com/bkuhlmann/refinements.git
+cd refinements
+bin/setup
+----
+
+You can also use the IRB console for direct access to all objects:
+
+[source,bash]
+----
+bin/console
+----
+
 == Tests
 
 To test, run:

data/lib/refinements.rb

@@ -6,6 +6,7 @@ require "refinements/big_decimals"
 require "refinements/date_times"
 require "refinements/files"
 require "refinements/hashes"
+require "refinements/ios"
 require "refinements/pathnames"
 require "refinements/strings"
 require "refinements/string_ios"

data/lib/refinements/arrays.rb

@@ -11,12 +11,30 @@ 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
 
-      def exclude *elements
-        self - elements.flatten
+      def intersperse *elements
+        product([elements]).tap(&:pop).flatten.push last
+      end
+
+      def mean
+        size.zero? ? 0 : sum(0) / size
       end
 
       def ring &block

data/lib/refinements/hashes.rb

@@ -13,6 +13,38 @@ module Refinements
     end
 
     refine Hash do
+      def deep_merge other
+        clazz = self.class
+
+        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
+          end
+        end
+      end
+
+      def deep_merge! other
+        replace deep_merge(other)
+      end
+
+      def deep_stringify_keys
+        recurse(&:stringify_keys)
+      end
+
+      def deep_stringify_keys!
+        replace deep_stringify_keys
+      end
+
+      def deep_symbolize_keys
+        recurse(&:symbolize_keys)
+      end
+
+      def deep_symbolize_keys!
+        replace deep_symbolize_keys
+      end
+
       def except *keys
         reject { |key, _value| keys.include? key }
       end
@@ -40,38 +72,6 @@ module Refinements
         replace flatten_keys(prefix: prefix, delimiter: delimiter, cast: cast)
       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
-
-        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
-          end
-        end
-      end
-
-      def deep_merge! other
-        replace deep_merge(other)
-      end
-
-      def deep_symbolize_keys
-        recurse(&:symbolize_keys)
-      end
-
-      def deep_symbolize_keys!
-        replace deep_symbolize_keys
-      end
-
       def recurse &block
         return self unless block_given?
 
@@ -102,6 +102,22 @@ 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?
 

data/lib/refinements/identity.rb

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

data/lib/refinements/ios.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Refinements
+  module IOs
+    refine IO.singleton_class do
+      def void
+        new(sysopen("/dev/null", "w+")).then do |io|
+          return io unless block_given?
+
+          yield io
+          io.tap(&:close)
+        end
+      end
+    end
+
+    refine IO do
+      def redirect other
+        return self unless block_given?
+
+        backup = dup
+        reopen other
+        yield self
+        reopen backup
+      end
+
+      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

@@ -13,8 +13,8 @@ module Refinements
     end
 
     refine Pathname do
-      def name
-        basename extname
+      def change_dir &block
+        block_given? ? Dir.chdir(self, &block) : (Dir.chdir self and self)
       end
 
       def copy to
@@ -39,6 +39,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,8 +71,12 @@ module Refinements
         relative_parent root_dir
       end
 
-      def make_ancestors
-        dirname.mkpath
+      def remove_dir
+        exist? ? (rmdir and self) : self
+      end
+
+      def remove_tree
+        rmtree if exist?
         self
       end
 

data/lib/refinements/strings.rb

@@ -12,6 +12,24 @@ module Refinements
     end
 
     refine String do
+      def blank?
+        match?(/\A\s*\z/)
+      end
+
+      def camelcase
+        return up unless match? DELIMITERS
+
+        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 down
+        return self if empty?
+
+        first.downcase + self[1, size]
+      end
+
       def first number = 0
         return self if empty?
 
@@ -23,6 +41,12 @@ module Refinements
         self[..(max - 1)]
       end
 
+      def indent multiplier = 1, padding: "  "
+        return self if multiplier.negative?
+
+        padding * multiplier + self
+      end
+
       def last number = 0
         return self if empty?
 
@@ -34,30 +58,6 @@ module Refinements
         self[(min + 1)..]
       end
 
-      def blank?
-        match?(/\A\s*\z/)
-      end
-
-      def up
-        return self if empty?
-
-        first.upcase + self[1, size]
-      end
-
-      def down
-        return self if empty?
-
-        first.downcase + self[1, size]
-      end
-
-      def camelcase
-        return up unless match? DELIMITERS
-
-        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 snakecase
         return downcase unless match? DELIMITERS
 
@@ -78,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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: refinements
 version: !ruby/object:Gem::Version
-  version: 7.9.0
+  version: 7.14.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -28,7 +28,7 @@ cert_chain:
   2XV8FRa7/JimI07sPLC13eLY3xd/aYTi85Z782KIA4j0G8XEEWAX0ouBhlXPocZv
   QWc=
   -----END CERTIFICATE-----
-date: 2020-09-19 00:00:00.000000000 Z
+date: 2020-11-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler-audit
@@ -36,42 +36,28 @@ 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: gemsmith
+  name: bundler-leak
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '14.2'
+        version: '0.2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '14.2'
-- !ruby/object:Gem::Dependency
-  name: git-lint
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: guard-rspec
   requirement: !ruby/object:Gem::Requirement
@@ -148,42 +134,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
@@ -204,14 +190,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
@@ -244,6 +230,7 @@ files:
 - lib/refinements/files.rb
 - lib/refinements/hashes.rb
 - lib/refinements/identity.rb
+- lib/refinements/ios.rb
 - lib/refinements/pathnames.rb
 - lib/refinements/string_ios.rb
 - lib/refinements/strings.rb