refinements 10.1.0 → 11.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: acd50ef5bb4db84f4db8c509c2deab9203e0e7c036e880d43ed047d540c961cf
-  data.tar.gz: df6ebf181b200aeb38f14f3f691f844735e1e352741bc6e7cd667970c5b81b6a
+  metadata.gz: 252744b620f3c79a0c38b635157f62fc9e48527701145e871de885c547b44b61
+  data.tar.gz: 411b88c5cf6b9b95c59c43055b8a2402c95d9954b612837fce70a106c4c4a5f1
 SHA512:
-  metadata.gz: 53703faa9a8b2941e562561a1f9edf22920fdd3934e7d6b55ec3e4290ad18d3e6282e96733c658accf58d475e6f0f78a6687c4777cb7fe2bc49edfdb9707b17b
-  data.tar.gz: 0ddb2f12bb1fcd7aefc06f6c9f2ce891c9929828a79162610824a8a5cf3ffa991d476118f9c5a106fb681c9603a6b8c1ba0dbeaf80004317c990b4673152f8ff
+  metadata.gz: 0c12fb201556e5949190657cd591b126115ba7efb9f14aec4aeb107455d7cd04676b0dd1cc05f84e9bdd8b7c61e2fbadbabe377b739ffd14a643c3d98d717068
+  data.tar.gz: db75e0359afed8603daba0bae481b8e839b9d9ede700ef22bbcde22116e2a75b221b5d56d0381500ccf992f73c11cb7a4555823c4294b131077972800a03f3c1

data/README.adoc

@@ -4,11 +4,7 @@
 
 = Refinements
 
-Refinements are a collection primitive Ruby objects enhancements without needing to resort to hard
-to debug link:https://alchemists.io/articles/ruby_antipatterns/#_monkey_patches[monkey patches].
-These refinements give you additional syntactic sugar to develop clean and concise implementations
-while using less code. By refining our code we can acquire the functionality we wish the core
-primitives had!
+These refinements augment and enhance Ruby primitives so you can avoid link:https://alchemists.io/articles/ruby_antipatterns/#_monkey_patches[monkey patches]. They also allow you to develop clean and concise implementations while using less code. By refining your code, you can acquire the functionality you wish the core primitives had!
 
 toc::[]
 
@@ -31,30 +27,45 @@ Enhances the following objects:
 == Requirements
 
 . https://www.ruby-lang.org[Ruby].
-. A solid understanding of link:https://alchemists.io/articles/ruby_refinements[Ruby refinements
-  and lexical scope].
+. A solid understanding of link:https://alchemists.io/articles/ruby_refinements[refinements].
 
 == 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
 
 === Requires
 
-If all refinements are not desired, add the following to your `+Gemfile+` instead:
+If no refinements are desired, then add the following to your `Gemfile` instead:
 
 [source,ruby]
 ----
@@ -195,7 +206,7 @@ Adds given array or elements without mutating itself.
 
 ===== #intersperse
 
-Inserts additional elements or array between all members of given array.
+Inserts additional elements or an array between all members of given array.
 
 [source,ruby]
 ----
@@ -267,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.
@@ -308,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
@@ -371,7 +436,7 @@ example[:b]  # []
 
 ===== #compress
 
-Removes `nil` and empty objects without mutating itself. Answers itself if there is nothing to remove.
+Removes `nil` and empty objects without mutating itself. Answers itself if nothing to remove.
 
 [source,ruby]
 ----
@@ -386,7 +451,7 @@ example                # {a: 1, b: "blueberry", c: nil, d: "", e: [], f: {}, g:
 
 ===== #compress!
 
-Removes `nil` and empty objects while mutating itself. Answers `nil` if there is nothing to remove.
+Removes `nil` and empty objects while mutating itself. Answers `nil` if nothing to remove.
 
 [source,ruby]
 ----
@@ -584,9 +649,7 @@ example                  # {a: 1, b: 2}
 
 ===== #transform_with
 
