refinements 8.2.1 → 8.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3357c002920480a640ec080da0e8744f04a0883fa5ec54b75a88b77f7d2101d6
-  data.tar.gz: f7bd7990e5f362ec9b08e06f42beca263bff1c78be5a68d834cf7dc4fe58e961
+  metadata.gz: 91c5c0e066eac0f4f01a1b28a73f8aa122cb51725ff510fe69466db4f2cd4dac
+  data.tar.gz: fc7b29eb6507fe08f2ebedd9a0b596c2bf70b7b9cd48a3b9de12cdae82613928
 SHA512:
-  metadata.gz: 968fc32529ba33a2833b814d722e38e0a5caffcfc3eba154528838a75469a0701847e3a9419d395d632a4c47cf52d927420e95558b90e0cb1b0868066ee99cd9
-  data.tar.gz: 3839e9d117a58251fd9304ad628a76aab0f22f7210542633e2e2fdc13abe38b38c25a126c111430f0c454bf29b5cc6c0b2a94d9473ed6caa59396dedeca8c2ba
+  metadata.gz: b9268d53d65140f5456f6c26521e7f55254480b58cfb30a73d9106aecb7a30977a02d03e8e37d6563904419a1a26d7dfec68f0f64a25f82baf294e817c01ac48
+  data.tar.gz: b564b642883464ed667be47ecef73be99ef48665d1f2be8f34ae5ec48b852c6b9a07ee3c4b0c542154a538f54ceaed4e1eca9d528841150469d2c8a5957b6c3e

checksums.yaml.gz.sig

