refinements 9.4.0 → 9.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48645ddfcd7e2ab3a7930401d2161dd259de6bf89ac2f5dbdf8f32015a9c9ed2
-  data.tar.gz: 8788e3eef62a5856f9136b38b6b76fe9d4c5a8db56b39394f8021bb6ea1db36d
+  metadata.gz: bfcbba638db46745a2a7bed58489bea5a2942fb8d414d6803696ee78d12b8ae2
+  data.tar.gz: bf5d97f24387a1b46c90b2ebce6e20a66a8ef7f817b60f7029c58ef7d8897236
 SHA512:
-  metadata.gz: 51c14c8e25b187ae86630f6c8c017cae3f53f16a4a1a72a9cbdfd3d5e2e83fe1e1bb07b2eacfb4865e35c5bd32092021f4758fdc454be900f42477a8f1a5f190
-  data.tar.gz: 8b4a378f5bd2e1eec9a3ca9c1bf72c0a5e3773dbe3ece7bebf5ac4bf3be815bd35b25ddc918de5a51116e6d43c98d4b0e54b423beaa2e1532a48645f477337b5
+  metadata.gz: 72fc04e99a5e2cc9f6d7adbc2b7c9d461f6d3246249eb1615379d2f64f871f5066c27bdedc95bda42cd44e247e4c793514f6885e11a497ce70980763bb00cb32
+  data.tar.gz: 16be117393cd04565ca945c1812e25d63169f7cb5400f4fa11bfe1aac27cbe3061deeeac6fb0e160c2538cf1f274cd1998e7e296f7c9e6e3cde39a0c5a822307

data/README.adoc

@@ -21,6 +21,8 @@ Enhances the following objects:
 * DateTime
 * Hash
 * IO
+* LogDevice
+* Logger
 * Pathname
 * String
 * StringIO
@@ -73,6 +75,8 @@ require "refinements/strings"
 require "refinements/string_ios"
 require "refinements/structs"
 require "refinements/symbols"
+require "refinements/log_devices"
+require "refinements/loggers"
 ----
 
 === Using
@@ -93,6 +97,8 @@ class Example
   using Refinements::StringIOs
   using Refinements::Structs
   using Refinements::Symbols
+  using Refinements::LogDevices
+  using Refinements::Loggers
 end
 ----
 
@@ -102,6 +108,24 @@ The following sections demonstrate how each refinement enriches your objects wit
 
 ==== Array
 
+===== #combinatorial?
+
+Answers if an array is equal to another array when the elements are equal but in any order and/or subset.
+
+[source,ruby]
+----
+example = %w[a b c]
+
+example.combinatorial? %w[a b c]    # true
+example.combinatorial? %w[c a b]    # true
+example.combinatorial? %w[c]        # true
+example.combinatorial? %w[c b]      # true
+example.combinatorial? %w[x]        # false
+example.combinatorial? %w[z b c]    # false
+example.combinatorial? %w[a b c d]  # false
+example.combinatorial? []           # false
+----
+
 ===== #compress
 
 Removes `nil` and empty objects without mutating itself.
@@ -254,6 +278,45 @@ example.ring { |(before, current, after)| puts "#{before} #{current} #{after}" }
 # [2 3 1]
 ----
 
+===== #supplant
+
+Answers mutated array where first target element found is replaced by single or multiple elements.
+
+[source,ruby]
+----
+%i[a b a].supplant :a, :z       # [:z, :b, :a]
+%i[a b a].supplant :a, :z, :y   # [:z, :y, :b, :a]
+%i[a b a].supplant :a, %i[z y]  # [[:z, :y], :b, :a]
+----
+
+===== #supplant_if
+
+Answers mutated array where all target elements are replaced by single or multiple elements.
+
+⚠️ Be aware that this can be an expensive operation on large arrays.
+
+[source,ruby]
+----
+%i[a b a].supplant_if :a, :z       # [:z, :b, :z]
+%i[a b a].supplant_if :a, :z, :y   # [:z, :y, :b, :z, :y]
+%i[a b a].supplant_if :a, %i[z y]  # [[:z, :y], :b, [:z, :y]]
+----
+
+===== #to_sentence
+
+Answers a sentence using `", "` as the default delimiter and `"and"` as the default conjunction.
+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"
+----
+
 ==== Big Decimal
 
 ===== #inspect
@@ -581,6 +644,54 @@ io.squelch { io.write "Test" }  # "#<IO:fd 20>"
 io.reread                       # ""
 ----
 
+==== LogDevice
+
+===== #reread
+
+Answers previously written content by rewinding to beginning of device.
+
+[source,ruby]
+----
+# With File.
+device = Logger::LogDevice.new "test.log"
+device.write "Test."
+device.reread                                # "Test."
+
+# With StringIO.
+device = Logger::LogDevice.new StringIO.new
+device.write "Test."
+device.reread                                # "Test."
+
+# With STDOUT.
+device = Logger::LogDevice.new $stdout
+device.write "Test."
+device.reread                                # ""
+----
+
+==== Logger
+
+===== #reread
+
+Answers previously written content by rewinding to beginning of log.
+
+[source,ruby]
+----
+# With File.
+logger = Logger.new "test.log"
+logger.write "Test."
+logger.reread                     # "Test."
+
+# With StringIO.
+logger = Logger.new StringIO.new
+logger.write "Test."
+logger.reread                     # "Test."
+
+# With STDOUT.
+logger = Logger.new $stdout
+logger.write "Test."
+logger.reread                     # ""
+----
+
 ==== Pathname
 
 ===== Pathname

data/lib/refinements/arrays.rb