-Transforms key/value pairs based on specific operations where each operation (i.e. function that responds to the `call` message). Does not mutate itself.
-
-You can transform multiple values at once:
+Transforms values of keys using specific operations (i.e. any object that responds to `#call`). Does not mutate itself and you can transform multiple values at once:
 
 [source,ruby]
 ----
@@ -605,7 +668,7 @@ example.transform_with bogus: -> value { value.tr "<>", "" }
 # {email: "<jd@example.com>"}
 ----
 
-The original object will not be mutated:
+The original object _will not_ be mutated:
 
 [source,ruby]
 ----
@@ -614,9 +677,7 @@ example  # {name: "Jayne Doe", email: "<jd@example.com>"}
 
 ===== #transform_with!
 
-Transforms key/value pairs based on specific operations where each operation (i.e. function that responds to the `call` message). Mutates itself.
-
-You can transform multiple values at once:
+Transforms values of keys using specific operations (i.e. any object that responds to `#call`). Mutates itself and you can transform multiple values at once:
 
 [source,ruby]
 ----
@@ -635,7 +696,7 @@ example.transform_with! bogus: -> value { value.tr "<>", "" }
 # {email: "<jd@example.com>"}
 ----
 
-The original object will be mutated:
+The original object _will be_ mutated:
 
 [source,ruby]
 ----
@@ -644,7 +705,7 @@ example  # {name: "Jayne", email: "jd@example.com"}
 
 ===== #use
 
-Passes each hash value as a block argument for further processing.
+Uses the hash's keys as block arguments where the value of the block argument is equal to the value of the key found within the hash. Works best with hashes that use symbols for keys but falls back to string keys when symbol keys can't be found.
 
 [source,ruby]
 ----
@@ -822,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]
 ----
@@ -1147,15 +1207,15 @@ Answers first character of a string or first set of characters if given a number
 
 ===== #indent
 
-Answers string indented by two spaces by default.
+Answers indentation (string) which is the result of the multiplier times padding. By default, the multiplier is `1` and the padding is `"  "` which equates to two spaces.
 
 [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/big_decimals.rb

@@ -6,7 +6,7 @@ module Refinements
   # Provides additional enhancements to the BigDecimal primitive.
   module BigDecimals
     refine BigDecimal do
-      def inspect = format("#<BigDecimal:%{id} %{string}>", id: object_id, string: to_s("F"))
+      def inspect = format("#<BigDecimal:%<id>s %<string>s>", id: object_id, string: to_s("F"))
     end
   end
 end

data/lib/refinements/hashes.rb

@@ -85,7 +85,7 @@ module Refinements
         return [] unless block
 
         block.parameters
-             .map { |(_type, key)| self[key] }
+             .map { |(_type, key)| self[key] || self[key.to_s] }
              .then { |values| yield values }
       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.0"
+  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 = {

data.tar.gz.sig

@@ -1,2 +1,3 @@
-�ED�j���ѹ��ĜF��FCށ:ϳ��'�� ;o^џ�xSm\'�̤`�dg��i��uw(�G��o�K"`�	��f�q�BjMz��&<���)Z�2��Q}�O�-�}����!���I;��+�9U�Lp|K�
-%fí�	���
�D�t�Z�p�e(�ީr�L�]���呔�os�1��E{]L�d�΅*�D�b
�L�6̹�d��p�^1�!?+|boÈ�c]��>#n��3���lQ5!�.�h���"�!���!�4(!�zj�$mH'`q�1�N4Z���uw�@��7[s�2{�p)\XMm��$W�֑�e>������d�P�x(UI�I����\��2��c����W�9�b5�}_���*cD�c�@F*�q?K
+��ã?_���۶5Πu#=��i;��w�7�����K׮<�`I����0������$*)�Jv�KƩp|#��2��Z�d��2�Tlӆ�H��*�#ݠ�m�B�&�+��V Jx��;Zo��N
+'j|�6L�d
SF��A}���SJQJ���U�ӻ�q��
UB�ʕ-��Z{]�q�
��?0�HG��ʕ#�T���t�y��ޙB7�ѻ���oہo	9`��c��Mچ
+']fP�E����

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: refinements
 version: !ruby/object:Gem::Version