@@ -1,2 +1 @@
-Vm�T7�:�UlVCȡ�]��0*���8�Omr�;��V�HR�Y'������ma͒X����O
1���KW%��2U����0$�ٗ>[.T,F�@랉\��[&2ѯ�ƞ��r�X�˅(�O#7d�r#��g��0aJ��1�yK1�bbV��N���sG��
-m��
+`O+�b}�_2^����'�}��q8Y��
�E:[(
�^UMO�*@�z՚�߈ϡ	�>�=�cc��A�t7�Y����R�	�*�5��)yr�
R���.���o(ꕚѝY���8�O�<h&��fy
NT+f�~_C�lX��x�9K���V<|�@'�NC�W���|�v,����&�	X-d���,Tf�Q�FD5�r�

data/README.adoc

@@ -11,7 +11,9 @@ image::https://img.shields.io/badge/code_style-alchemists-brightgreen.svg[Alchem
 [link=https://circleci.com/gh/bkuhlmann/refinements]
 image::https://circleci.com/gh/bkuhlmann/refinements.svg?style=svg[Circle CI Status]
 
-A collection of refinements (enhancements) to primitive Ruby objects.
+Refinements is a collection of enhancements to primitive Ruby objects without needing to resort
+painful and hard to debug monkey patches. These refinements give you additional syntactic sugar to
+build clean and concise implementations all while using less code.
 
 toc::[]
 
@@ -105,13 +107,14 @@ The following sections demonstrate how each refinement enriches your objects wit
 
 ===== #compress
 
-Removes `nil` and empty values without mutating itself.
+Removes `nil` and empty objects without mutating itself.
 
 [source,ruby]
 ----
-example = ["An", nil, "", "Example"]
-example.compress  # => ["An", "Example"]
-example           # => ["An", nil, "", "Example"]
+object = Object.new
+example = [1, "blueberry", nil, "", [], {}, object]
+example.compress  # => [1, "blueberry", object]
+example           # => [1, "blueberry", nil, "", [], {}, object]
 ----
 
 ===== #compress!
@@ -120,9 +123,10 @@ Removes `nil` and empty values while mutating itself.
 
 [source,ruby]
 ----
-example = ["An", nil, "", "Example"]
-example.compress!  # => ["An", "Example"]
-example            # => ["An", "Example"]
+object = Object.new
+example = [1, "blueberry", nil, "", [], {}, object]
+example.compress  # => [1, "blueberry", object]
+example           # => [1, "blueberry", object]
 ----
 
 ===== #excluding
@@ -249,6 +253,22 @@ Allows one to inspect a big decimal with numeric representation.
 BigDecimal.new("5.0E-10").inspect # => "#<BigDecimal:3fd3d458fe84 0.0000000005>"
 ----
 
+==== Class
+
+===== #descendants
+
+Answers descendants of a class.
+
+[source,ruby]
+----
+a = Class.new
+b = Class.new a
+c = Class.new a
+
+a.descendants          # => [b, c]
+Class.new.descendants  # => []
+----
+
 ==== DateTime
 
 ===== .utc
@@ -286,6 +306,30 @@ example = Hash.with_default []
 example[:b]  # => []
 ----
 
+===== #compress
+
+Removes `nil` and empty objects without mutating itself.
+
+[source,ruby]
+----
+object = Object.new
+example = {a: 1, b: "blueberry", c: nil, d: "", e: [], f: {}, g: object}
+example.compress  # => {a: 1, b: "blueberry", g: object}
+example           # => {a: 1, b: "blueberry", c: nil, d: "", e: [], f: {}, g: object}
+----
+
+===== #compress!
+
+Removes `nil` and empty objects while mutating itself.
+
+[source,ruby]
+----
+object = Object.new
+example = {a: 1, b: "blueberry", c: nil, d: "", e: [], f: {}, g: object}
+example.compress!  # => {a: 1, b: "blueberry", g: object}
+example            # => {a: 1, b: "blueberry", g: object}
+----
+
 ===== #deep_merge
 
 Merges deeply nested hashes together without mutating itself.
@@ -352,6 +396,22 @@ example.deep_symbolize_keys!  # => {a: {b: 1}}
 example                       # => {a: {b: 1}}
 ----
 
+===== #fetch_value
+
+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"`.
+
+[source,ruby]
+----
+{a: "test"}.fetch_value :a, "default"  # => "test"
+{a: "test"}.fetch_value :a             # => "test"
+{a: nil}.fetch_value :a, "default"      # => "default"
+{}.fetch_value(:a) { "default" }        # => "default"
+{}.fetch_value :a                       # => KeyError
+{a: "test"}.fetch_value                 # => ArgumentError
+----
+
 ===== #flatten_keys
 
 Flattens nested keys as top-level keys without mutating itself. Does not handle nested arrays,
@@ -535,7 +595,7 @@ Wraps `Dir.mktmpdir` with the following behavior (see
 link:https://rubyapi.org/o/Dir.mktmpdir#method-c-mktmpdir[Dir.mktmpdir] for details):
 
 * *Without Block* - Answers a newly created Pathname instance which is not automatically cleaned up.
-* *With Block*  Yields a Pathname instance, answers result of given block, and automatidally cleans
+* *With Block*  Yields a Pathname instance, answers result of given block, and automatically cleans
   up temporary directory after block exits.
 
 The following examples use truncated temporary directories for illustration purposes only. In
@@ -614,6 +674,30 @@ Copies file from current location to new location while answering itself so it c
 Pathname("input.txt").copy Pathname("output.txt")  # => Pathname("input.txt")
 ----
 
+===== #deep_touch
+
+Has all of the same functionality as the `#touch` method while being able to create ancestor
+directories no matter how deeply nested the file might be.
+
+[source,ruby]
+----
+Pathname("a/b/c/d.txt").touch               # => Pathname("a/b/c/d.txt")
+Pathname("a/b/c/d.txt").touch Time.now - 1  # => Pathname("a/b/c/d.txt")
+----
+
+===== #delete
+
+Deletes file or directory and answers itself so it can be chained.
+
+[source,ruby]
+----
+# When path exists.
+Pathname("/example.txt").touch.delete  # => Pathname("/example")
+
+# When path doesn't exist.
+Pathname("/example.txt").delete        # => Errno::ENOENT
+----
+
 ===== #directories
 
 Answers all directories or filtered directories for current path.
@@ -625,6 +709,20 @@ Pathname("/example").directories "a*"                      # => [Pathname("a")]
 Pathname("/example").directories flag: File::FNM_DOTMATCH  # => [Pathname(".."), Pathname(".")]
 ----
 
+===== #empty
+
+Empties a directory of children (i.e. folders, nested folders, or files) or clears an existing file
+of contents. If a directory or file doesn't exist, it will be created.
+
+[source,ruby]
+----
+directory = Pathname("test").make_path
+file = directory.join("test.txt").write("example")
+
+file.empty.read           # => ""
+directory.empty.children  # => []
+----
+
 ===== #extensions
 
 Answers file extensions as an array.
@@ -755,10 +853,13 @@ Pathname("/test.txt").rewrite { |body| body.sub "[token]", "example" }  # => Pat
 
 ===== #touch
 
-Updates access and modification times for path. Defaults to current time.
+Updates access and modification times for an existing path by defaulting to current time. When path
+doesn't exist, it will be created as a file.
 
 [source,ruby]
 ----
+Pathname("example").touch                   # => Pathname("example")
+Pathname("example").touch Time.now - 1      # => Pathname("example")
 Pathname("example.txt").touch               # => Pathname("example.txt")
 Pathname("example.txt").touch Time.now - 1  # => Pathname("example.txt")
 ----
@@ -837,6 +938,46 @@ Answers last character of a string or last set of characters if given a number.
 "instant".last 3  # => "ant"
 ----
 
+===== #pluralize
+
+Answers plural form of self when given a suffix to add. The plural form of the word can be
+dynamically calculated when given a count and a replacement pattern (i.e. string or regular
+expression) can be supplied for further specificity. Usage is based on
+link:https://en.wikipedia.org/wiki/English_plurals[plurals in English] which may or may not work
+well in other languages.
+
+[source,ruby]
+----
+"apple".pluralize "s"                      # => apples
+"apple".pluralize "s", count: 0            # => apples
+"apple".pluralize "s", count: 1            # => apple
+"apple".pluralize "s", count: -1           # => apple
+"apple".pluralize "s", count: 2            # => apples
+"apple".pluralize "s", count: -2           # => apples
+"cactus".pluralize "i", replace: "us"      # => cacti
+"cul-de-sac".pluralize "ls", replace: "l"  # => culs-de-sac
+----
+
+===== #singularize
+
+Answers singular form of self when given a suffix to remove (can be a string or a regular
+expression). The singular form of the word can be dynamically calculated when given a count and a
+replacement string can be supplied for further specificity. Usage is based on
+link:https://en.wikipedia.org/wiki/English_plurals[plurals in English] which may or may not work
+well in other languages.
+
+[source,ruby]
+----
+"apples".singularize "s"                      # => apple
+"apples".singularize "s", count: 0            # => apples
+"apples".singularize "s", count: 1            # => apple
+"apples".singularize "s", count: -1           # => apple
+"apples".singularize "s", count: 2            # => apples
+"apples".singularize "s", count: -2           # => apples
+"cacti".singularize "i", replace: "us"        # => cactus
+"culs-de-sac".singularize "ls", replace: "l"  # => cul-de-sac
+----
+
 ===== #snakecase
 
 Answers a snakecased string.
@@ -1031,6 +1172,24 @@ example.revalue!                                                   # => #<struct
 example                                                            # => #<struct a=1, b=2, c=3>
 ----
 
+==== Symbol
+
+===== #call
+
+Enhances symbol-to-proc by allowing you to send additional arguments and/or a block. This only works
+with public methods in order to not break encapsulation.
+
+[source,ruby]
+----
+%w[clue crow cow].map(&:tr.call("c", "b"))                              # => ["blue", "brow", "bow"]
+[%w[a b c], %w[c a b]].map(&:index.call { |element| element == "b" })   # => [1, 2]
+%w[1.outside 2.inside].map(&:sub.call(/\./) { |bullet| bullet + " " })  # => ["1. outside", "2. inside"]
+[1, 2, 3].map(&:to_s.call)                                              # => ["1", "2", "3"]
+----
+
+⚠️ Use of `#call` without any arguments or block should be avoided in order to not incur extra
+processing costs since the original symbol-to-proc call can used instead.
+
 == Development
 
 To contribute, run:

data/lib/refinements/arrays.rb

@@ -1,11 +1,15 @@
 # frozen_string_literal: true
 
 module Refinements
+  # Provides additional enhancements to the Array primitive.
   module Arrays
     refine Array do
-      def compress = compact.reject(&:empty?)
+      def compress = dup.compress!
 
-      def compress! = replace(compress)
+      def compress!
+        compact!
+        delete_if { |element| element.respond_to?(:empty?) && element.empty? }
+      end
 
       def excluding(*elements) = self - elements.flatten
 

data/lib/refinements/big_decimals.rb

@@ -3,6 +3,7 @@
 require "bigdecimal"
 
 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"))

data/lib/refinements/classes.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Refinements
+  # Provides additional enhancements to Class objects.
+  module Classes
+    refine Class do
+      def descendants
+        ObjectSpace.each_object(singleton_class)
+                   .reject { |klass| klass.singleton_class? || klass == self }
+      end
+    end
+  end
+end

data/lib/refinements/date_times.rb

@@ -3,6 +3,7 @@
 require "date"
 
 module Refinements
+  # Provides additional enhancements to the DateTime primitive.
   module DateTimes
     refine DateTime.singleton_class do
       def utc = now.new_offset(0)

data/lib/refinements/hashes.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Refinements
+  # Provides additional enhancements to the Hash primitive.
   module Hashes
     refine Hash.singleton_class do
       def infinite
@@ -11,6 +12,14 @@ module Refinements
     end
 
     refine Hash do
+      def compress = dup.compress!
+
+      def compress!
+        return self if empty?
+
+        compact!.delete_if { |_key, value| value.respond_to?(:empty?) && value.empty? }
+      end
+
       def deep_merge other
         clazz = self.class
 
@@ -33,6 +42,10 @@ module Refinements
 
       def deep_symbolize_keys! = replace(deep_symbolize_keys)
 
+      def fetch_value key, *default_value, &block
+        fetch(key, *default_value, &block) || default_value.first
+      end
+
       # :reek:TooManyStatements
       def flatten_keys prefix: nil, delimiter: "_", cast: :to_sym
         fail StandardError, "Unknown cast: #{cast}." unless %i[to_sym to_s].include? cast
@@ -62,13 +75,13 @@ module Refinements
         end
       end
 
-      def stringify_keys = reduce({}) { |hash, (key, value)| hash.merge key.to_s => value }
+      def stringify_keys = transform_keys(&:to_s)
 
-      def stringify_keys! = replace(stringify_keys)
+      def stringify_keys! = transform_keys!(&:to_s)
 
-      def symbolize_keys = reduce({}) { |hash, (key, value)| hash.merge key.to_sym => value }
+      def symbolize_keys = transform_keys(&:to_sym)
 
-      def symbolize_keys! = replace(symbolize_keys)
+      def symbolize_keys! = transform_keys!(&:to_sym)
 
       def use &block
         return [] unless block

data/lib/refinements/identity.rb

@@ -5,7 +5,7 @@ module Refinements
   module Identity
     NAME = "refinements"
     LABEL = "Refinements"
-    VERSION = "8.2.1"
-    VERSION_LABEL = "#{LABEL} #{VERSION}"
+    VERSION = "8.5.0"
+    VERSION_LABEL = "#{LABEL} #{VERSION}".freeze
   end
 end

data/lib/refinements/ios.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Refinements
+  # Provides additional enhancements to the IO primitive.
   module IOs
     refine IO.singleton_class do
       def void

data/lib/refinements/pathnames.rb

@@ -3,9 +3,9 @@
 require "pathname"
 
 module Refinements
+  # Provides additional enhancements to the Pathname primitive.
   module Pathnames
     refine Kernel do
-      # :reek:UncommunicativeMethodName
       def Pathname object
         return super(String(object)) unless object
 
@@ -24,7 +24,7 @@ module Refinements
         new(root).files(pattern).each { |path| require path.to_s }
       end
 
-      def root = new("/")
+      def root = new(File::SEPARATOR)
     end
 
     refine Pathname do
@@ -38,10 +38,16 @@ module Refinements
         self
       end
 
+      def deep_touch(...) = make_ancestors.touch(...)
+
+      def delete = super && self
+
       def directories pattern = "*", flag: File::FNM_SYSCASE
         glob(pattern, flag).select(&:directory?).sort
       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

data/lib/refinements/string_ios.rb

@@ -3,6 +3,7 @@
 require "stringio"
 
 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)

data/lib/refinements/strings.rb

@@ -1,11 +1,12 @@
 # frozen_string_literal: true
 
 module Refinements
+  # Provides additional enhancements to the String primitive.
   module Strings
     DELIMITERS = %r([a-z][A-Z]|\s*-\s*|\s*/\s*|\s*:+\s*|\s*_\s*|\s+)
 
     refine String do
-      def blank? = match?(/\A\s*\z/)
+      def blank? = empty? || match?(/\A[[:space:]]*\z/)
 
       def camelcase
         return up unless match? DELIMITERS
@@ -35,7 +36,7 @@ module Refinements
       def indent multiplier = 1, padding: "  "
         return self if multiplier.negative?
 
-        padding * multiplier + self
+        (padding * multiplier) + self
       end
 
       def last number = 0
@@ -49,6 +50,10 @@ module Refinements
         self[(min + 1)..]
       end
 
+      def pluralize(suffix, replace: /$/, count: 0) = count.abs == 1 ? self : sub(replace, suffix)
+
+      def singularize(suffix, replace: "", count: 1) = count.abs == 1 ? sub(suffix, replace) : self
+
       def snakecase
         return downcase unless match? DELIMITERS
 

data/lib/refinements/structs.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Refinements
+  # Provides additional enhancements to the Struct primitive.
   module Structs
     refine Struct.singleton_class do
       def keyworded? = inspect.include?("keyword_init: true")

data/lib/refinements/symbols.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Refinements
+  # Provides additional enhancements to the Symbol primitive.
+  module Symbols
+    refine Symbol do
+      def call *arguments, &block
+        proc { |receiver| receiver.public_send self, *arguments, &block }
+      end
+    end
+  end
+end

data/lib/refinements.rb

@@ -2,6 +2,7 @@
 
 require "refinements/identity"
 require "refinements/arrays"
+require "refinements/classes"
 require "refinements/big_decimals"
 require "refinements/date_times"
 require "refinements/hashes"
@@ -10,3 +11,4 @@ require "refinements/pathnames"
 require "refinements/strings"
 require "refinements/string_ios"
 require "refinements/structs"
+require "refinements/symbols"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: refinements
 version: !ruby/object:Gem::Version
-  version: 8.2.1
+  version: 8.5.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -28,7 +28,7 @@ cert_chain:
   lkHilIrX69jq8wMPpBhlaw2mRmeSL50Wv5u6xVBvOHhXFSP1crXM95vfLhLyRYod
   W2A=
   -----END CERTIFICATE-----
-date: 2021-08-08 00:00:00.000000000 Z
+date: 2021-10-16 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -44,6 +44,7 @@ files:
 - lib/refinements.rb
 - lib/refinements/arrays.rb
 - lib/refinements/big_decimals.rb
+- lib/refinements/classes.rb
 - lib/refinements/date_times.rb
 - lib/refinements/hashes.rb
 - lib/refinements/identity.rb
@@ -52,6 +53,7 @@ files:
 - lib/refinements/string_ios.rb
 - lib/refinements/strings.rb
 - lib/refinements/structs.rb
+- lib/refinements/symbols.rb
 homepage: https://www.alchemists.io/projects/refinements
 licenses:
 - Apache-2.0
@@ -75,7 +77,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.25
+rubygems_version: 3.2.29
 signing_key:
 specification_version: 4
 summary: A collection of refinements to core Ruby objects.