refinements 8.4.1 → 8.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b633f00ddb573cba22fcf647e293a7f4544fecc82ad3869d9c3528d0bd8e1aa
-  data.tar.gz: 00ef7df42687d801237b8b27563aaa028e19b75a4764c32a3c2220f58186dbe0
+  metadata.gz: 91c5c0e066eac0f4f01a1b28a73f8aa122cb51725ff510fe69466db4f2cd4dac
+  data.tar.gz: fc7b29eb6507fe08f2ebedd9a0b596c2bf70b7b9cd48a3b9de12cdae82613928
 SHA512:
-  metadata.gz: edb16cbce2ab22b6b95303751e87f09037dd570b38ffb7e6620d91a3e8e7bc9293fdcf4a4378e091847b12ccb80bd5d57c5bab22b0d930507327e54c29c9c855
-  data.tar.gz: 5767133f63df1a255b0ac9d6f9ff1ab6c8dfc73d237968a3cea225e3d2be4964fd8aa2298c7047cb81a8594ba6a9f4a676738d485519b696efeee20ddfe4b51d
+  metadata.gz: b9268d53d65140f5456f6c26521e7f55254480b58cfb30a73d9106aecb7a30977a02d03e8e37d6563904419a1a26d7dfec68f0f64a25f82baf294e817c01ac48
+  data.tar.gz: b564b642883464ed667be47ecef73be99ef48665d1f2be8f34ae5ec48b852c6b9a07ee3c4b0c542154a538f54ceaed4e1eca9d528841150469d2c8a5957b6c3e

data/README.adoc

@@ -253,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
@@ -380,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,
@@ -642,6 +674,17 @@ 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.
@@ -666,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.
@@ -796,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")
 ----
@@ -878,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.
@@ -1072,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/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/hashes.rb

@@ -42,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

data/lib/refinements/identity.rb

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

data/lib/refinements/pathnames.rb

@@ -38,12 +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/strings.rb

@@ -50,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/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.4.1
+  version: 8.5.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -28,7 +28,7 @@ cert_chain:
   lkHilIrX69jq8wMPpBhlaw2mRmeSL50Wv5u6xVBvOHhXFSP1crXM95vfLhLyRYod
   W2A=
   -----END CERTIFICATE-----
-date: 2021-10-03 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.28
+rubygems_version: 3.2.29
 signing_key:
 specification_version: 4
 summary: A collection of refinements to core Ruby objects.