-  version: 10.1.0
+  version: 11.0.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -10,32 +10,32 @@ bindir: bin
 cert_chain:
 - |
   -----BEGIN CERTIFICATE-----
-  MIIEZDCCAsygAwIBAgIBATANBgkqhkiG9w0BAQsFADA8MQwwCgYDVQQDDAN5b3Ux
-  FzAVBgoJkiaJk/IsZAEZFgdleGFtcGxlMRMwEQYKCZImiZPyLGQBGRYDY29tMB4X
-  DTIzMDMyMjE1NTAzNloXDTI1MDMyMTE1NTAzNlowPDEMMAoGA1UEAwwDeW91MRcw
-  FQYKCZImiZPyLGQBGRYHZXhhbXBsZTETMBEGCgmSJomT8ixkARkWA2NvbTCCAaIw
-  DQYJKoZIhvcNAQEBBQADggGPADCCAYoCggGBAMD1xmCyBRDIgMr9h+bXYgckAJwj
-  EE8d49cWc4IgxXLEz7E/r3+DVWfbviErgQEjqZztso/5jormLpS2LC3VNjRXWdSN
-  3QoD51J3/OnAsW340sXTVvj5M9KD5ZkDo+QIoQO1Dp8QZKI5Ney8gTUxCj5857sX
-  XqWmBjgOK3lFnPOMWRtbVaBh7059eiCu3+LYhVgBgMgcTtYSCluHffzAVt9j8lAE
-  NwCxK8TSZqIQVBQOZgvCqiciKa1cwBGrKgCSdpZdt9gj9WmawQXMmeep2fFOQ8Fi
-  7Y6LWtUfVVvzIKL1BqEyCGH5/Gh0ll/ONPMc4YTXsDs+dQEL+FanoqlUmtH7cpvB
-  VGeXQZu6SeDx/QqvjXYUcrWC34tsiyZS2iC4zsTdtLsi2fwjtvvsO/6Mx9l9BoQ2
-  yM2jWGB/dMijDEmrvIWDDd5+pDCpZwOwp+6OuhSBIyT780z8hwSpQUH8C89AJAK0
-  k0HK4ULXbJOQEQz0RVfvwcJXBxR9g2J0u/VAGQIDAQABo3EwbzAJBgNVHRMEAjAA
-  MAsGA1UdDwQEAwIEsDAdBgNVHQ4EFgQUynDeWx+yghZzQ73QtK3reacuXSEwGgYD
-  VR0RBBMwEYEPeW91QGV4YW1wbGUuY29tMBoGA1UdEgQTMBGBD3lvdUBleGFtcGxl
-  LmNvbTANBgkqhkiG9w0BAQsFAAOCAYEAPJeQGa0T03CxyhFLeBLeKNRA3JMCJWwS
-  4EHmMNOkVFyCo4FCGFunKFUE0HucA8NEaolQ1t+8SSfvfXE5+7kpxdPDHjAr2zFy
-  3+I33zGhRhhFlcJRQ6QH7WFYJvMrjMDhSbU3JDHLIrL2kmzkmRJ2GST+E1ztAbaO
-  OvrW8J5Eab5nJdADcZZaEc7RfGfyl1eGoJt6cho71GMyTfXk2aGfk2XZAJ5JI1G/
-  rbfQGPsune5CPTnY3a0VPK7f6s07WvZ9XWfJ7MgRcAcXCIg6xC1SYk9B6hi3swIQ
-  Pp4POByvlvVl9HbcmCaEO1IGE1cQLLz6gxDFyFIrDwbimNibwb3JW4x8X0wIQMf+
-  W3TjRZkQUZvoB8gKv8Y/CtDZvBjB5joEgEq5JxbOS4v1AKt0EydIB78S5cGNlgml
-  2rAoRKxft/8MhVs5yHlkqOf+JFFGYnvXVMtXfAKw8Sp4CamkVQmlULd2d2GKQHap
-  9xhcE6ZO5JU1gPGPIxJ383ce1NoNTP7e
+  MIIEeDCCAuCgAwIBAgIBATANBgkqhkiG9w0BAQsFADBBMQ8wDQYDVQQDDAZicm9v
+  a2UxGjAYBgoJkiaJk/IsZAEZFgphbGNoZW1pc3RzMRIwEAYKCZImiZPyLGQBGRYC
+  aW8wHhcNMjMwMzIyMTYxNDQxWhcNMjUwMzIxMTYxNDQxWjBBMQ8wDQYDVQQDDAZi
+  cm9va2UxGjAYBgoJkiaJk/IsZAEZFgphbGNoZW1pc3RzMRIwEAYKCZImiZPyLGQB
+  GRYCaW8wggGiMA0GCSqGSIb3DQEBAQUAA4IBjwAwggGKAoIBgQCro8tj5/E1Hg88
+  f4qfiwPVd2zJQHvdYt4GHVvuHRRgx4HGhJuNp+4BId08RBn7V6V1MW6MY3kezRBs
+  M+7QOQ4b1xNLTvY7FYQB1wGK5a4x7TTokDrPYQxDB2jmsdDYCzVbIMrAvUfcecRi
+  khyGZCdByiiCl4fKv77P12tTT+NfsvXkLt/AYCGwjOUyGKTQ01Z6eC09T27GayPH
+  QQvIkakyFgcJtzSyGzs8bzK5q9u7wQ12MNTjJoXzW69lqp0oNvDylu81EiSUb5S6
+  QzzPxZBiRB1sgtbt1gUbVI262ZDq1gR+HxPFmp+Cgt7ZLIJZAtesQvtcMzseXpfn
+  hpmm0Sw22KGhRAy/mqHBRhDl5HqS1SJp2Ko3lcnpXeFResp0HNlt8NSu13vhC08j
+  GUHU9MyIXbFOsnp3K3ADrAVjPWop8EZkmUR3MV/CUm00w2cZHCSGiXl1KMpiVKvk
+  Ywr1gd2ZME4QLSo+EXUtLxDUa/W3xnBS8dBOuMMz02FPWYr3PN8CAwEAAaN7MHkw
+  CQYDVR0TBAIwADALBgNVHQ8EBAMCBLAwHQYDVR0OBBYEFAFgmv0tYMZnItuPycSM
+  F5wykJEVMB8GA1UdEQQYMBaBFGJyb29rZUBhbGNoZW1pc3RzLmlvMB8GA1UdEgQY
+  MBaBFGJyb29rZUBhbGNoZW1pc3RzLmlvMA0GCSqGSIb3DQEBCwUAA4IBgQAX+EGY
+  9RLYGxF1VLZz+G1ACQc4uyrCB6kXwI06kzUa5dF9tPXqTX9ffnz3/W8ck2IQhKzu
+  MKO2FVijzbDWTsZeZGglS4E+4Jxpau1lU9HhOIcKolv6LeC6UdALTFudY+GLb8Xw
+  REXgaJkjzzhkUSILmEnRwEbY08dVSl7ZAaxVI679vfI2yapLlIwpbBgmQTiTvPr3
+  qyyLUno9flYEOv9fmGHunSrM+gE0/0niGTXa5GgXBXYGS2he4LQGgSBfGp/cTwMU
+  rDKJRcusZ12lNBeDfgqACz/BBJF8FLodgk6rGMRZz7+ZmjjHEmpG5bQpR6Q2BuWL
+  XMtYk/QzaWuhiR7pWjiF8jbdd7RO6or0ohq7iFkokz/5xrtQ/vPzU2RQ3Qc6YaKw
+  3n5C8/6Zh9DYTkpcwPSuIfAga6wf4nXc9m6JAw8AuMLaiWN/r/2s4zJsUHYERJEu
+  gZGm4JqtuSg8pYjPeIJxS960owq+SfuC+jxqmRA54BisFCv/0VOJi7tiJVY=
   -----END CERTIFICATE-----
-date: 2023-03-22 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.9
+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: []