refinements 12.7.1 → 12.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 81242c43b3aad6b04319273228ac9a83e1dde30677f95bafe56629552e9a2aff
-  data.tar.gz: 350fbedab3dba89b6506b73b1ee1eb029d0fab302d347caddccfb53af865bc8b
+  metadata.gz: 229ada32a4378800013462184db88be59d33109cbbd63c8c6378add52fc7b321
+  data.tar.gz: 4f0291390f858b45e2066dc9eac5e3f06ceef5c9e1051160aa7c625e734c78c4
 SHA512:
-  metadata.gz: 3b52ff2d707ddca982386b1f65d49f21a080faa3f5985adead49c3c15c3bed2ebc4c5587c0bedbbe2fcc3a0b80e97946c5b895fb365d39eeeabf02922b0388a0
-  data.tar.gz: f7eaf17a912a7ddfdf05117da9a13f0bd699aae9238f6df8e8dcc26f963f431781710a20f39775162547c44fe847d04edd6304da3bbaea90412e74db35f2c72f
+  metadata.gz: dbe61e5483ff24ffe0d9852e3f1c34e613f53a48f8a96cb15b862bf2528c448df71e9357d2910068b7e41275a916a9169f99e6b5b67c355df73eaf3e6ac2d124
+  data.tar.gz: 3f77b617a157b3d9be6735a08a9340ddd945642107d5e2728e384f6496197a44e180cfcce8c5738ec5ea509df883fcc5ca3b1261ffaddeaedbcfe0764987d9d0

data/README.adoc

@@ -635,7 +635,7 @@ Any object that _is not_ the same type will have a `nil` value as shown in the l
 
 Fetches value for exiting or missing key. Behavior is identical to `#fetch` except when the value of
 the key is `nil` you'll get the default value instead. This eliminates the need for using an _or_
-expression `example.fetch(:desired_key) || "default_value"`.
+expression: `example.fetch(:desired_key) || "default_value"`.
 
 [source,ruby]
 ----
@@ -650,8 +650,7 @@ expression `example.fetch(:desired_key) || "default_value"`.
 
 ===== #flatten_keys
 
-Flattens nested keys as top-level keys without mutating itself. Does not handle nested arrays,
-though.
+Flattens nested keys as top-level keys without mutating itself. Keys are converted to symbols. Does not handle nested arrays.
 
 [source,ruby]
 ----
@@ -665,8 +664,7 @@ example                                         # {a: {b: 1}}
 
 ===== #flatten_keys!
 
-Flattens nested keys as top-level keys while mutating itself. Does not handle nested arrays,
-though.
+Flattens nested keys as top-level keys while mutating itself. Keys are converted to symbols. Does not handle nested arrays.
 
 [source,ruby]
 ----
@@ -747,6 +745,52 @@ example.symbolize_keys!  # {a: 1, b: 2}
 example                  # {a: 1, b: 2}
 ----
 
+===== #transform_value
+
+Transforms a value for the specified key _only_ if the key exists and a block is given. Otherwise, the original hash is answered. Does not mutate itself.
+
+[source,ruby]
+----
+example = {a: 1, b: 2}
+
+example.transform_value :b                          # {a: 1, b: 2}
+example.transform_value(:b) { 20 }                  # {a: 1, b: 20}
+example.transform_value(:b) { |value| value * 10 }  # {a: 1, b: 20}
+example.transform_value :c                          # {a: 1, b: 2}
+example.transform_value(:c) { :bogus }              # {a: 1, b: 2}
+----
+
+The original object _is not_ mutated:
+
+[source,ruby]
+----
+example.transform_value(:b) { 20 }  # {a: 1, b: 20}
+example                             # {a: 1, b: 2}
+----
+
+===== #transform_value!
+
+Transforms a value for the specified key _only_ if the key exists and a block is given. Otherwise, the original hash is answered. Mutates itself.
+
+[source,ruby]
+----
+example = {a: 1, b: 2}
+
+example.transform_value! :b                          # {a: 1, b: 2}
+example.transform_value!(:b) { 20 }                  # {a: 1, b: 20}
+example.transform_value!(:b) { |value| value * 10 }  # {a: 1, b: 20}
+example.transform_value! :c                          # {a: 1, b: 2}
+example.transform_value!(:c) { :bogus }              # {a: 1, b: 2}
+----
+
+The original object _is_ mutated:
+
+[source,ruby]
+----
+example.transform_value!(:b) { 20 }  # {a: 1, b: 20}
+example                              # {a: 1, b: 20}
+----
+
 ===== #transform_with
 
 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:
@@ -768,7 +812,7 @@ example.transform_with bogus: -> value { value.tr "<>", "" }
 # {email: "<jd@example.com>"}
 ----
 
-The original object _will not_ be mutated:
+The original object _is not_ mutated:
 
 [source,ruby]
 ----
@@ -796,7 +840,7 @@ example.transform_with! bogus: -> value { value.tr "<>", "" }
 # {email: "<jd@example.com>"}
 ----
 
-The original object _will be_ mutated:
+The original object _is_ mutated:
 
 [source,ruby]
 ----
@@ -1524,6 +1568,32 @@ io.reread(buffer:)  # "This is a test."
 buffer              # "This is a test."
 ----
 
+===== #to_s
+
+Answers underlying string representation for _explicit_ conversion.
+
+[source,ruby]
+----
+io = StringIO.new
+io.write "One"
+io.write ", "
+io.write "Two."
+io.to_s # "One, Two."
+----
+
+===== #to_str
+
+Answers underlying string representation for _implicit_ conversion.
+
+[source,ruby]
+----
+io = StringIO.new
+io.write "One"
+io.write ", "
+io.write "Two."
+io.to_str # "One, Two."
+----
+
 ==== Struct
 
 ===== .with_positions
