refinements 11.0.0 → 11.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 252744b620f3c79a0c38b635157f62fc9e48527701145e871de885c547b44b61
-  data.tar.gz: 411b88c5cf6b9b95c59c43055b8a2402c95d9954b612837fce70a106c4c4a5f1
+  metadata.gz: 0ec4e17de3e050923d08c34123d8e8f2cf7096e66b3cf035c5fec870470de049
+  data.tar.gz: 8d5d5449055c76a8cb4675acc8ccbd2f9e46b4eb9986e29b04e548847f6d69b3
 SHA512:
-  metadata.gz: 0c12fb201556e5949190657cd591b126115ba7efb9f14aec4aeb107455d7cd04676b0dd1cc05f84e9bdd8b7c61e2fbadbabe377b739ffd14a643c3d98d717068
-  data.tar.gz: db75e0359afed8603daba0bae481b8e839b9d9ede700ef22bbcde22116e2a75b221b5d56d0381500ccf992f73c11cb7a4555823c4294b131077972800a03f3c1
+  metadata.gz: fe21be9b51f2616eeb94664a85006332dc1b00395cee44540a2adf9b5a08397636e22d35ca4d786887f2d6bfb287bcbca6aee54e89383b71f4976f1433980001
+  data.tar.gz: 5bc27d6026ce8ce38fe522929b54328c67445a7ed89f44ba57759a216b2f098c5fd18696bea14c0ab4719d953b59c6173ebff1e218d2d35b9bcfb9ebfdee43e8

data/README.adoc

@@ -14,6 +14,7 @@ Enhances the following objects:
 
 * Array
 * BigDecimal
+* Data
 * DateTime
 * Hash
 * IO
@@ -78,6 +79,7 @@ gem "refinements", require: false
 ----
 require "refinements/arrays"
 require "refinements/big_decimals"
+require "refinements/data"
 require "refinements/date_times"
 require "refinements/hashes"
 require "refinements/ios"
@@ -100,6 +102,7 @@ refinement(s):
 class Example
   using Refinements::Arrays
   using Refinements::BigDecimals
+  using Refinements::Data
   using Refinements::DateTimes
   using Refinements::Hashes
   using Refinements::IOs