@@ -8,6 +8,8 @@ module Refinements
     refine Array do
       import_methods Shared::Enumerables::Many
 
+      def combinatorial?(other) = !other.empty? && size == union(other).size
+
       def compress = dup.compress!
 
       def compress!
@@ -32,6 +34,28 @@ module Refinements
       def pad(value, max: size) = dup.fill(value, size..(max - 1))
 
       def ring(&) = [last, *self, first].each_cons(3, &)
+
+      def supplant target, *replacements
+        index(target).then do |position|
+          delete_at position
+          insert position, *replacements
+        end
+
+        self
+      end
+
+      def supplant_if target, *replacements
+        each { |item| supplant target, *replacements if item == target }
+        self
+      end
+
+      def to_sentence delimiter: ", ", conjunction: "and"
+        case length
+          when (3..) then "#{self[..-2].join delimiter}#{delimiter}#{conjunction} #{last}"
+          when 2 then join " #{conjunction} "
+          else join
+        end
+      end
     end
   end
 end

data/lib/refinements/hashes.rb

@@ -21,7 +21,8 @@ module Refinements
       def compress!
         return self if empty?
 
-        compact!.delete_if { |_key, value| value.respond_to?(:empty?) && value.empty? }
+        compact!
+        delete_if { |_key, value| value.respond_to?(:empty?) && value.empty? }
       end
 
       def deep_merge other

data/lib/refinements/ios.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "refinements/shared/ios/reread"
+
 module Refinements
   # Provides additional enhancements to the IO primitive.
   module IOs
@@ -15,6 +17,8 @@ module Refinements
     end
 
     refine IO do
+      import_methods Shared::IOs::Reread
+
       def redirect other
         return self unless block_given?
 
@@ -24,8 +28,6 @@ module Refinements
         reopen backup
       end
 
-      def reread(length = nil, buffer: nil) = tap(&:rewind).read(length, buffer)
-
       def squelch(&) = self.class.void.then { |void| redirect(void, &) }
     end
   end

data/lib/refinements/log_devices.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "logger"
+require "refinements/string_ios"
+
+module Refinements
+  # Provides additional enhancements to a log device.
+  module LogDevices
+    using StringIOs
+
+    refine Logger::LogDevice do
+      def reread
+        case dev
+          when File then dev.class.new(dev).read
+          when StringIO then dev.reread
+          else ""
+        end
+      end
+    end
+  end
+end

data/lib/refinements/loggers.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "refinements/log_devices"
+
+module Refinements
+  # Provides additional enhancements to a logger.
+  module Loggers
+    using LogDevices
+
+    refine Logger do
+      def reread = @logdev.reread
+    end
+  end
+end

data/lib/refinements/shared/ios/reread.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Refinements
+  module Shared
+    module IOs
+      # Provides shared functionality for I/O object rewinding.
+      module Reread
+        def reread(length = nil, buffer: nil) = tap(&:rewind).read(length, buffer)
+      end
+    end
+  end
+end

data/lib/refinements/string_ios.rb

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
 
 require "stringio"
+require "refinements/shared/ios/reread"
 
 module Refinements
   # Provides additional enhancements to the StringIO primitive.
   module StringIOs
     refine StringIO do
-      def reread(length = nil, buffer: nil) = tap(&:rewind).read(length, buffer)
+      import_methods Shared::IOs::Reread
     end
   end
 end

data/lib/refinements.rb

@@ -10,3 +10,5 @@ require "refinements/strings"
 require "refinements/string_ios"
 require "refinements/structs"
 require "refinements/symbols"
+require "refinements/log_devices"
+require "refinements/loggers"

data/refinements.gemspec

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: refinements
 version: !ruby/object:Gem::Version
-  version: 9.4.0
+  version: 9.7.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -28,7 +28,7 @@ cert_chain:
   CxDe2+VuChj4I1nvIHdu+E6XoEVlanUPKmSg6nddhkKn2gC45Kyzh6FZqnzH/CRp
   RFE=
   -----END CERTIFICATE-----
-date: 2022-05-07 00:00:00.000000000 Z
+date: 2022-09-01 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -47,8 +47,11 @@ files:
 - lib/refinements/date_times.rb
 - lib/refinements/hashes.rb
 - lib/refinements/ios.rb
+- lib/refinements/log_devices.rb
+- lib/refinements/loggers.rb
 - lib/refinements/pathnames.rb
 - lib/refinements/shared/enumerables/many.rb
+- lib/refinements/shared/ios/reread.rb
 - lib/refinements/string_ios.rb
 - lib/refinements/strings.rb
 - lib/refinements/structs.rb
@@ -80,7 +83,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.13
+rubygems_version: 3.3.21
 signing_key:
 specification_version: 4
 summary: A collection of refinements to core Ruby objects.

metadata.gz.sig

@@ -1,4 +1,3 @@
-�B|�7�3��
��j�t5��|-w�Mp��������INxA�W)�R�J�@z���@����KN
-�9t�DC�����1|I��}{m�ƨb�B8
-ozsl��$/�����!p�#I���q��hF�qw��q��l��H����5f�L�E�P��y�N��=�R�w廔���A��B6����ȿ14��������#��
-��p���s=%�B)ע)��2,��uG�̛��,~k�L��>�����}?�[�8�
+;�����^�Ǐ"���˾�S���l��}:������q\�������k�����+���鰩�
+�7��I�
4������0�{�=���y�̳>&��
O�!w
+b����e�5pѨ�[PXw��76>�^n�V��٫��ejFE��&��ek���2��.���Vr�2�� v�M�?~�F�1����h-�!�P����Y�/�nqt*������?i�(�]?9<������,������<��u\?���{%�P�O