@@ -1730,6 +1800,8 @@ bin/rake
 
 == link:https://alchemists.io/policies/contributions[Contributions]
 
+== link:https://alchemists.io/policies/developer_certificate_of_origin[Developer Certificate of Origin]
+
 == link:https://alchemists.io/projects/refinements/versions[Versions]
 
 == link:https://alchemists.io/community[Community]

data/lib/refinements/array.rb

@@ -19,7 +19,7 @@ module Refinements
 
       def excluding(*elements) = self - elements.flatten
 
-      def filter_find(&block) = block ? lazy.map(&block).find(&:itself) : lazy
+      def filter_find(&) = block_given? ? lazy.map(&).find(&:itself) : lazy
 
       def including(*elements) = self + elements.flatten
 

data/lib/refinements/hash.rb

@@ -80,9 +80,15 @@ module Refinements
 
       def symbolize_keys! = transform_keys!(&:to_sym)
 
-      def transform_with(operations) = dup.transform_with! operations
+      def transform_value(key, &) = dup.transform_value!(key, &)
 
-      def transform_with! operations
+      def transform_value! key
+        block_given? && key?(key) ? merge!(key => yield(self[key])) : self
+      end
+
+      def transform_with(**) = dup.transform_with!(**)
+
+      def transform_with!(**operations)
         operations.each { |key, function| self[key] = function.call self[key] if key? key }
         self
       end

data/lib/refinements/pathname.rb

@@ -53,14 +53,14 @@ module Refinements
       def delete_suffix(pattern) = parent.join %(#{name.sub(/#{pattern}\z/, "")}#{extname})
 
       def directories pattern = "*", flag: File::FNM_SYSCASE
-        glob(pattern, flag).select(&:directory?).sort
+        glob(pattern, flag).select(&:directory?)
       end
 
       def empty = file? ? (truncate(0) and self) : remove_tree.make_dir
 
       def extensions = basename.to_s.split(/(?=\.)+/).tap(&:shift)
 
-      def files(pattern = "*", flag: File::FNM_SYSCASE) = glob(pattern, flag).select(&:file?).sort
+      def files(pattern = "*", flag: File::FNM_SYSCASE) = glob(pattern, flag).select(&:file?)
 
       def gsub(pattern, replacement) = self.class.new(to_s.gsub(pattern, replacement))
 

data/lib/refinements/string_io.rb

@@ -8,6 +8,9 @@ module Refinements
   module StringIO
     refine ::StringIO do
       import_methods Shared::Reread
+
+      alias_method :to_s, :string
+      alias_method :to_str, :string
     end
   end
 end

data/refinements.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "refinements"
-  spec.version = "12.7.1"
+  spec.version = "12.9.0"
   spec.authors = ["Brooke Kuhlmann"]
   spec.email = ["brooke@alchemists.io"]
   spec.homepage = "https://alchemists.io/projects/refinements"
@@ -12,7 +12,7 @@ Gem::Specification.new do |spec|
   spec.metadata = {
     "bug_tracker_uri" => "https://github.com/bkuhlmann/refinements/issues",
     "changelog_uri" => "https://alchemists.io/projects/refinements/versions",
-    "documentation_uri" => "https://alchemists.io/projects/refinements",
+    "homepage_uri" => "https://alchemists.io/projects/refinements",
     "funding_uri" => "https://github.com/sponsors/bkuhlmann",
     "label" => "Refinements",
     "rubygems_mfa_required" => "true",
@@ -22,7 +22,7 @@ Gem::Specification.new do |spec|
   spec.signing_key = Gem.default_key_path
   spec.cert_chain = [Gem.default_cert_path]
 
-  spec.required_ruby_version = "~> 3.3"
+  spec.required_ruby_version = ">= 3.3", "<= 3.4"
 
   spec.files = Dir["*.gemspec", "lib/**/*"]
   spec.extra_rdoc_files = Dir["README*", "LICENSE*"]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: refinements
 version: !ruby/object:Gem::Version
-  version: 12.7.1
+  version: 12.9.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -35,7 +35,7 @@ cert_chain:
   3n5C8/6Zh9DYTkpcwPSuIfAga6wf4nXc9m6JAw8AuMLaiWN/r/2s4zJsUHYERJEu
   gZGm4JqtuSg8pYjPeIJxS960owq+SfuC+jxqmRA54BisFCv/0VOJi7tiJVY=
   -----END CERTIFICATE-----
-date: 2024-08-03 00:00:00.000000000 Z
+date: 2024-10-01 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -73,7 +73,7 @@ licenses:
 metadata:
   bug_tracker_uri: https://github.com/bkuhlmann/refinements/issues
   changelog_uri: https://alchemists.io/projects/refinements/versions
-  documentation_uri: https://alchemists.io/projects/refinements
+  homepage_uri: https://alchemists.io/projects/refinements
   funding_uri: https://github.com/sponsors/bkuhlmann
   label: Refinements
   rubygems_mfa_required: 'true'
@@ -84,16 +84,19 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - "~>"
+  - - ">="
     - !ruby/object:Gem::Version
       version: '3.3'
+  - - "<="
+    - !ruby/object:Gem::Version
+      version: '3.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.17
+rubygems_version: 3.5.20
 signing_key:
 specification_version: 4
 summary: A collection of core object refinements.