@@ -289,7 +292,7 @@ array = [{name: "a", label: "A"}, {name: "b", label: "B"}, {name: "c", label: "C
 array.pick :name          # "a"
 array.pick :name, :label  # ["a", "A"]
 array.pick                # nil
-[].pick(:test)            # nil
+[].pick(:other)           # nil
 ----
 
 ===== #pluck
@@ -303,7 +306,7 @@ array = [{name: "a", label: "A"}, {name: "b", label: "B"}, {name: "c", label: "C
 array.pluck :name          # ["a", "b", "c"]
 array.pluck :name, :label  # [["a", "A"], ["b", "B"], ["c", "C"]]
 array.pluck                # []
-[].pluck :test             # []
+[].pluck :other            # []
 ----
 
 ===== #replace_at
@@ -365,25 +368,25 @@ Useful when building documentation, answering human readable error messages, etc
 [source,ruby]
 ----
 [].to_sentence                                        # ""
-["test"].to_sentence                                  # "test"
+["demo"].to_sentence                                  # "demo"
 ["a", :b].to_sentence                                 # "a and b"
-[1, "a", :b, 2.0, /\w+/].map(&:inspect).to_sentence   # 1, "a", :b, 2.0, and /\w+/
+[1, "a", :b, 2.0, /\w+/].to_sentence                  # "1, a, b, 2.0, and (?-mix:\\w+)"
 %w[one two three].to_sentence                         # "one, two, and three"
 %w[eins zwei drei].to_sentence "und", delimiter: " "  # "eins zwei und drei"
 ----
 
 ===== #to_usage
 
-Builds upon and enhances `#to_sentence` further by answering a sentence which all elements are inspected -- where each element of the array is called with `#inspect` -- before turned into a sentence using `"and"` as the default conjunction and `", "` as the default delimiter. This is useful when providing detailed error messages _and_ you need to show the element types used.
+Builds upon and enhances `#to_sentence` further by answering a sentence which all elements are inspected -- where each element of the array is called with `#inspect` -- before turned into a sentence using `"and"` as the default conjunction and `", "` as the default delimiter. This is useful when providing detailed error messages _and_ you need to detail the types of element used.
 
 [source,ruby]
 ----
 [].to_usage                                        # ""
-["test"].to_usage                                  # "test"
-["a", :b].to_usage                                 # "a and b"
-[1, "a", :b, 2.0, /\w+/].map(&:inspect).to_usage   # 1, "a", :b, 2.0, and /\w+/
-%w[one two three].to_usage                         # "one, two, and three"
-%w[eins zwei drei].to_usage "und", delimiter: " "  # "eins zwei und drei"
+["demo"].to_usage                                  # "\"demo\""
+["a", :b].to_usage                                 # "\"a\" and :b"
+[1, "a", :b, 2.0, /\w+/].to_usage                  # "1, \"a\", :b, 2.0, and /\\w+/"
+%w[one two three].to_usage                         # "\"one\", \"two\", and \"three\""
+%w[eins zwei drei].to_usage "und", delimiter: " "  # "\"eins\" \"zwei\" und \"drei\""
 ----
 
 ==== Big Decimal
@@ -397,6 +400,28 @@ Allows one to inspect a big decimal with numeric representation.
 BigDecimal.new("5.0E-10").inspect  # "#<BigDecimal:3fd3d458fe84 0.0000000005>"
 ----
 
+==== Data
+
+===== #diff
+
+Allows you to obtain the differences between two objects.
+
+[source,ruby]
+----
+implementation = Data.define :a, :b, :c
+
+one = implementation.new a: 1, b: 2, c: 3
+two = implementation.new a: 3, b: 2, c: 1
+three = Data.define(:x, :y).new x: 1, y: 2
+
+one.diff one         # {}
+one.diff two         # {:a=>[1, 3], :c=>[3, 1]}
+one.diff three       # {:a=>[1, nil], :b=>[2, nil], :c=>[3, nil]}
+one.diff Object.new  # {:a=>[1, nil], :b=>[2, nil], :c=>[3, nil]}
+----
+
+Any object that _is not_ the same type will have a `nil` value as shown in the last two examples.
+
 ==== DateTime
 
 ===== .utc
@@ -532,6 +557,26 @@ example.deep_symbolize_keys!  # {a: {b: 1}}
 example                       # {a: {b: 1}}
 ----
 
+===== #diff
+
+Allows you to obtain the differences between two objects.
+
+[source,ruby]
+----
+one = {a: 1, b: 2, c: 3}
+two = {a: 3, b: 2, c: 1}
+three = {c: 3, b: 2, a: 1}
+four = Data.define(:x, :y).new x: 1, y: 2
+
+one.diff one         # {}
+one.diff two         # {:a=>[1, 3], :c=>[3, 1]}
+one.diff three       # {}
+one.diff four        # {:a=>[1, nil], :b=>[2, nil], :c=>[3, nil]}
+one.diff Object.new  # {:a=>[1, nil], :b=>[2, nil], :c=>[3, nil]}
+----
+
+Any object that _is not_ the same type will have a `nil` value as shown in the last two examples. Two hashes with the same keys but defined in different order behave as if they had the same key order.
+
 ===== #fetch_value
 
 Fetches value for exiting or missing key. Behavior is identical to `#fetch` except when the value of
@@ -540,12 +585,12 @@ expression `example.fetch(:desired_key) || "default_value"`.
 
 [source,ruby]
 ----
-{a: "test"}.fetch_value :a, "default"  # "test"
-{a: "test"}.fetch_value :a             # "test"
+{a: "demo"}.fetch_value :a, "default"  # "demo"
+{a: "demo"}.fetch_value :a             # "demo"
 {a: nil}.fetch_value :a, "default"     # "default"
 {}.fetch_value(:a) { "default" }       # "default"
 {}.fetch_value :a                      # KeyError
-{a: "test"}.fetch_value                # ArgumentError
+{a: "demo"}.fetch_value                # ArgumentError
 ----
 
 ===== #flatten_keys
@@ -555,7 +600,7 @@ though.
 
 [source,ruby]
 ----
-{a: {b: 1}}.flatten_keys prefix: :test          # {test_a_b: 1}
+{a: {b: 1}}.flatten_keys prefix: :demo          # {demo_a_b: 1}
 {a: {b: 1}}.flatten_keys delimiter: :|          # {:"a|b" => 1}
 
 example = {a: {b: 1}}
@@ -570,7 +615,7 @@ though.
 
 [source,ruby]
 ----
-{a: {b: 1}}.flatten_keys! prefix: :test          # {test_a_b: 1}
+{a: {b: 1}}.flatten_keys! prefix: :demo          # {demo_a_b: 1}
 {a: {b: 1}}.flatten_keys! delimiter: :|          # {:"a|b" => 1}
 
 example = {a: {b: 1}}
@@ -735,11 +780,11 @@ answered instead.
 
 [source,ruby]
 ----
-io = IO.new IO.sysopen(Pathname("test.txt").to_s, "w+")
+io = IO.new IO.sysopen(Pathname("demo.txt").to_s, "w+")
 other = IO.new IO.sysopen(Pathname("other.txt").to_s, "w+")
 
 io.redirect other                                    # "#<IO:fd 20>"
-io.redirect(other) { |stream| stream.write "test" }  # "#<IO:fd 21>"
+io.redirect(other) { |stream| stream.write "demo" }  # "#<IO:fd 21>"
 ----
 
 ===== #reread
@@ -748,15 +793,15 @@ Answers full stream by rewinding to beginning of stream and reading all content.
 
 [source,ruby]
 ----
-io = IO.new IO.sysopen(Pathname("test.txt").to_s, "w+")
-io.write "This is a test."
+io = IO.new IO.sysopen(Pathname("demo.txt").to_s, "w+")
+io.write "This is a demo."
 
-io.reread                  # "This is a test."
+io.reread                  # "This is a demo."
 io.reread 4                # "This"
 
 buffer = "".dup
-io.reread(buffer: buffer)  # "This is a test."
-buffer                     # "This is a test."
+io.reread(buffer: buffer)  # "This is a demo."
+buffer                     # "This is a demo."
 ----
 
 ===== #squelch
@@ -1355,6 +1400,26 @@ Example.with_positions 1, 2, 3  # #<struct a=1, b=2, c=3>
 Example.with_positions 1        # #<struct a=1, b=nil, c=nil>
 ----
 
+===== #diff
+
+Allows you to obtain the differences between two objects.
+
+[source,ruby]
+----
+implementation = Struct.new :a, :b, :c
+
+one = implementation.new a: 1, b: 2, c: 3
+two = implementation.new a: 3, b: 2, c: 1
+three = Struct.new(:x, :y).new x: 1, y: 2
+
+one.diff one         # {}
+one.diff two         # {:a=>[1, 3], :c=>[3, 1]}
+one.diff three       # {:a=>[1, nil], :b=>[2, nil], :c=>[3, nil]}
+one.diff Object.new  # {:a=>[1, nil], :b=>[2, nil], :c=>[3, nil]}
+----
+
+Any object that _is not_ the same type will have a `nil` value as shown in the last two examples.
+
 ===== #merge
 
 Merges multiple attributes without mutating itself and supports any object that responds to `#to_h`.

data/lib/refinements/data.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "refinements/shared/values/diff"
+
+module Refinements
+  # Provides additional enhancements to the Struct primitive.
+  module Data
+    refine ::Data do
+      import_methods Shared::Values::Diff
+    end
+  end
+end

data/lib/refinements/hashes.rb

@@ -45,6 +45,12 @@ module Refinements
 
       def deep_symbolize_keys! = replace(deep_symbolize_keys)
 
+      def diff other
+        return differences_from other if other.is_a?(self.class) && keys.sort! == other.keys.sort!
+
+        each.with_object({}) { |(key, value), diff| diff[key] = [value, nil] }
+      end
+
       def fetch_value(key, *default_value, &) = fetch(key, *default_value, &) || default_value.first
 
       def flatten_keys prefix: nil, delimiter: "_"
@@ -88,6 +94,13 @@ module Refinements
              .map { |(_type, key)| self[key] || self[key.to_s] }
              .then { |values| yield values }
       end
+
+      private
+
+      def differences_from other
+        result = merge(other.to_h) { |_, one, two| [one, two].uniq }
+        result.select { |_, diff| diff.size == 2 }
+      end
     end
   end
 end

data/lib/refinements/shared/values/diff.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Refinements
+  module Shared
+    module Values
+      # Provides shared whole value functionality for knowing the difference between two objects.
+      module Diff
+        def diff other
+          if other.is_a? self.class
+            to_h.merge(other.to_h) { |_, one, two| [one, two].uniq }
+                .select { |_, diff| diff.size == 2 }
+          else
+            to_h.each.with_object({}) { |(key, value), diff| diff[key] = [value, nil] }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/refinements/structs.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "refinements/shared/values/diff"
+
 module Refinements
   # Provides additional enhancements to the Struct primitive.
   module Structs
@@ -8,6 +10,8 @@ module Refinements
     end
 
     refine Struct do
+      import_methods Shared::Values::Diff
+
       def merge(...) = dup.merge!(...)
 
       def merge! object = nil

data/lib/refinements.rb

@@ -2,6 +2,7 @@
 
 require "refinements/arrays"
 require "refinements/big_decimals"
+require "refinements/data"
 require "refinements/date_times"
 require "refinements/hashes"
 require "refinements/ios"

data/refinements.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "refinements"
-  spec.version = "11.0.0"
+  spec.version = "11.1.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: 11.0.0
+  version: 11.1.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -35,7 +35,7 @@ cert_chain:
   3n5C8/6Zh9DYTkpcwPSuIfAga6wf4nXc9m6JAw8AuMLaiWN/r/2s4zJsUHYERJEu
   gZGm4JqtuSg8pYjPeIJxS960owq+SfuC+jxqmRA54BisFCv/0VOJi7tiJVY=
   -----END CERTIFICATE-----
-date: 2023-06-13 00:00:00.000000000 Z
+date: 2023-08-15 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -51,6 +51,7 @@ files:
 - lib/refinements.rb
 - lib/refinements/arrays.rb
 - lib/refinements/big_decimals.rb
+- lib/refinements/data.rb
 - lib/refinements/date_times.rb
 - lib/refinements/hashes.rb
 - lib/refinements/ios.rb
@@ -59,6 +60,7 @@ files:
 - lib/refinements/pathnames.rb
 - lib/refinements/shared/enumerables/many.rb
 - lib/refinements/shared/ios/reread.rb
+- lib/refinements/shared/values/diff.rb
 - lib/refinements/string_ios.rb
 - lib/refinements/strings.rb
 - lib/refinements/structs.rb
@@ -90,7 +92,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.14
+rubygems_version: 3.4.18
 signing_key:
 specification_version: 4
 summary: A collection of core Ruby object refinements.