refinements 12.8.0 → 12.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 81ecb80884f2fcc3c01f67b069fc4d8e46bf6c0dec1a03013a0f4183800c971e
-  data.tar.gz: 85ced417ccf67b5940b1441df1cacc2d9ca32812e4bc9f89d775e17574cce1e9
+  metadata.gz: 56d9d8ea056f8d22d211d5d9ad964b74e5fc86eb4be0b3476a1cd15c0ef74856
+  data.tar.gz: bd3d5e64e0dfd3ae296d81a6b96212390b223f79b91d14fd3af14eab2c2dd867
 SHA512:
-  metadata.gz: a9d24dfcb5491cda43127501056b1cbb74fa13286964bcfca60107e42ca2bb67c56e22e35fd8773f83e91c16122c97d2723ac6ca0fc1094c6bd746bee7c5bff6
-  data.tar.gz: c8bbde575d08783fbf64d303fac8cb8cc0b0215b7bdc8e532ce1180f8451bc12e02391c9e22300edaba464ee50a1d2b1eb31b4081e8a234350e174ddc8cc7c08
+  metadata.gz: 63f889fedadba076370027afce7f0e176bd7e840d6b470d99043033a39f79277a4aebe7b0573e8d6c367432c59e98cb77b26ee62b5148f420121b632d86f8dfb
+  data.tar.gz: 47712bdf7aff52e05671f7fed297bd06f54dfa1e554e529723c3ab932b2204d30630a25906b757769f314c213e004014fc887bcdfd5b6ac36edf1949bd16335d

data/README.adoc

@@ -20,6 +20,7 @@ Enhances the following objects:
 * IO
 * LogDevice
 * Logger
+* Module
 * Object
 * Pathname
 * String
@@ -87,6 +88,7 @@ require "refinements/hash"
 require "refinements/io"
 require "refinements/log_device"
 require "refinements/logger"
+require "refinements/module"
 require "refinements/object"
 require "refinements/pathname"
 require "refinements/string"
@@ -111,6 +113,7 @@ class Example
   using Refinements::IO
   using Refinements::LogDevice
   using Refinements::Logger
+  using Refinements::Module
   using Refinements::Object
   using Refinements::Pathname
   using Refinements::String
@@ -186,6 +189,8 @@ Removes given array or elements without mutating itself.
 
 ===== #filter_find
 
+⚠️ _This is deprecated and will be removed in Version 13.0.0._
+
 Answers the first element which evaluates to true from a filtered collection.
 
 [source,ruby]
@@ -635,7 +640,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 +655,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 +669,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 +750,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 +817,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 +845,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]
 ----
@@ -925,7 +974,8 @@ logger.reread  # ""
 
 Allows you to log _any_ message which is identical in behavior and functionality to the `Logger#unknown` method only this requires less typing and better matches the terminology used by the `#unknown` method.
 
-``` ruby
+[source,ruby]
+----
 logger = Logger.new STDOUT
 
 logger.any "Test."
@@ -933,7 +983,33 @@ logger.any "Test."
 
 logger.any { "Test." }
 A, [2000-01-10T09:00:00.330719 #44925]   ANY -- : Test.
-```
+----
+
+==== Module
+
+===== #pseudonym
+
+Allows you to set a temporary name for your anonymous `Module` (or `Class` since `Class` inherits from `Module`) with a better default than what `+#set_temporary_name+` provides.
+
+[source,ruby]
+----
+Module.new.pseudonym "demo"                       # demo-44600
+Module.new.pseudonym "demo", delimiter: "_"       # demo_60900
+Module.new.pseudonym "demo", nil                  # demo-
+Module.new.pseudonym "demo", nil, delimiter: nil  # demo
+----
+
+The same applies for anonymous classes since classes inherit from modules:
+
+[source,ruby]
+----
+Class.new.pseudonym "demo"                       # demo-44600 < Object
+Class.new.pseudonym "demo", delimiter: "_"       # demo_60900 < Object
+Class.new.pseudonym "demo", nil                  # demo- < Object
+Class.new.pseudonym "demo", nil, delimiter: nil  # demo < Object
+----
+
+💡 While convenient, if you find yourself nullifying the suffix and/or delimiter, you're better off using `+#set_temporary_name+`.
 
 ==== Object
 
@@ -1554,6 +1630,8 @@ io.to_str # "One, Two."
 
 ===== .with_positions
 
+⚠️ _This is deprecated and will be removed in Version 13.0.0._
+
 Answers a struct instance with given positional arguments regardless of
 whether the struct was constructed with positional or keyword arguments.
 

data/lib/refinements/array.rb

@@ -19,7 +19,12 @@ module Refinements
 
       def excluding(*elements) = self - elements.flatten
 
-      def filter_find(&block) = block ? lazy.map(&block).find(&:itself) : lazy
+      def filter_find(&)
+        warn "`#{self.class}##{__method__}` is deprecated and will be removed in Version 13.0.0.",
+             category: :deprecated
+
+        block_given? ? lazy.map(&).find(&:itself) : lazy
+      end
 
       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/module.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Refinements
+  # Provides additional enhancements to the Symbol primitive.
+  module Module
+    refine ::Module do
+      def pseudonym prefix, suffix = object_id, delimiter: "-"
+        set_temporary_name "#{prefix}#{delimiter}#{suffix}"
+      end
+    end
+  end
+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/struct.rb

@@ -6,7 +6,12 @@ module Refinements
   # Provides additional enhancements to the Struct primitive.
   module Struct
     refine ::Struct.singleton_class do
-      def with_positions(*values) = keyword_init? ? new(**members.zip(values).to_h) : new(*values)
+      def with_positions(*values)
+        warn "`#{self.class}##{__method__}` is deprecated and will be removed in Version 13.0.0.",
+             category: :deprecated
+
+        keyword_init? ? new(**members.zip(values).to_h) : new(*values)
+      end
     end
 
     refine ::Struct do

data/lib/refinements.rb

@@ -8,6 +8,7 @@ require "refinements/hash"
 require "refinements/io"
 require "refinements/log_device"
 require "refinements/logger"
+require "refinements/module"
 require "refinements/object"
 require "refinements/pathname"
 require "refinements/string"

data/refinements.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "refinements"
-  spec.version = "12.8.0"
+  spec.version = "12.10.0"
   spec.authors = ["Brooke Kuhlmann"]
   spec.email = ["brooke@alchemists.io"]
   spec.homepage = "https://alchemists.io/projects/refinements"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: refinements
 version: !ruby/object:Gem::Version
-  version: 12.8.0
+  version: 12.10.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -35,7 +35,7 @@ cert_chain:
   3n5C8/6Zh9DYTkpcwPSuIfAga6wf4nXc9m6JAw8AuMLaiWN/r/2s4zJsUHYERJEu
   gZGm4JqtuSg8pYjPeIJxS960owq+SfuC+jxqmRA54BisFCv/0VOJi7tiJVY=
   -----END CERTIFICATE-----
-date: 2024-09-01 00:00:00.000000000 Z
+date: 2024-10-22 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -57,6 +57,7 @@ files:
 - lib/refinements/io.rb
 - lib/refinements/log_device.rb
 - lib/refinements/logger.rb
+- lib/refinements/module.rb
 - lib/refinements/object.rb
 - lib/refinements/pathname.rb
 - lib/refinements/shared/diff.rb
@@ -96,7 +97,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.18
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: A collection of core object refinements.