refinements 10.1.1 → 11.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 82142460f83d84a2b94bf4a1e6c07b4c6839e91f2da64192e0c64a36382fe3e5
-  data.tar.gz: d657c64e946049d4c946513329446b781880c34c76301408318a8487e0728f17
+  metadata.gz: efdcd2042bcfde5031fad3d0049e01fc4e1ad23a9d4841ee601fdcb02a96d3af
+  data.tar.gz: 55fac5447439c53705870a9409268e96aaf633e7a420f9d4678257f9b68f078d
 SHA512:
-  metadata.gz: 81df10e22a7fb65d5737e7a8c23114fdecd47bcdecf532bc231612d29cd9036a90444fd8d59b5d140ab7c72347a1bbbbc9dee9b1e8c3464962b146ad5dc82085
-  data.tar.gz: 4446cffdb57fe7383f891193a95edc8c0a023da2f6670fb13a00730be21113123a55f8f13ad9cf9fad39954af418142e5e17e8b6b00cac0fb815b5ed6592252d
+  metadata.gz: 81949b0fb95b4aca53d6fd88f51d8cb4f0c8738bbb3eac83816880ff6b479ac86228847dd6660d8a99a861c5e3aee6e6985a0628764af037b328db55422cc7fb
+  data.tar.gz: 6b40c6be0c5cc6304366fe60c8df54bca9e3ab366338f45308b2267f9a81f6adb123002740feb933af3313a0349a9a5035c39525c0b90d48f875842fefd0c3cf

data/README.adoc

@@ -31,18 +31,34 @@ Enhances the following objects:
 
 == Setup
 
