refinements 10.1.1 → 11.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 82142460f83d84a2b94bf4a1e6c07b4c6839e91f2da64192e0c64a36382fe3e5
-  data.tar.gz: d657c64e946049d4c946513329446b781880c34c76301408318a8487e0728f17
+  metadata.gz: 252744b620f3c79a0c38b635157f62fc9e48527701145e871de885c547b44b61
+  data.tar.gz: 411b88c5cf6b9b95c59c43055b8a2402c95d9954b612837fce70a106c4c4a5f1
 SHA512:
-  metadata.gz: 81df10e22a7fb65d5737e7a8c23114fdecd47bcdecf532bc231612d29cd9036a90444fd8d59b5d140ab7c72347a1bbbbc9dee9b1e8c3464962b146ad5dc82085
-  data.tar.gz: 4446cffdb57fe7383f891193a95edc8c0a023da2f6670fb13a00730be21113123a55f8f13ad9cf9fad39954af418142e5e17e8b6b00cac0fb815b5ed6592252d
+  metadata.gz: 0c12fb201556e5949190657cd591b126115ba7efb9f14aec4aeb107455d7cd04676b0dd1cc05f84e9bdd8b7c61e2fbadbabe377b739ffd14a643c3d98d717068
+  data.tar.gz: db75e0359afed8603daba0bae481b8e839b9d9ede700ef22bbcde22116e2a75b221b5d56d0381500ccf992f73c11cb7a4555823c4294b131077972800a03f3c1

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(:test)            # 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 :test             # []
+----
+
+===== #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                                        # ""
+["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 "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 show the element types used.
+
+[source,ruby]
+----
+[].to_usage                                        # ""
+["test"].to_usage                                  # "test"
+["a", :b].to_usage                                 # "a and b"
+[1, "a", :b, 2.0, /\w+/].map(&:inspect).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
@@ -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.0"
   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.0
 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-13 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: []