-To install, run:
+To install _with_ security, run:
+
+[source,bash]
+----
+# 💡 Skip this line if you already have the public certificate installed.
+gem cert --add <(curl --compressed --location https://alchemists.io/gems.pem)
+gem install refinements --trust-policy HighSecurity
+----
+
+To install _without_ security, run:
 
 [source,bash]
 ----
 gem install refinements
 ----
 
-Add the following to your Gemfile file:
+You can also add the gem directly to your project:
+
+[source,bash]
+----
+bundle add refinements
+----
+
+Once the gem is installed, you only need to require it:
 
 [source,ruby]
 ----
-gem "refinements"
+require "refinements"
 ----
 
 == Usage
@@ -262,6 +278,46 @@ needs to be a specific size with padded values.
 [1, 2].pad 3, max: 3  # [1, 2, 3]
 ----
 
+===== #pick
+
+Answers value of first element that matches given key.
+
+[source,ruby]
+----
+array = [{name: "a", label: "A"}, {name: "b", label: "B"}, {name: "c", label: "C"}]
+
+array.pick :name          # "a"
+array.pick :name, :label  # ["a", "A"]
+array.pick                # nil
+[].pick(:other)           # nil
+----
+
+===== #pluck
+
+Answers values of all elements that match given keys.
+
+[source,ruby]
+----
+array = [{name: "a", label: "A"}, {name: "b", label: "B"}, {name: "c", label: "C"}]
+
+array.pluck :name          # ["a", "b", "c"]
+array.pluck :name, :label  # [["a", "A"], ["b", "B"], ["c", "C"]]
+array.pluck                # []
+[].pluck :other            # []
+----
+
+===== #replace_at
+
+Answers mutated array where an element -- at a specific index -- is replaced by single or multiple elements.
+
+[source,ruby]
+----
+%i[a b c].replace_at(0, :x)      # [:x, :b, :c]
+%i[a b c].replace_at(1, :x)      # [:a, :x, :c]
+%i[a b c].replace_at(1, :x, :y)  # [:a, :x, :y, :c]
+%i[a b c].replace_at(-1, :x)     # [:a, :b, :x]
+----
+
 ===== #ring
 
 Answers a circular array which can enumerate before, current, after elements.
@@ -303,17 +359,31 @@ Answers mutated array where all target elements are replaced by single or multip
 
 ===== #to_sentence
 
-Answers a sentence using `", "` as the default delimiter and `"and"` as the default conjunction.
+Answers a sentence using `"and"` as the default conjunction and `", "` as the default delimiter.
 Useful when building documentation, answering human readable error messages, etc.
 
 [source,ruby]
 ----
-[].to_sentence                                                     # ""
-["test"].to_sentence                                               # "test"
-["a", :b].to_sentence                                              # "a and b"
-[1, "a", :b, 2.0, /\w+/].map(&:inspect).to_sentence                # 1, "a", :b, 2.0, and /\w+/
-%w[one two three].to_sentence                                      # "one, two, and three"
-%w[eins zwei drei].to_sentence delimiter: " ", conjunction: "und"  # "eins zwei und drei"
+[].to_sentence                                        # ""
+["demo"].to_sentence                                  # "demo"
+["a", :b].to_sentence                                 # "a and b"
+[1, "a", :b, 2.0, /\w+/].to_sentence                  # "1, a, b, 2.0, and (?-mix:\\w+)"
+%w[one two three].to_sentence                         # "one, two, and three"
+%w[eins zwei drei].to_sentence "und", delimiter: " "  # "eins zwei und drei"
+----
+
+===== #to_usage
+
+Builds upon and enhances `#to_sentence` further by answering a sentence which all elements are inspected -- where each element of the array is called with `#inspect` -- before turned into a sentence using `"and"` as the default conjunction and `", "` as the default delimiter. This is useful when providing detailed error messages _and_ you need to detail the types of element used.
+
+[source,ruby]
+----
+[].to_usage                                        # ""
+["demo"].to_usage                                  # "\"demo\""
+["a", :b].to_usage                                 # "\"a\" and :b"
+[1, "a", :b, 2.0, /\w+/].to_usage                  # "1, \"a\", :b, 2.0, and /\\w+/"
+%w[one two three].to_usage                         # "\"one\", \"two\", and \"three\""
+%w[eins zwei drei].to_usage "und", delimiter: " "  # "\"eins\" \"zwei\" und \"drei\""
 ----
 
 ==== Big Decimal
@@ -470,12 +540,12 @@ expression `example.fetch(:desired_key) || "default_value"`.
 
 [source,ruby]
 ----
-{a: "test"}.fetch_value :a, "default"  # "test"
-{a: "test"}.fetch_value :a             # "test"
+{a: "demo"}.fetch_value :a, "default"  # "demo"
+{a: "demo"}.fetch_value :a             # "demo"
 {a: nil}.fetch_value :a, "default"     # "default"
 {}.fetch_value(:a) { "default" }       # "default"
 {}.fetch_value :a                      # KeyError
-{a: "test"}.fetch_value                # ArgumentError
+{a: "demo"}.fetch_value                # ArgumentError
 ----
 
 ===== #flatten_keys
@@ -485,7 +555,7 @@ though.
 
 [source,ruby]
 ----
-{a: {b: 1}}.flatten_keys prefix: :test          # {test_a_b: 1}
+{a: {b: 1}}.flatten_keys prefix: :demo          # {demo_a_b: 1}
 {a: {b: 1}}.flatten_keys delimiter: :|          # {:"a|b" => 1}
 
 example = {a: {b: 1}}
@@ -500,7 +570,7 @@ though.
 
 [source,ruby]
 ----
-{a: {b: 1}}.flatten_keys! prefix: :test          # {test_a_b: 1}
+{a: {b: 1}}.flatten_keys! prefix: :demo          # {demo_a_b: 1}
 {a: {b: 1}}.flatten_keys! delimiter: :|          # {:"a|b" => 1}
 
 example = {a: {b: 1}}
@@ -665,11 +735,11 @@ answered instead.
 
 [source,ruby]
 ----
-io = IO.new IO.sysopen(Pathname("test.txt").to_s, "w+")
+io = IO.new IO.sysopen(Pathname("demo.txt").to_s, "w+")
 other = IO.new IO.sysopen(Pathname("other.txt").to_s, "w+")
 
 io.redirect other                                    # "#<IO:fd 20>"
-io.redirect(other) { |stream| stream.write "test" }  # "#<IO:fd 21>"
+io.redirect(other) { |stream| stream.write "demo" }  # "#<IO:fd 21>"
 ----
 
 ===== #reread
@@ -678,15 +748,15 @@ 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 = IO.new IO.sysopen(Pathname("demo.txt").to_s, "w+")
+io.write "This is a demo."
 
-io.reread                  # "This is a test."
+io.reread                  # "This is a demo."
 io.reread 4                # "This"
 
 buffer = "".dup
-io.reread(buffer: buffer)  # "This is a test."
-buffer                     # "This is a test."
+io.reread(buffer: buffer)  # "This is a demo."
+buffer                     # "This is a demo."
 ----
 
 ===== #squelch
@@ -813,8 +883,7 @@ Pathname.make_temp_dir { |path| path.join "sub_dir" }        # Pathname:/var/fol
 
 ===== .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:
+Requires all Ruby files in given root path and corresponding nested tree structure. All files are sorted before being required to ensure consistent behavior. Example:
 
 [source,ruby]
 ----
@@ -1142,11 +1211,11 @@ Answers indentation (string) which is the result of the multiplier times padding
 
 [source,ruby]
 ----
-"example".indent                  # "  example"
-"example".indent 0                # "example"
-"example".indent -1               # "example"
-"example".indent 2                # "    example"
-"example".indent 3, padding: " "  # "   example"
+"example".indent              # "  example"
+"example".indent 0            # "example"
+"example".indent -1           # "example"
+"example".indent 2            # "    example"
+"example".indent 3, pad: " "  # "   example"
 ----
 
 ===== #last

data/lib/refinements/arrays.rb

@@ -33,6 +33,29 @@ module Refinements
 
       def pad(value, max: size) = dup.fill(value, size..(max - 1))
 
+      def pick(*keys)
+        return if empty?
+
+        keys.many? ? keys.map { |key| first[key] } : first[keys.first]
+      end
+
+      def pluck(*keys)
+        return dup if empty?
+        return [] if keys.empty?
+
+        if keys.many?
+          map { |element| keys.map { |key| element[key] } }
+        else
+          key = keys.first
+          map { |element| element[key] }
+        end
+      end
+
+      def replace_at(index, *elements)
+        delete_at index
+        insert(index, *elements)
+      end
+
       def ring(&) = [last, *self, first].each_cons(3, &)
 
       def supplant target, *replacements
@@ -49,13 +72,17 @@ module Refinements
         self
       end
 
-      def to_sentence delimiter: ", ", conjunction: "and"
+      def to_sentence conjunction = "and", delimiter: ", "
         case length
           when (3..) then "#{self[..-2].join delimiter}#{delimiter}#{conjunction} #{last}"
           when 2 then join " #{conjunction} "
           else join
         end
       end
+
+      def to_usage conjunction = "and", delimiter: ", "
+        map(&:inspect).to_sentence conjunction, delimiter:
+      end
     end
   end
 end

data/lib/refinements/pathnames.rb

@@ -24,9 +24,7 @@ module Refinements
         end
       end
 
-      def require_tree root, pattern = "**/*.rb"
-        new(root).files(pattern).each { |path| require path.to_s }
-      end
+      def require_tree(root) = new(root).files("**/*.rb").each { |path| require path.to_s }
 
       def root = new(File::SEPARATOR)
     end

data/lib/refinements/strings.rb

@@ -26,8 +26,8 @@ module Refinements
         self[..(maximum - 1)]
       end
 
-      def indent multiplier = 1, padding: "  "
-        multiplier.negative? ? self : (padding * multiplier) + self
+      def indent multiplier = 1, pad: "  "
+        multiplier.negative? ? self : (pad * multiplier) + self
       end
 
       def last minimum = 0

data/refinements.gemspec

@@ -2,11 +2,11 @@
 
 Gem::Specification.new do |spec|
   spec.name = "refinements"
-  spec.version = "10.1.1"
+  spec.version = "11.0.1"
   spec.authors = ["Brooke Kuhlmann"]
   spec.email = ["brooke@alchemists.io"]
   spec.homepage = "https://alchemists.io/projects/refinements"
-  spec.summary = "A collection of refinements to core Ruby objects."
+  spec.summary = "A collection of core Ruby object refinements."
   spec.license = "Hippocratic-2.1"
 
   spec.metadata = {

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: refinements
 version: !ruby/object:Gem::Version
-  version: 10.1.1
+  version: 11.0.1
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -35,7 +35,7 @@ cert_chain:
   3n5C8/6Zh9DYTkpcwPSuIfAga6wf4nXc9m6JAw8AuMLaiWN/r/2s4zJsUHYERJEu
   gZGm4JqtuSg8pYjPeIJxS960owq+SfuC+jxqmRA54BisFCv/0VOJi7tiJVY=
   -----END CERTIFICATE-----
-date: 2023-04-08 00:00:00.000000000 Z
+date: 2023-06-19 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -90,8 +90,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
+rubygems_version: 3.4.14
 signing_key:
 specification_version: 4
-summary: A collection of refinements to core Ruby objects.
+summary: A collection of core Ruby object refinements.
 test_files: []